    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}