View Javadoc

1   /*
2    * Copyright 2000-2002,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  // package
18  package org.apache.jetspeed.services.statemanager;
19  
20  // imports
21  import javax.servlet.http.HttpSession;
22  
23  /***
24  * <p>The StateManagerService is a service that manages SessionState information.
25  * Each SessionState is identified by a unique key in this service.  The SessionState
26  * is composed of name - value sets of attributes, stored under the key by the service.</p>
27  * <p>See the proposal: jakarta-jetspeed/proposals/StateManager.txt for more details.</p>
28  * <p>Attribute values placed into SessionStates may be automatically removed, for example when
29  * a SessionState expires in some way, or by means of some other automatic service.  These value
30  * objects can be notified of their placement into and out of the SessionState.  Objects that wish
31  * to receive this notification implement the SessionStateBindingListener interface.  This is based
32  * on and similar to the HttpSessionBindingListener mechanism.</p>
33  * <p>To support the "current" routines; the ability to get a session state based
34  * on the current http session, this service must be installed properly into the
35  * procssing of each http request.  At the start of the request, the HttpSession
36  * of the request must be passed into the setCurrentContext() method.  At the end
37  * of the request, clearCurrentContext() is called.  For Jetspeed, this is done in
38  * the JetspeedRunDataService, which is always going to be called by Turbine in this
39  * way.</p>
40  * @version $Revision: 1.5 $
41  * @see org.apache.jetspeed.services.statemanager.SessionState
42  * @see org.apache.jetspeed.services.statemanager.SessionStateBindingListener
43  * @author <a href="mailto:ggolden@apache.org">Glenn R. Golden</a>
44  */
45  public interface StateManagerService
46  {
47      /*** The name used to find the service in the service manager. */
48      public String SERVICE_NAME = "StateManagerService";
49  
50      /***
51      * Access the named attribute of the keyed state.
52      * @param key The state key.
53      * @param name The attribute name.
54      * @return The named attribute value of the keyed state.
55      */
56      public Object getAttribute ( String key, String name );
57  
58      /***
59      * Set the named state attribute of the keyed state with the provided object.
60      * @param key The state key.
61      * @param name The attribute name.
62      * @param value The new value of the attribute (any object type).
63      */
64      public void setAttribute( String key, String name, Object value );
65  
66      /***
67      * Remove the named state attribute of the keyed state, if it exists.
68      * @param key The state key.
69      * @param name The attribute name.
70      */
71      public void removeAttribute( String key, String name );
72  
73      /***
74      * Remove all state attribute of the keyed state.
75      * @param key The state key.
76      */
77      public void clear( String key );
78  
79      /***
80      * Access an array of all names of attributes stored in the keyed state.
81      * @param key The state key.
82      * @return An array of all names of attributes stored in the keyed state.
83      */
84      public String[] getAttributeNames( String key );
85  
86      /***
87      * Access an SessionState object with the given key.
88      * @param key The SessionState key.
89      * @return an SessionState object with the given key.
90      */
91      public SessionState getSessionState( String key );
92  
93      /***
94      * Access the SessionState object associated with the current request's http session.
95  	* The session id is used as the key.
96      * @return an SessionState object associated with the current request's http session.
97      */
98      public SessionState getCurrentSessionState();
99  
100     /***
101     * Access the SessionState object associated with the current request's http session with the given key.
102 	* @param key The string to add to the session id to form the SessionState key.
103     * @return an SessionState object associated with the current request's http session with the given key.
104     */
105     public SessionState getCurrentSessionState( String key );
106 
107     /***
108     * Retire, forget about and clean up all states that start with the given key.
109     * @param keyStart The beginning of the key of the states to clean up.
110     */
111     public void retireState( String keyStart );
112 
113     /***
114     * Set the "current" context for this thread -
115     * Call this at the start of each request, and call %%% at the end.
116     * getCurrentSession() uses this for the session state key.
117     * @param session the HttpSession of the current request.
118     */
119     public void setCurrentContext( HttpSession session );
120 
121     /***
122     * Clear the "current context for this thread -
123     * Call at the end of each request, balanced with calls to setCurrentContext()
124     */
125     public void clearCurrentContext();
126 
127 }   // interface StateManagerService
128 
129 /***********************************************************************************
130 *
131 * $Header: /home/cvs/jakarta-jetspeed/src/java/org/apache/jetspeed/services/statemanager/StateManagerService.java,v 1.5 2004/02/23 03:38:28 jford Exp $
132 *
133 **********************************************************************************/
134