001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/presence/tags/sakai_2-4-1/presence-api/api/src/java/org/sakaiproject/presence/api/PresenceService.java $
003: * $Id: PresenceService.java 18354 2006-11-21 20:42:33Z josrodri@iupui.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.presence.api;
021:
022: import java.util.List;
023:
024: /**
025: * <p>
026: * A PresenceService keeps track of a session's presence at various locations in the system.
027: * </p>
028: * <p>
029: * Location is a combination of site id, (optional) page id and (optional) tool id
030: * </p>
031: */
032: public interface PresenceService {
033: /** This string starts the references to resources in this service. */
034: static final String REFERENCE_ROOT = "/presence";
035:
036: /** Name for the event of establishing presence at a location. */
037: static final String EVENT_PRESENCE = "pres.begin";
038:
039: /** Name for the event of ending presence at a location. */
040: static final String EVENT_ABSENCE = "pres.end";
041:
042: /**
043: * Form a presence reference from a location id
044: *
045: * @param id
046: * the location id.
047: * @return A presence reference based on a location id.
048: */
049: String presenceReference(String id);
050:
051: /**
052: * Construct a location id from site, page, and tool.
053: *
054: * @param site
055: * The site id.
056: * @param page
057: * The page id (optional).
058: * @param tool
059: * The tool id (optional).
060: * @return a Location Id.
061: */
062: String locationId(String site, String page, String tool);
063:
064: /**
065: * Form a description for the location.
066: *
067: * @param location
068: * The presence location.
069: * @return A description for the location.
070: */
071: String getLocationDescription(String location);
072:
073: /**
074: * Establish or refresh the presence of the current session in a location.
075: *
076: * @param session
077: * The session object.
078: * @param locationId
079: * A presence location id.
080: */
081: void setPresence(String locationId);
082:
083: /**
084: * Remove the presence of the current session from a location.
085: *
086: * @param session
087: * The session object.
088: * @param locationId
089: * A presence location id.
090: */
091: void removePresence(String locationId);
092:
093: /**
094: * Access a List of sessions (UsageSession) now present in a location.
095: *
096: * @param locationId
097: * A presence location id.
098: * @return The a List of sessions (UsageSession) now present in the location (may be empty).
099: */
100: List getPresence(String locationId);
101:
102: /**
103: * Access a List of users (User) now present in a location.
104: *
105: * @param locationId
106: * A presence location id.
107: * @return The a List of users (User) now present in the location (may be empty).
108: */
109: List getPresentUsers(String locationId);
110:
111: /**
112: * Access a List of users (User) now present in a location.
113: *
114: * @param locationId
115: * A presence location id.
116: * @param siteId
117: * A siteId (added when integrating PrivacyManager)
118: *
119: * @return The a List of users (User) now present in the location (may be empty).
120: */
121: List getPresentUsers(String locationId, String siteId);
122:
123: /**
124: * Access a List of all location ids (String).
125: *
126: * @return The List of all location ids (Strings) (may be empty).
127: */
128: List getLocations();
129:
130: /**
131: * Access the time (in seconds) after which a presence will timeout.
132: *
133: * @return The time (seconds) after which a presence will timeout.
134: */
135: int getTimeout();
136: }
|