001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.environment;
018:
019: import java.util.Enumeration;
020:
021: /**
022: *
023: * Provides a way to identify a user across more than one page
024: * request or visit to a Web site and to store information about that user.
025: *
026: * <p>Cocoon uses this interface to create a session
027: * between a client and the "cocoon server". The session persists
028: * for a specified time period, across more than one connection or
029: * page request from the user. A session usually corresponds to one
030: * user, who may visit a site many times. The server can maintain a
031: * session in many ways such as using cookies or rewriting URLs.
032: *
033: * <p>This interface allows Cocoon to
034: * <ul>
035: * <li>View and manipulate information about a session, such as
036: * the session identifier, creation time, and last accessed time
037: * <li>Bind objects to sessions, allowing user information to persist
038: * across multiple user connections
039: * </ul>
040: *
041: * <p>Session information is scoped only to the current context
042: * (<code>Context</code>), so information stored in one context
043: * will not be directly visible in another.
044: *
045: * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
046: * @version CVS $Id: Session.java 433543 2006-08-22 06:22:54Z crossley $
047: *
048: */
049:
050: public interface Session {
051:
052: /**
053: *
054: * Returns the time when this session was created, measured
055: * in milliseconds since midnight January 1, 1970 GMT.
056: *
057: * @return a <code>long</code> specifying
058: * when this session was created,
059: * expressed in
060: * milliseconds since 1/1/1970 GMT
061: *
062: * @exception IllegalStateException if this method is called on an
063: * invalidated session
064: *
065: */
066: long getCreationTime();
067:
068: /**
069: *
070: * Returns a string containing the unique identifier assigned
071: * to this session. The identifier is assigned
072: * by the context container and is implementation dependent.
073: *
074: * @return a string specifying the identifier
075: * assigned to this session
076: *
077: * @exception IllegalStateException if this method is called on an
078: * invalidated session
079: *
080: */
081: String getId();
082:
083: /**
084: *
085: * Returns the last time the client sent a request associated with
086: * this session, as the number of milliseconds since midnight
087: * January 1, 1970 GMT.
088: *
089: * <p>Actions that your application takes, such as getting or setting
090: * a value associated with the session, do not affect the access
091: * time.
092: *
093: * @return a <code>long</code>
094: * representing the last time
095: * the client sent a request associated
096: * with this session, expressed in
097: * milliseconds since 1/1/1970 GMT
098: *
099: * @exception IllegalStateException if this method is called on an
100: * invalidated session
101: *
102: */
103:
104: long getLastAccessedTime();
105:
106: /**
107: *
108: * Specifies the time, in seconds, between client requests before the
109: * contextcontainer will invalidate this session. A negative time
110: * indicates the session should never timeout.
111: *
112: * @param interval An integer specifying the number
113: * of seconds
114: *
115: */
116: void setMaxInactiveInterval(int interval);
117:
118: /**
119: * Returns the maximum time interval, in seconds, that
120: * the context container will keep this session open between
121: * client accesses. After this interval, the context container
122: * will invalidate the session. The maximum time interval can be set
123: * with the <code>setMaxInactiveInterval</code> method.
124: * A negative time indicates the session should never timeout.
125: *
126: *
127: * @return an integer specifying the number of
128: * seconds this session remains open
129: * between client requests
130: *
131: * @see #setMaxInactiveInterval(int)
132: *
133: *
134: */
135: int getMaxInactiveInterval();
136:
137: /**
138: *
139: * Returns the object bound with the specified name in this session, or
140: * <code>null</code> if no object is bound under the name.
141: *
142: * @param name a string specifying the name of the object
143: *
144: * @return the object with the specified name
145: *
146: * @exception IllegalStateException if this method is called on an
147: * invalidated session
148: *
149: */
150: Object getAttribute(String name);
151:
152: /**
153: *
154: * Returns an <code>Enumeration</code> of <code>String</code> objects
155: * containing the names of all the objects bound to this session.
156: *
157: * @return an <code>Enumeration</code> of
158: * <code>String</code> objects specifying the
159: * names of all the objects bound to
160: * this session
161: *
162: * @exception IllegalStateException if this method is called on an
163: * invalidated session
164: *
165: */
166: Enumeration getAttributeNames();
167:
168: /**
169: * Binds an object to this session, using the name specified.
170: * If an object of the same name is already bound to the session,
171: * the object is replaced.
172: *
173: *
174: * @param name the name to which the object is bound;
175: * cannot be null
176: *
177: * @param value the object to be bound; cannot be null
178: *
179: * @exception IllegalStateException if this method is called on an
180: * invalidated session
181: *
182: */
183: void setAttribute(String name, Object value);
184:
185: /**
186: *
187: * Removes the object bound with the specified name from
188: * this session. If the session does not have an object
189: * bound with the specified name, this method does nothing.
190: *
191: *
192: * @param name the name of the object to
193: * remove from this session
194: *
195: * @exception IllegalStateException if this method is called on an
196: * invalidated session
197: */
198: void removeAttribute(String name);
199:
200: /**
201: *
202: * Invalidates this session
203: * to it.
204: *
205: * @exception IllegalStateException if this method is called on an
206: * already invalidated session
207: *
208: */
209: void invalidate();
210:
211: /**
212: *
213: * Returns <code>true</code> if the client does not yet know about the
214: * session or if the client chooses not to join the session. For
215: * example, if the server used only cookie-based sessions, and
216: * the client had disabled the use of cookies, then a session would
217: * be new on each request.
218: *
219: * @return <code>true</code> if the
220: * server has created a session,
221: * but the client has not yet joined
222: *
223: * @exception IllegalStateException if this method is called on an
224: * already invalidated session
225: *
226: */
227: boolean isNew();
228:
229: }
|