javax.portlet.PortletSession Maven / Gradle / Ivy
/* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you 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.
*/
/*
* NOTE: this source code is based on an early draft version of JSR 286 and not intended for product
* implementations. This file may change or vanish in the final version of the JSR 286 specification.
*/
/*
* This source code implements specifications defined by the Java
* Community Process. In order to remain compliant with the specification
* DO NOT add / change / or delete method signatures!
*/
/**
* Copyright 2006 IBM Corporation.
*/
package javax.portlet;
import java.util.Map;
/**
* The PortletSession interface provides a way to identify a user
* across more than one request and to store transient information about that user.
*
* A PortletSession is created per user client per portlet application.
*
* A portlet can bind an object attribute into a PortletSession by name.
* The PortletSession interface defines two scopes for storing objects:
*
* APPLICATION_SCOPE
* PORTLET_SCOPE
*
* All objects stored in the session using the APPLICATION_SCOPE
* must be available to all the portlets, servlets and
* JSPs that belongs to the same portlet application and that handles a
* request identified as being a part of the same session.
* Objects stored in the session using the PORTLET_SCOPE must be
* available to the portlet during requests for the same portlet window
* that the objects where stored from. Attributes stored in the
* PORTLET_SCOPE are not protected from other web components
* of the portlet application. They are just conveniently namespaced.
*
* The portlet session is based on the HttpSession. Therefore all
* HttpSession listeners do apply to the portlet session and
* attributes set in the portlet session are visible in the HttpSession
* and vice versa.
*/
public interface PortletSession
{
/**
* This constant defines an application wide scope for the session attribute.
* APPLICATION_SCOPE session attributes enable Portlets
* within one portlet application to share data.
*
* Portlets may need to prefix attributes set in this scope with some
* ID, to avoid overwriting each other's attributes in the
* case where two portlets of the same portlet definition
* are created.
*
* Value: 0x01
*/
public static final int APPLICATION_SCOPE = 0x01;
/**
* This constant defines the scope of the session attribute to be
* private to the portlet and its included resources.
*
* Value: 0x02
*/
public static final int PORTLET_SCOPE = 0x02;
/**
* Returns the object bound with the specified name in this session
* under the PORTLET_SCOPE, or null if no
* object is bound under the name in that scope.
*
* @param name a string specifying the name of the object
*
* @return the object with the specified name for
* the PORTLET_SCOPE.
*
* @exception java.lang.IllegalStateException if this method is called on an
* invalidated session.
* @exception java.lang.IllegalArgumentException
* if name is null.
*/
public java.lang.Object getAttribute(java.lang.String name);
/**
* Returns the object bound with the specified name in this session,
* or null if no object is bound under the name in the given scope.
*
* @param name a string specifying the name of the object
* @param scope session scope of this attribute
*
* @return the object with the specified name
*
* @exception java.lang.IllegalStateException if this method is called on an
* invalidated session, or the scope is unknown to the container.
* @exception java.lang.IllegalArgumentException
* if name is null.
*/
public java.lang.Object getAttribute(java.lang.String name,int scope);
/**
* Returns an Enumeration of String objects containing the names of
* all the objects bound to this session under the PORTLET_SCOPE, or an
* empty Enumeration if no attributes are available.
*
* @return an Enumeration of
* String objects specifying the
* names of all the objects bound to
* this session, or an empty Enumeration
* if no attributes are available.
*
* @exception java.lang.IllegalStateException if this method is called on an
* invalidated session
*/
public java.util.Enumeration getAttributeNames();
/**
* Returns an Enumeration of String objects containing the names of
* all the objects bound to this session in the given scope, or an
* empty Enumeration if no attributes are available in the
* given scope.
*
* @param scope session scope of the attribute names
*
* @return an Enumeration of
* String objects specifying the
* names of all the objects bound to
* this session, or an empty Enumeration
* if no attributes are available in the given scope.
*
* @exception java.lang.IllegalStateException if this method is called on an
* invalidated session, or the scope is unknown to the container.
*/
public java.util.Enumeration getAttributeNames(int scope);
/**
* Returns the time when this session was created, measured in
* milliseconds since midnight January 1, 1970 GMT.
*
* @return a long specifying
* when this session was created,
* expressed in
* milliseconds since 1/1/1970 GMT
*
* @exception java.lang.IllegalStateException if this method is called on an
* invalidated session
*/
public long getCreationTime();
/**
* Returns a string containing the unique identifier assigned to this session.
*
* @return a string specifying the identifier
* assigned to this session
*/
public java.lang.String getId();
/**
* Returns the last time the client sent a request associated with this session,
* as the number of milliseconds since midnight January 1, 1970 GMT.
*
* Actions that your portlet takes, such as getting or setting
* a value associated with the session, do not affect the access
* time.
*
* @return a long
* representing the last time
* the client sent a request associated
* with this session, expressed in
* milliseconds since 1/1/1970 GMT
*/
public long getLastAccessedTime();
/**
* Returns the maximum time interval, in seconds, for which the portlet container
* keeps this session open between client accesses. After this interval,
* the portlet container invalidates the session. The maximum time
* interval can be set
* with the setMaxInactiveInterval method.
* A negative time indicates the session should never timeout.
*
* @return an integer specifying the number of
* seconds this session remains open
* between client requests
*
* @see #setMaxInactiveInterval
*/
public int getMaxInactiveInterval();
/**
* Invalidates this session (all scopes) and unbinds any objects bound to it.
*
* Invalidating the portlet session will result in invalidating the underlying
* HttpSession
*
* @exception java.lang.IllegalStateException if this method is called on a
* session which has already been invalidated
*/
public void invalidate();
/**
* Returns true if the client does not yet know about the session or
* if the client chooses not to join the session.
*
* @return true if the
* server has created a session,
* but the client has not joined yet.
*
* @exception java.lang.IllegalStateException if this method is called on a
* session which has already been invalidated
*
*/
public boolean isNew();
/**
* Removes the object bound with the specified name under
* the PORTLET_SCOPE from
* this session. If the session does not have an object
* bound with the specified name, this method does nothing.
*
* @param name the name of the object to be
* removed from this session in the
* PORTLET_SCOPE.
*
* @exception java.lang.IllegalStateException
* if this method is called on a
* session which has been invalidated
* @exception java.lang.IllegalArgumentException
* if name is null.
*/
public void removeAttribute(String name) ;
/**
* Removes the object bound with the specified name and the given scope from
* this session. If the session does not have an object
* bound with the specified name, this method does nothing.
*
* @param name the name of the object to be
* removed from this session
* @param scope session scope of this attribute
*
* @exception java.lang.IllegalStateException
* if this method is called on a
* session which has been invalidated
* @exception java.lang.IllegalArgumentException
* if name is null.
*/
public void removeAttribute(String name, int scope) ;
/**
* Binds an object to this session under the PORTLET_SCOPE, using the name specified.
* If an object of the same name in this scope is already bound to the session,
* that object is replaced.
*
*
After this method has been executed, 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
* that implements HttpSessionBindingListener, its
* HttpSessionBindingListener.valueUnbound method is called.
*
*
If the value is null, this has the same effect as calling
* removeAttribute().
*
*
* @param name the name to which the object is bound under
* the PORTLET_SCOPE;
* this cannot be null.
* @param value the object to be bound
*
* @exception java.lang.IllegalStateException if this method is called on a
* session which has been invalidated
* @exception java.lang.IllegalArgumentException
* if name is null.
*/
public void setAttribute(java.lang.String name, java.lang.Object value);
/**
* Binds an object to this session in the given scope, using the name specified.
* If an object of the same name in this scope is already bound to the session,
* that object is replaced.
*
*
After this method has been executed, 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
* that implements HttpSessionBindingListener, its
* HttpSessionBindingListener.valueUnbound method is called.
*
*
If the value is null, this has the same effect as calling
* removeAttribute().
*
*
* @param name the name to which the object is bound;
* this cannot be null.
* @param value the object to be bound
* @param scope session scope of this attribute
*
* @exception java.lang.IllegalStateException if this method is called on a
* session which has been invalidated
* @exception java.lang.IllegalArgumentException
* if name is null or scope is unknown to the container.
*/
public void setAttribute(java.lang.String name, java.lang.Object value, int scope);
/**
* Specifies the time, in seconds, between client requests, before the
* portlet container invalidates this session. A negative time
* indicates the session should never timeout.
*
* @param interval An integer specifying the number
* of seconds
*/
public void setMaxInactiveInterval(int interval);
/**
* Returns the portlet application context associated with this session.
*
* @return the portlet application context
*/
public PortletContext getPortletContext ();
/**
* Returns a Map of the session attributes in
* the portlet session scope.
*
* The keys are of type String and the values in the
* returned Map are from type Object.
*
* If no session attributes exist this method returns an empty Map.
*
* @return an immutable Map containing the session attributes in the
* portlet session scope as keys and attribute values as map values, or an empty Map
* if no session attributes exist. The keys in the
* map are of type String, the values of type
* Object.
* @since 2.0
*/
public Map getAttributeMap();
/**
* Returns a Map of the session attributes in
* the given session scope.
*
* The keys are of type String and the values in the
* returned Map are from type Object.
*
* If no session attributes exist this method returns an empty Map.
*
* @param scope session scope of this attribute
*
* @return an immutable Map containing the session attributes in the
* given scope as keys and attribute values as map values, or an empty Map
* if no session attributes exist. The keys in the
* map are of type String, the values of type
* Object.
* @since 2.0
*/
public Map getAttributeMap(int scope);
}