    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.services;
    014
    015import org.apache.tapestry5.ioc.ObjectLocator;
    016import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
    017
    018/**
    019 * Responsible for managing <em>session state objects</em>, objects which persist between requests, but are not tied to
    020 * any individual page or component. SSOs are also created on demand. SSOs are typically stored in the session, so that
    021 * they are specific to a particular client.
    022 *
    023 * The term "Application" is a hold-over from Tapestry 5.0, which used the @ApplicationState (deprecated and deleted)
    024 * annotation, and called them "ASOs" (Application State Objects). This service would be better named
    025 * "SessionStateManager" (but renaming it would cause backwards compatibility issues).
    026 *
    027 * Tapestry has a built-in default strategy for storing SSOs (in the session) and instantiating them. If desired,
    028 * contributions to the service configuration can override the default behavior, either specifying an alternate storage
    029 * strategy, or an alternate {@linkplain org.apache.tapestry5.services.ApplicationStateCreator creation strategy}.
    030 *
    031 * @see org.apache.tapestry5.annotations.SessionState
    032 */
    033@UsesMappedConfiguration(key = Class.class, value = ApplicationStateContribution.class)
    034public interface ApplicationStateManager
    035{
    036    /**
    037     * For a given class, find the SSO for the class, creating it if necessary. The manager has a configuration that
    038     * determines how an instance is stored and created as needed. The default (when there is no configuration for
    039     * a SSO type) is to instantiate the object with injected dependencies, via {@link ObjectLocator#autobuild(Class)}.
    040     * This
    041     * allows an SSO to keep references to Tapestry IoC services or other objects that can be injected.
    042     *
    043     * @param ssoClass
    044     *            identifies the SSO to access or create
    045     * @return the SSO instance
    046     */
    047    <T> T get(Class<T> ssoClass);
    048
    049    /**
    050     * For a given class, find the SSO for the class. The manager has a configuration that determines how an instance is
    051     * stored.
    052     *
    053     * @param ssoClass
    054     *            identifies the SSO to access or create
    055     * @return the SSO instance or null if it does not already exist
    056     */
    057    <T> T getIfExists(Class<T> ssoClass);
    058
    059    /**
    060     * Returns true if the SSO already exists, false if it has not yet been created.
    061     *
    062     * @param ssoClass
    063     *            used to select the SSO
    064     * @return true if SSO exists, false if null
    065     */
    066    <T> boolean exists(Class<T> ssoClass);
    067
    068    /**
    069     * Stores a new SSO, replacing the existing SSO (if any). Storing the value null will delete the SSO so that it may
    070     * be re-created later.
    071     *
    072     * @param ssoClass
    073     *            the type of SSO
    074     * @param SSO
    075     *            the SSO instance
    076     */
    077    <T> void set(Class<T> ssoClass, T SSO);
    078}