portletsession.java.svn-base

portal越来越流行了

/*  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 <CODE>PortletSession</CODE> interface provides a way to identify a user
 * across more than one request and to store transient information about that user.
 * <p>
 * A <code>PortletSession</code> is created per user client per portlet application.
 * <p>
 * A portlet can bind an object attribute into a <code>PortletSession</code> by name.
 * The <code>PortletSession</code> interface defines two scopes for storing objects:
 * <ul>
 * <li><code>APPLICATION_SCOPE</code>
 * <li><code>PORTLET_SCOPE</code>
 * </ul>
 * All objects stored in the session using the <code>APPLICATION_SCOPE</code> 
 * 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 <code>PORTLET_SCOPE</code> must be
 * available to the portlet during requests for the same portlet window
 * that the objects where stored from. Attributes stored in the
 * <code>PORTLET_SCOPE</code> are not protected from other web components
 * of the portlet application. They are just conveniently namespaced.
 * <P>
 * The portlet session is based on the <code>HttpSession</code>. Therefore all
 * <code>HttpSession</code> listeners do apply to the portlet session and
 * attributes set in the portlet session are visible in the <code>HttpSession</code>
 * and vice versa.
 */
public interface PortletSession
{

  /**
   * This constant defines an application wide scope for the session attribute.
   * <code>APPLICATION_SCOPE</code> session attributes enable Portlets 
   * within one portlet application to share data.
   * <p>
   * 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.
   * <p>
   * Value: <code>0x01</code>
   */
  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. 
   * <p>
   * Value: <code>0x02</code>
   */
  public static final int PORTLET_SCOPE = 0x02;



  /**
   * Returns the object bound with the specified name in this session
   * under the <code>PORTLET_SCOPE</code>, or <code>null</code> 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 <code>PORTLET_SCOPE</code>.
   *
   * @exception java.lang.IllegalStateException	if this method is called on an
   *					invalidated session.
   * @exception  java.lang.IllegalArgumentException 
   *                            if name is <code>null</code>.
   */

  public java.lang.Object getAttribute(java.lang.String name);

  
  /**
   * Returns the object bound with the specified name in this session, 
   * or <code>null</code> 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 <code>null</code>.
   */

  public java.lang.Object getAttribute(java.lang.String name,int scope);


  /**
   * Returns an <code>Enumeration</code> of String objects containing the names of 
   * all the objects bound to this session under the <code>PORTLET_SCOPE</code>, or an
   * empty <code>Enumeration</code> if no attributes are available.
   *
   * @return			an <code>Enumeration</code> of 
   *				<code>String</code> objects specifying the
   *				names of all the objects bound to
   *				this session, or an empty <code>Enumeration</code> 
   *                if no attributes are available.
   *
   * @exception java.lang.IllegalStateException	if this method is called on an
   *					invalidated session   
   */
  
  public java.util.Enumeration<String> getAttributeNames();


  /**
   * Returns an <code>Enumeration</code> of String objects containing the names of 
   * all the objects bound to this session in the given scope, or an
   * empty <code>Enumeration</code> if no attributes are available in the
   * given scope.
   *
   * @param scope               session scope of the attribute names
   *
   * @return			an <code>Enumeration</code> of 
   *				<code>String</code> objects specifying the
   *				names of all the objects bound to
   *				this session, or an empty <code>Enumeration</code> 
   *                            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<String> getAttributeNames(int scope);

  /**
   * Returns the time when this session was created, measured in 
   * milliseconds since midnight January 1, 1970 GMT.  
   *
   * @return				a <code>long</code> 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.  
   *
   * <p>Actions that your portlet takes, such as getting or setting
   * a value associated with the session, do not affect the access
   * time.
   *
   * @return				a <code>long</code>
   *					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,