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