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}