001    // Copyright 2007, 2008 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.annotations.UsesMappedConfiguration;
018    
019    /**
020     * Responsible for managing <em>session state objects</em>, objects which persist between requests, but are not tied to
021     * any individual page or component. SSOs are also created on demand. SSOs are typically stored in the session, so that
022     * they are specific to a particular client.
023     * <p/>
024     * The term "Application" is a hold-over from Tapestry 5.0, which used the {@link ApplicationState} annotation, and
025     * called them "ASOs" (Application State Objects).
026     * <p/>
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.ApplicationState
032     */
033    @UsesMappedConfiguration(key = Class.class, value = ApplicationStateContribution.class)
034    public 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. A requested SSO not in the configuration is assumed
039         * to be created via a no-args constructor, and stored in the session.
040         *
041         * @param <T>
042         * @param ssoClass identifies the SSO to access or create
043         * @return the SSO instance
044         */
045        <T> T get(Class<T> ssoClass);
046    
047        /**
048         * For a given class, find the SSO for the class. The manager has a configuration that determines how an instance is
049         * stored.
050         *
051         * @param <T>
052         * @param ssoClass identifies the SSO to access or create
053         * @return the SSO instance or null if it does not already exist
054         */
055        <T> T getIfExists(Class<T> ssoClass);
056    
057        /**
058         * Returns true if the SSO already exists, false if it has not yet been created.
059         *
060         * @param ssoClass used to select the SSO
061         * @return true if SSO exists, false if null
062         */
063        <T> boolean exists(Class<T> ssoClass);
064    
065        /**
066         * Stores a new SSO, replacing the existing SSO (if any). Storing the value null will delete the SSO so that it may
067         * be re-created later.
068         *
069         * @param <T>
070         * @param ssoClass the type of SSO
071         * @param SSO      the SSO instance
072         */
073        <T> void set(Class<T> ssoClass, T SSO);
074    }