001: /*
002: * Copyright 2005 Joe Walker
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.directwebremoting;
017:
018: import java.util.Iterator;
019:
020: import javax.servlet.http.HttpSession;
021:
022: /**
023: * Script scope is like session scope except that it is managed using a
024: * Javascript variable.
025: * The operations on a Page are similar to (and derived from) the options on a
026: * Session, with some added simplification.
027: * @see javax.servlet.http.HttpSession
028: * @author Joe Walker [joe at getahead dot ltd dot uk]
029: */
030: public interface ScriptSession {
031: /**
032: * Returns the object bound with the specified name in this session, or
033: * <code>null</code> if no object is bound under the name.
034: * @param name a string specifying the name of the object
035: * @return the object with the specified name
036: * @throws IllegalStateException if the page has been invalidated
037: */
038: Object getAttribute(String name);
039:
040: /**
041: * Binds an object to this session, using the name specified.
042: * If an object of the same name is already bound to the session, the
043: * object is replaced.
044: * <p>After this method executes, and if the new object implements
045: * <code>HttpSessionBindingListener</code>, the container calls
046: * <code>HttpSessionBindingListener.valueBound</code>. The container then
047: * notifies any <code>HttpSessionAttributeListener</code>s in the web
048: * application.
049: * <p>If an object was already bound to this session of this name that
050: * implements <code>HttpSessionBindingListener</code>, its
051: * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
052: * <p>If the value passed in is null, this has the same effect as calling
053: * <code>removeAttribute()<code>.
054: * @param name the name to which the object is bound; cannot be null
055: * @param value the object to be bound
056: * @throws IllegalStateException if the page has been invalidated
057: */
058: void setAttribute(String name, Object value);
059:
060: /**
061: * Removes the object bound with the specified name from this session.
062: * If the session does not have an object bound with the specified name,
063: * this method does nothing.
064: * <p>After this method executes, and if the object implements
065: * <code>HttpSessionBindingListener</code>, the container calls
066: * <code>HttpSessionBindingListener.valueUnbound</code>. The container
067: * then notifies any <code>HttpSessionAttributeListener</code>s in the web
068: * application.
069: * @param name the name of the object to remove from this session
070: * @throws IllegalStateException if the page has been invalidated
071: */
072: void removeAttribute(String name);
073:
074: /**
075: * Returns an <code>Enumeration</code> of <code>String</code> objects
076: * containing the names of all the objects bound to this session.
077: * @return an <code>Iterator</code> of <code>String</code>s, specifying the
078: * names of all the objects bound to this session
079: * @throws IllegalStateException if the page has been invalidated
080: */
081: Iterator<String> getAttributeNames();
082:
083: /**
084: * Invalidates this session then unbinds any objects bound to it.
085: * @throws IllegalStateException if the page has been invalidated
086: */
087: void invalidate();
088:
089: /**
090: * Checks to see if this ScriptSession has been invalidated.
091: * <p>There is no similar method on {@link HttpSession} because it is
092: * assumed that you do not store HttpSessions from one request to another,
093: * so all sessions that you have access to will always be either valid, or
094: * you have just invalidated it yourself so you wont need to ask. This
095: * method makes up for the change that now ScriptSessions are accessible
096: * from outside the normal scope.
097: * @return true if the ScriptSession has been invalidated
098: */
099: boolean isInvalidated();
100:
101: /**
102: * Add a script to the list waiting for remote execution.
103: * The version automatically wraps the string in a ClientScript object.
104: * @param script The script to execute
105: */
106: void addScript(ScriptBuffer script);
107:
108: /**
109: * Returns a string containing the unique identifier assigned to this
110: * session. The identifier is assigned by the servlet container and is
111: * implementation dependent.
112: * @return a string specifying the identifier assigned to this session
113: * @throws IllegalStateException if the page has been invalidated
114: */
115: String getId();
116:
117: /**
118: * Returns the time when this session was created, measured in milliseconds
119: * since midnight January 1, 1970 GMT.
120: * @return when was this page created, in milliseconds since 1/1/1970 GMT
121: * @throws IllegalStateException if the page has been invalidated
122: */
123: long getCreationTime();
124:
125: /**
126: * Returns the last time the client sent a request associated with this
127: * session, as the number of milliseconds since 1/1/1970 GMT, and marked by
128: * the time the container received the request.
129: * <p>Actions that your application takes, such as getting or setting a
130: * value associated with the session, do not affect the access time.
131: * @return when was this page last accessed, in milliseconds since 1/1/1970 GMT
132: * @throws IllegalStateException if the page has been invalidated
133: */
134: long getLastAccessedTime();
135:
136: /**
137: * What page is this script session attached to?
138: * The page does not include server information, but does include everything
139: * from the host/port onwards, including the query parameters depending on
140: * the configured {@link org.directwebremoting.extend.PageNormalizer}, which
141: * by default removes them.
142: * @return The page that this script session is viewing
143: */
144: String getPage();
145: }
|