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