001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: RememberManager.java 3643 2007-01-12 15:29:45Z gbevin $
007: */
008: package com.uwyn.rife.authentication;
009:
010: import com.uwyn.rife.authentication.exceptions.RememberManagerException;
011:
012: /**
013: * This interface defines the methods that classes with
014: * {@code RememberManager} functionalities have to implement.
015: * <p>A {@code RememberManager} is reponsible for coupling a user ID to
016: * an expiring remember ID. The remember ID is typically stored in a cookie in
017: * the browser and expires after a certain duration. An authentication element
018: * that uses a {@code RememberManager}, should erase the remember ID
019: * after using it once, create a new one immediately and send it to the
020: * client. This ensures that each remember ID can only be used once.
021: *
022: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
023: * @version $Revision: 3643 $
024: * @see com.uwyn.rife.authentication.credentials.RememberMe
025: * @since 1.0
026: */
027: public interface RememberManager {
028: /**
029: * Obtains the maximum time that a remember ID can be used before it
030: * becomes invalid.
031: *
032: * @return The maximum lifetime in milliseconds.
033: * @since 1.0
034: */
035: public long getRememberDuration();
036:
037: /**
038: * Sets the maximum time that a remember ID can be used before it becomes
039: * invalid.
040: *
041: * @param milliseconds The lifetime in milliseconds.
042: * @since 1.0
043: */
044: public void setRememberDuration(long milliseconds);
045:
046: /**
047: * Starts a new session.
048: *
049: * @param userId The ID that uniquely identifies the user that has to be
050: * remembered.
051: * @param hostIp The ip address of the host from which the user accesses
052: * the application.
053: * @return A {@code String} that uniquely identifies the remembered
054: * user ID.
055: * @exception RememberManagerException An undefined number of exceptional
056: * cases or error situations can occur when a remember ID is created. They
057: * are all indicated by throwing an instance of
058: * {@code RememberManagerException}. It's up to the implementations
059: * of this interface to give more specific meanings to these exceptions.
060: * @since 1.0
061: */
062: public String createRememberId(long userId, String hostIp)
063: throws RememberManagerException;
064:
065: /**
066: * Removes one particular remember ID. This makes it instantly invalid.
067: *
068: * @param rememberId The remember ID that needs to be erased.
069: * @return {@code true} if the ID was successfully erased; or
070: * <p>{@code false} if this was not possible.
071: * @exception RememberManagerException An undefined number of exceptional
072: * cases or error situations can occur when a remember ID is erased. They
073: * are all indicated by throwing an instance of
074: * {@code RememberManagerException}. It's up to the implementations
075: * of this interface to give more specific meanings to these exceptions.
076: * @since 1.0
077: */
078: public boolean eraseRememberId(String rememberId)
079: throws RememberManagerException;
080:
081: /**
082: * Removes all remember IDs for a particular user. This makes all issued
083: * remember IDs instantly invalid.
084: *
085: * @param userId The id that uniquely identifies the user whose remember
086: * IDs are to be erased.
087: * @return {@code true} if the IDs were successfully erased; or
088: * <p>{@code false} if this was not possible
089: * @exception RememberManagerException An undefined number of exceptional
090: * cases or error situations can occur when a remember ID is erased. They
091: * are all indicated by throwing an instance of
092: * {@code RememberManagerException}. It's up to the implementations
093: * of this interface to give more specific meanings to these exceptions.
094: * @since 1.0
095: */
096: public boolean eraseUserRememberIds(long userId)
097: throws RememberManagerException;
098:
099: /**
100: * Removes all available remember ID. This makes all existing remember IDs
101: * instantly invalid and unusable for all users.
102: *
103: * @exception RememberManagerException An undefined number of exceptional
104: * cases or error situations can occur when a remember ID is erased. They
105: * are all indicated by throwing an instance of
106: * {@code RememberManagerException}. It's up to the implementations
107: * of this interface to give more specific meanings to these exceptions.
108: * @since 1.0
109: */
110: public void eraseAllRememberIds() throws RememberManagerException;
111:
112: /**
113: * Retrieves the user ID that corresponds to a certain remember ID.
114: *
115: * @param rememberId The remember ID that maps to the user ID.
116: * @return the ID of the user that corresponds to the provided remember
117: * ID; or
118: * <p>{@code -1} if no user ID corresponds to the provided remember
119: * ID.
120: * @exception RememberManagerException An undefined number of exceptional
121: * cases or error situations can occur when a user ID is retrieved. They
122: * are all indicated by throwing an instance of
123: * {@code RememberManagerException}. It's up to the implementations
124: * of this interface to give more specific meanings to these exceptions.
125: * @since 1.0
126: */
127: public long getRememberedUserId(String rememberId)
128: throws RememberManagerException;
129:
130: /**
131: * Removes all remember IDs that are expired. This means that all remember
132: * IDs where the lifetime has been exceeded, will be removed.
133: *
134: * @exception RememberManagerException An undefined number of exceptional
135: * cases or error situations can occur when a remember ID is purged. They
136: * are all indicated by throwing an instance of
137: * {@code RememberManagerException}. It's up to the implementations
138: * of this interface to give more specific meanings to these exceptions.
139: * @since 1.0
140: */
141: public void purgeRememberIds() throws RememberManagerException;
142: }
|