    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    }