001 // Copyright 2007, 2008, 2010 The Apache Software Foundation002 //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 at006 //007 // http://www.apache.org/licenses/LICENSE-2.0008 //009 // Unless required by applicable law or agreed to in writing, software010 // 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 and013 // limitations under the License.014015 package org.apache.tapestry5.services;016017 import org.apache.tapestry5.ioc.ObjectLocator;018 import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;019020 /**021 * Responsible for managing <em>session state objects</em>, objects which persist between requests, but are not tied to022 * any individual page or component. SSOs are also created on demand. SSOs are typically stored in the session, so that023 * 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 named027 * "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 storage031 * strategy, or an alternate {@linkplain org.apache.tapestry5.services.ApplicationStateCreator creation strategy}.032 * 033 * @see org.apache.tapestry5.annotations.SessionState034 */035 @UsesMappedConfiguration(key = Class.class, value = ApplicationStateContribution.class)036 public interface ApplicationStateManager037 {038 /**039 * For a given class, find the SSO for the class, creating it if necessary. The manager has a configuration that040 * determines how an instance is stored and created as needed. The default (when there is no configuration for041 * a SSO type) is to instantiate the object with injected dependencies, via {@link ObjectLocator#autobuild(Class)}.042 * This043 * allows an SSO to keep references to Tapestry IoC services or other objects that can be injected.044 * 045 * @param ssoClass046 * identifies the SSO to access or create047 * @return the SSO instance048 */049 <T> T get(Class<T> ssoClass);050051 /**052 * For a given class, find the SSO for the class. The manager has a configuration that determines how an instance is053 * stored.054 * 055 * @param ssoClass056 * identifies the SSO to access or create057 * @return the SSO instance or null if it does not already exist058 */059 <T> T getIfExists(Class<T> ssoClass);060061 /**062 * Returns true if the SSO already exists, false if it has not yet been created.063 * 064 * @param ssoClass065 * used to select the SSO066 * @return true if SSO exists, false if null067 */068 <T> boolean exists(Class<T> ssoClass);069070 /**071 * Stores a new SSO, replacing the existing SSO (if any). Storing the value null will delete the SSO so that it may072 * be re-created later.073 * 074 * @param ssoClass075 * the type of SSO076 * @param SSO077 * the SSO instance078 */079 <T> void set(Class<T> ssoClass, T SSO);080 }