Home » apache-tomcat-6.0.26-src » org.apache » catalina » [javadoc | source]

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    * 
    9    *      http://www.apache.org/licenses/LICENSE-2.0
   10    * 
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   
   18   
   19   package org.apache.catalina;
   20   
   21   
   22   import java.security.Principal;
   23   import java.util.Iterator;
   24   
   25   import javax.servlet.http.HttpSession;
   26   
   27   
   28   /**
   29    * A <b>Session</b> is the Catalina-internal facade for an
   30    * <code>HttpSession</code> that is used to maintain state information
   31    * between requests for a particular user of a web application.
   32    *
   33    * @author Craig R. McClanahan
   34    * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (Tue, 24 Oct 2006) $
   35    */
   36   
   37   public interface Session {
   38   
   39   
   40       // ----------------------------------------------------- Manifest Constants
   41   
   42   
   43       /**
   44        * The SessionEvent event type when a session is created.
   45        */
   46       public static final String SESSION_CREATED_EVENT = "createSession";
   47   
   48   
   49       /**
   50        * The SessionEvent event type when a session is destroyed.
   51        */
   52       public static final String SESSION_DESTROYED_EVENT = "destroySession";
   53   
   54   
   55       /**
   56        * The SessionEvent event type when a session is activated.
   57        */
   58       public static final String SESSION_ACTIVATED_EVENT = "activateSession";
   59   
   60   
   61       /**
   62        * The SessionEvent event type when a session is passivated.
   63        */
   64       public static final String SESSION_PASSIVATED_EVENT = "passivateSession";
   65   
   66   
   67       // ------------------------------------------------------------- Properties
   68   
   69   
   70       /**
   71        * Return the authentication type used to authenticate our cached
   72        * Principal, if any.
   73        */
   74       public String getAuthType();
   75   
   76   
   77       /**
   78        * Set the authentication type used to authenticate our cached
   79        * Principal, if any.
   80        *
   81        * @param authType The new cached authentication type
   82        */
   83       public void setAuthType(String authType);
   84   
   85   
   86       /**
   87        * Return the creation time for this session.
   88        */
   89       public long getCreationTime();
   90   
   91   
   92       /**
   93        * Set the creation time for this session.  This method is called by the
   94        * Manager when an existing Session instance is reused.
   95        *
   96        * @param time The new creation time
   97        */
   98       public void setCreationTime(long time);
   99   
  100   
  101       /**
  102        * Return the session identifier for this session.
  103        */
  104       public String getId();
  105   
  106   
  107       /**
  108        * Return the session identifier for this session.
  109        */
  110       public String getIdInternal();
  111   
  112   
  113       /**
  114        * Set the session identifier for this session.
  115        *
  116        * @param id The new session identifier
  117        */
  118       public void setId(String id);
  119   
  120   
  121       /**
  122        * Return descriptive information about this Session implementation and
  123        * the corresponding version number, in the format
  124        * <code>&lt;description&gt;/&lt;version&gt;</code>.
  125        */
  126       public String getInfo();
  127   
  128   
  129       /**
  130        * Return the last time the client sent a request associated with this
  131        * session, as the number of milliseconds since midnight, January 1, 1970
  132        * GMT.  Actions that your application takes, such as getting or setting
  133        * a value associated with the session, do not affect the access time.
  134        */
  135       public long getLastAccessedTime();
  136   
  137       /**
  138        * Return the last client access time without invalidation check
  139        * @see #getLastAccessedTime().
  140        */
  141       public long getLastAccessedTimeInternal();
  142   
  143       /**
  144        * Return the Manager within which this Session is valid.
  145        */
  146       public Manager getManager();
  147   
  148   
  149       /**
  150        * Set the Manager within which this Session is valid.
  151        *
  152        * @param manager The new Manager
  153        */
  154       public void setManager(Manager manager);
  155   
  156   
  157       /**
  158        * Return the maximum time interval, in seconds, between client requests
  159        * before the servlet container will invalidate the session.  A negative
  160        * time indicates that the session should never time out.
  161        */
  162       public int getMaxInactiveInterval();
  163   
  164   
  165       /**
  166        * Set the maximum time interval, in seconds, between client requests
  167        * before the servlet container will invalidate the session.  A negative
  168        * time indicates that the session should never time out.
  169        *
  170        * @param interval The new maximum interval
  171        */
  172       public void setMaxInactiveInterval(int interval);
  173   
  174   
  175       /**
  176        * Set the <code>isNew</code> flag for this session.
  177        *
  178        * @param isNew The new value for the <code>isNew</code> flag
  179        */
  180       public void setNew(boolean isNew);
  181   
  182   
  183       /**
  184        * Return the authenticated Principal that is associated with this Session.
  185        * This provides an <code>Authenticator</code> with a means to cache a
  186        * previously authenticated Principal, and avoid potentially expensive
  187        * <code>Realm.authenticate()</code> calls on every request.  If there
  188        * is no current associated Principal, return <code>null</code>.
  189        */
  190       public Principal getPrincipal();
  191   
  192   
  193       /**
  194        * Set the authenticated Principal that is associated with this Session.
  195        * This provides an <code>Authenticator</code> with a means to cache a
  196        * previously authenticated Principal, and avoid potentially expensive
  197        * <code>Realm.authenticate()</code> calls on every request.
  198        *
  199        * @param principal The new Principal, or <code>null</code> if none
  200        */
  201       public void setPrincipal(Principal principal);
  202   
  203   
  204       /**
  205        * Return the <code>HttpSession</code> for which this object
  206        * is the facade.
  207        */
  208       public HttpSession getSession();
  209   
  210   
  211       /**
  212        * Set the <code>isValid</code> flag for this session.
  213        *
  214        * @param isValid The new value for the <code>isValid</code> flag
  215        */
  216       public void setValid(boolean isValid);
  217   
  218   
  219       /**
  220        * Return the <code>isValid</code> flag for this session.
  221        */
  222       public boolean isValid();
  223   
  224   
  225       // --------------------------------------------------------- Public Methods
  226   
  227   
  228       /**
  229        * Update the accessed time information for this session.  This method
  230        * should be called by the context when a request comes in for a particular
  231        * session, even if the application does not reference it.
  232        */
  233       public void access();
  234   
  235   
  236       /**
  237        * Add a session event listener to this component.
  238        */
  239       public void addSessionListener(SessionListener listener);
  240   
  241   
  242       /**
  243        * End access to the session.
  244        */
  245       public void endAccess();
  246   
  247   
  248       /**
  249        * Perform the internal processing required to invalidate this session,
  250        * without triggering an exception if the session has already expired.
  251        */
  252       public void expire();
  253   
  254   
  255       /**
  256        * Return the object bound with the specified name to the internal notes
  257        * for this session, or <code>null</code> if no such binding exists.
  258        *
  259        * @param name Name of the note to be returned
  260        */
  261       public Object getNote(String name);
  262   
  263   
  264       /**
  265        * Return an Iterator containing the String names of all notes bindings
  266        * that exist for this session.
  267        */
  268       public Iterator getNoteNames();
  269   
  270   
  271       /**
  272        * Release all object references, and initialize instance variables, in
  273        * preparation for reuse of this object.
  274        */
  275       public void recycle();
  276   
  277   
  278       /**
  279        * Remove any object bound to the specified name in the internal notes
  280        * for this session.
  281        *
  282        * @param name Name of the note to be removed
  283        */
  284       public void removeNote(String name);
  285   
  286   
  287       /**
  288        * Remove a session event listener from this component.
  289        */
  290       public void removeSessionListener(SessionListener listener);
  291   
  292   
  293       /**
  294        * Bind an object to a specified name in the internal notes associated
  295        * with this session, replacing any existing binding for this name.
  296        *
  297        * @param name Name to which the object should be bound
  298        * @param value Object to be bound to the specified name
  299        */
  300       public void setNote(String name, Object value);
  301   
  302   
  303   }

Home » apache-tomcat-6.0.26-src » org.apache » catalina » [javadoc | source]