ScriptSession


1   /*
2    * Copyright 2005 Joe Walker
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  package org.directwebremoting;
17  
18  import java.util.Iterator  ;
19  
20  import javax.servlet.http.HttpSession  ;
21  
22  /**
23   * Script scope is like session scope except that it is managed using a
24   * Javascript variable.
25   * The operations on a Page are similar to (and derived from) the options on a
26   * Session, with some added simplification.
27   * @see javax.servlet.http.HttpSession
28   * @author Joe Walker [joe at getahead dot ltd dot uk]
29   */
30  public interface ScriptSession
31  {
32      /**
33       * Returns the object bound with the specified name in this session, or
34       * <code>null</code> if no object is bound under the name.
35       * @param name a string specifying the name of the object
36       * @return the object with the specified name
37       * @throws IllegalStateException if the page has been invalidated
38       */
39      Object   getAttribute(String   name);
40  
41      /**
42       * Binds an object to this session, using the name specified.
43       * If an object of the same name is already bound to the session, the
44       * object is replaced.
45       * <p>After this method executes, and if the new object implements
46       * <code>HttpSessionBindingListener</code>, the container calls
47       * <code>HttpSessionBindingListener.valueBound</code>. The container then
48       * notifies any <code>HttpSessionAttributeListener</code>s in the web
49       * application.
50       * <p>If an object was already bound to this session of this name that
51       * implements <code>HttpSessionBindingListener</code>, its
52       * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
53       * <p>If the value passed in is null, this has the same effect as calling
54       * <code>removeAttribute()<code>.
55       * @param name the name to which the object is bound; cannot be null
56       * @param value the object to be bound
57       * @throws IllegalStateException if the page has been invalidated
58       */
59      void setAttribute(String   name, Object   value);
60  
61      /**
62       * Removes the object bound with the specified name from this session.
63       * If the session does not have an object bound with the specified name,
64       * this method does nothing.
65       * <p>After this method executes, and if the object implements
66       * <code>HttpSessionBindingListener</code>, the container calls
67       * <code>HttpSessionBindingListener.valueUnbound</code>. The container
68       * then notifies any <code>HttpSessionAttributeListener</code>s in the web
69       * application.
70       * @param name the name of the object to remove from this session
71       * @throws IllegalStateException if the page has been invalidated
72       */
73      void removeAttribute(String   name);
74  
75      /**
76       * Returns an <code>Enumeration</code> of <code>String</code> objects
77       * containing the names of all the objects bound to this session.
78       * @return an <code>Iterator</code> of <code>String</code>s, specifying the
79       *     names of all the objects bound to this session
80       * @throws IllegalStateException if the page has been invalidated
81       */
82      Iterator   getAttributeNames();
83  
84      /**
85       * Invalidates this session then unbinds any objects bound to it.
86       * @throws IllegalStateException if the page has been invalidated
87       */
88      void invalidate();
89  
90      /**
91       * Checks to see if this ScriptSession has been invalidated.
92       * <p>There is no similar method on {@link HttpSession} because it is
93       * assumed that you do not store HttpSessions from one request to another,
94       * so all sessions that you have access to will always be either valid, or
95       * you have just invalidated it yourself so you wont need to ask. This
96       * method makes up for the change that now ScriptSessions are accessible
97       * from outside the normal scope.
98       * @return true if the ScriptSession has been invalidated
99       */
100     boolean isInvalidated();
101 
102     /**
103      * Add a script to the list waiting for remote execution.
104      * The version automatically wraps the string in a ClientScript object.
105      * @param script The script to execute
106      */
107     void addScript(ScriptBuffer script);
108 
109     /**
110      * Returns a string containing the unique identifier assigned to this
111      * session. The identifier is assigned by the servlet container and is
112      * implementation dependent.
113      * @return a string specifying the identifier assigned to this session
114      * @throws IllegalStateException if the page has been invalidated
115      */
116     String   getId();
117 
118     /**
119      * Returns the time when this session was created, measured in milliseconds
120      * since midnight January 1, 1970 GMT.
121      * @return when was this page created, in milliseconds since 1/1/1970 GMT
122      * @throws IllegalStateException if the page has been invalidated
123      */
124     long getCreationTime();
125 
126     /**
127      * Returns the last time the client sent a request associated with this
128      * session, as the number of milliseconds since 1/1/1970 GMT, and marked by
129      * the time the container recieved the request.
130      * <p>Actions that your application takes, such as getting or setting a
131      * value associated with the session, do not affect the access time.
132      * @return when was this page last accessed, in milliseconds since 1/1/1970 GMT
133      * @throws IllegalStateException if the page has been invalidated
134      */
135     long getLastAccessedTime();
136 }
137
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags