org.directwebremoting.ScriptSession Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2005 Joe Walker
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.directwebremoting;

import java.util.Iterator;

import javax.servlet.http.HttpSession;

/**
 * Script scope is like session scope except that it is managed using a
 * Javascript variable.
 * The operations on a Page are similar to (and derived from) the options on a
 * Session, with some added simplification.
 * @see javax.servlet.http.HttpSession
 * @author Joe Walker [joe at getahead dot ltd dot uk]
 */
public interface ScriptSession
{
    /**
     * Returns the object bound with the specified name in this session, or
     * null if no object is bound under the name.
     * @param name a string specifying the name of the object
     * @return the object with the specified name
     * @throws IllegalStateException if the page has been invalidated
     */
    Object getAttribute(String name);

    /**
     * Binds an object to this session, using the name specified.
     * If an object of the same name is already bound to the session, the
     * object is replaced.
     * After this method executes, and if the new object implements
     * HttpSessionBindingListener, the container calls
     * HttpSessionBindingListener.valueBound. The container then
     * notifies any HttpSessionAttributeListeners in the web
     * application.
     * 
If an object was already bound to this session of this name that
     * implements HttpSessionBindingListener, its
     * HttpSessionBindingListener.valueUnbound method is called.
     * 
If the value passed in is null, this has the same effect as calling
     * removeAttribute().
     * @param name the name to which the object is bound; cannot be null
     * @param value the object to be bound
     * @throws IllegalStateException if the page has been invalidated
     */
    void setAttribute(String name, Object value);

    /**
     * Removes the object bound with the specified name from this session.
     * If the session does not have an object bound with the specified name,
     * this method does nothing.
     * 
After this method executes, and if the object implements
     * HttpSessionBindingListener, the container calls
     * HttpSessionBindingListener.valueUnbound. The container
     * then notifies any HttpSessionAttributeListeners in the web
     * application.
     * @param name the name of the object to remove from this session
     * @throws IllegalStateException if the page has been invalidated
     */
    void removeAttribute(String name);

    /**
     * Returns an Enumeration of String objects
     * containing the names of all the objects bound to this session.
     * @return an Iterator of Strings, specifying the
     *     names of all the objects bound to this session
     * @throws IllegalStateException if the page has been invalidated
     */
    Iterator getAttributeNames();

    /**
     * Invalidates this session then unbinds any objects bound to it.
     * @throws IllegalStateException if the page has been invalidated
     */
    void invalidate();

    /**
     * Checks to see if this ScriptSession has been invalidated.
     * 
There is no similar method on {@link HttpSession} because it is
     * assumed that you do not store HttpSessions from one request to another,
     * so all sessions that you have access to will always be either valid, or
     * you have just invalidated it yourself so you wont need to ask. This
     * method makes up for the change that now ScriptSessions are accessible
     * from outside the normal scope.
     * @return true if the ScriptSession has been invalidated
     */
    boolean isInvalidated();

    /**
     * Add a script to the list waiting for remote execution.
     * The version automatically wraps the string in a ClientScript object.
     * @param script The script to execute
     */
    void addScript(ScriptBuffer script);

    /**
     * Returns a string containing the unique identifier assigned to this
     * session. The identifier is assigned by the servlet container and is
     * implementation dependent.
     * @return a string specifying the identifier assigned to this session
     * @throws IllegalStateException if the page has been invalidated
     */
    String getId();

    /**
     * Returns the time when this session was created, measured in milliseconds
     * since midnight January 1, 1970 GMT.
     * @return when was this page created, in milliseconds since 1/1/1970 GMT
     * @throws IllegalStateException if the page has been invalidated
     */
    long getCreationTime();

    /**
     * Returns the last time the client sent a request associated with this
     * session, as the number of milliseconds since 1/1/1970 GMT, and marked by
     * the time the container recieved the request.
     * 
Actions that your application takes, such as getting or setting a
     * value associated with the session, do not affect the access time.
     * @return when was this page last accessed, in milliseconds since 1/1/1970 GMT
     * @throws IllegalStateException if the page has been invalidated
     */
    long getLastAccessedTime();
}