001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/event/tags/sakai_2-4-1/event-api/api/src/java/org/sakaiproject/event/api/UsageSessionService.java $
003: * $Id: UsageSessionService.java 15113 2006-09-21 19:11:42Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.event.api;
021:
022: import java.util.List;
023: import java.util.Map;
024:
025: import javax.servlet.http.HttpServletRequest;
026:
027: import org.sakaiproject.user.api.Authentication;
028:
029: /**
030: * <p>
031: * UsageSessionService keeps track of usage sessions.
032: * </p>
033: */
034: public interface UsageSessionService {
035: /** Name for the event of logging in. */
036: public static final String EVENT_LOGIN = "user.login";
037:
038: /** Name for the event of logging out. */
039: public static final String EVENT_LOGOUT = "user.logout";
040:
041: /** Name for the global cookie to store the session */
042: public static final String SAKAI_SESSION_COOKIE = "sakai.session";
043:
044: /**
045: * Name for the session key to retrieve the UsageSession.
046: * Note: This must be a constant and not based on classname - it must stay the same regardless of the name of the implementing class.
047: */
048: public static final String USAGE_SESSION_KEY = "org.sakaiproject.event.api.UsageSessionService";
049:
050: /**
051: * Establish a usage session associated with the current request or thread.
052: *
053: * @param userId
054: * The user id.
055: * @param remoteAddress
056: * The IP address from the user is making a request.
057: * @param userAgent
058: * The string describing the user's browser.
059: * @return The new UsageSession, or null if one could not be created.
060: */
061: UsageSession startSession(String userId, String remoteAddress,
062: String userAgent);
063:
064: /**
065: * Access the usage session associated with the current request or thread.
066: *
067: * @return The UsageSession object holding the information about this session.
068: */
069: UsageSession getSession();
070:
071: /**
072: * Access the session id from the usage session associated with the current request or thread, or null if no session.
073: *
074: * @return The session id from the usage session associated with the current request or thread, or null if no session.
075: */
076: String getSessionId();
077:
078: /**
079: * Access a SessionState object with the given key associated with the current usage session.
080: *
081: * @param key
082: * The SessionState key.
083: * @return an SessionState object with the given key.
084: */
085: SessionState getSessionState(String key);
086:
087: /**
088: * Indicate recent user activity on the current usage session - user initiated or auto. Maintains the initiated activity timeout mechanism.
089: *
090: * @param auto
091: * if true, activity from an automatic event, otherwise from a user initiated event.
092: * @return The current usage session (may be just closed).
093: */
094: UsageSession setSessionActive(boolean auto);
095:
096: /**
097: * Access a usage session (may be other than the current one) by id.
098: *
099: * @param id
100: * the Session id.
101: * @return The UsageSession object for this id, or null if not defined.
102: */
103: UsageSession getSession(String id);
104:
105: /**
106: * Access a List of usage sessions by List of ids.
107: *
108: * @param ids
109: * the List (String) of Session ids.
110: * @return The List (UsageSession) of UsageSession object for these ids.
111: */
112: List getSessions(List ids);
113:
114: /**
115: * Access a List of usage sessions by *arbitrary criteria* for te session ids.
116: *
117: * @param joinTable
118: * the table name to (inner) join to
119: * @param joinAlias
120: * the alias used in the criteria string for the joinTable
121: * @param joinColumn
122: * the column name of the joinTable that is to match the session id in the join ON clause
123: * @param joinCriteria
124: * the criteria of the select (after the where)
125: * @param fields
126: * Optional values to go with the criteria in an implementation specific way.
127: * @return The List (UsageSession) of UsageSession object for these ids.
128: */
129: List getSessions(String joinTable, String joinAlias,
130: String joinColumn, String joinCriteria, Object[] values);
131:
132: /**
133: * Access the time (seconds) we will wait for any user generated request from a session before we consider the session inactive.
134: *
135: * @return the time (seconds) used for session inactivity detection.
136: */
137: int getSessionInactiveTimeout();
138:
139: /**
140: * Access the time (seconds) we will wait for hearing anyting from a session before we consider the session lost.
141: *
142: * @return the time (seconds) used for lost session detection.
143: */
144: int getSessionLostTimeout();
145:
146: /**
147: * Access a list of all open sessions.
148: *
149: * @return a List (UsageSession) of all open sessions, ordered by server, then by start (asc)
150: */
151: List getOpenSessions();
152:
153: /**
154: * Access a list of all open sessions, grouped by server.
155: *
156: * @return a Map (server id -> List (UsageSession)) of all open sessions, ordered by server, then by start (asc)
157: */
158: Map getOpenSessionsByServer();
159:
160: /**
161: * Start a usage session and do any other book-keeping needed to login a user who has already been authenticated.
162: *
163: * @param authn
164: * The user authentication.
165: * @param req
166: * The servlet request.
167: * @return true if all went well, false if not (may fail if the userId is not a valid User)
168: */
169: boolean login(Authentication authn, HttpServletRequest req);
170:
171: /**
172: * End a usage session and otherwise cleanup from a login.
173: *
174: */
175: void logout();
176: }
|