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: SessionValidator.java 3643 2007-01-12 15:29:45Z gbevin $
007: */
008: package com.uwyn.rife.authentication;
009:
010: import com.uwyn.rife.authentication.SessionManager;
011: import com.uwyn.rife.authentication.exceptions.SessionValidatorException;
012:
013: /**
014: * This interface defines the methods that classes with
015: * {@code SessionValidator} functionalities have to implement.
016: * <p>
017: * A {@code SessionValidator} is essentially a bridge between a
018: * {@code CredentialsManager} and a {@code SessionManager}. The
019: * validity of a session is often dependent on external attributes which define
020: * the context for a valid session that goes beyond a valid session id.
021: * <p>
022: * Typical uses can be:
023: * <ul>
024: * <li>a user can become blocked during an active session,</li>
025: * <li>a user is a member of different groups (roles) and only
026: * has access to certain resources when being part of a
027: * particular group,</li>
028: * <li>a user needs to provide information at the first valid log-in,
029: * without providing this information the user can't access any
030: * of the resources in the application.</li>
031: * </ul>
032: * <p>
033: * All these scenarios require additional information and additional processing
034: * that are often specific to each implementation of a
035: * {@code CredentialsManager}.
036: * <p>
037: * Since any {@code CredentialsManager} can be combined with any
038: * {@code SessionManager}, performance would often not be optimal.
039: * <p>
040: * For example, if the credentials and the session information are stored in the
041: * same database. Completely isolating all fuctionalities would cause more
042: * database queries to be executed than what's really needed. By implementing
043: * the combined functionality of verifying a valid authentication session in a
044: * bridge class that implements the {@code SessionValidator} interface,
045: * only one query can be used to provide the same results. Thus, dramatically
046: * increasing performance.
047: *
048: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
049: * @version $Revision: 3643 $
050: * @see com.uwyn.rife.authentication.sessionvalidators.AbstractSessionValidator
051: * @see com.uwyn.rife.authentication.SessionAttributes
052: * @see com.uwyn.rife.authentication.CredentialsManager
053: * @see com.uwyn.rife.authentication.SessionManager
054: * @since 1.0
055: */
056: public interface SessionValidator {
057: /**
058: * Validates an existing session according to a set of attributes that
059: * define the context in which this validation occurs.
060: * <p>
061: * This method is typically executed for each access to a secured resource,
062: * performance is thus of critical importance.
063: * <p>
064: * The implementation of this method should be optimal for the combination
065: * of the used {@code CredentialsManager} and
066: * {@code SessionManager}. Specific code that combines the features of
067: * both managers should be written, instead of relying on the abstracted api
068: * of each manager. Paying attention to the implementation of this method
069: * can dramatically reduce the overhead of securing resources.
070: *
071: * @param authId The unique id of the authentication session that needs
072: * to be validated.
073: * @param hostIp The ip address of the host from which the user accesses
074: * the application.
075: * @param attributes Access to the attributes that define that context
076: * in which the session has to be validated.
077: *
078: * @return A number that indicates the validation state of the session.
079: * This allows the application to go beyond <em>valid</em> or
080: * <em>invalid</em>. Additional states like for example : <em>blocked</em>,
081: * <em>initial login</em> and <em>disabled</em>, can be used by using
082: * different numbers.
083: *
084: * @throws SessionValidatorException An undefined number of exceptional
085: * cases or error situations can occur when a session is validated. They are
086: * all indicated by throwing an instance of
087: * {@code SessionValidatorException}. It's up to the implementations of
088: * this interface to give more specific meanings to these exceptions.
089: *
090: * @since 1.0
091: */
092: public int validateSession(String authId, String hostIp,
093: SessionAttributes attributes)
094: throws SessionValidatorException;
095:
096: /**
097: * Indicates if the provided validity identifier is considered as
098: * <em>valid</em> and that the access to the secured resource is thus
099: * authorized.
100: * <p>
101: * Normally, specific business logic is only required for the situations in
102: * which access has prohibited. This method is used to make it possible to
103: * provide automatic access to the secured resource.
104: *
105: * @param id The numeric identifier that is returned by the
106: * {@code validateSession} method.
107: *
108: * @return {@code true} if access to the secured resource was
109: * authorized; or
110: * <p>
111: * {@code false} if access was prohibited.
112: *
113: * @since 1.0
114: */
115: public boolean isAccessAuthorized(int id);
116:
117: /**
118: * Sets the {@code CredentialsManager} that will be used.
119: *
120: * @param credentialsManager The new {@code CredentialsManager}.
121: *
122: * @since 1.0
123: */
124: public void setCredentialsManager(
125: CredentialsManager credentialsManager);
126:
127: /**
128: * Retrieves the currently used {@code CredentialsManager}.
129: *
130: * @return The current {@code CredentialsManager}.
131: *
132: * @since 1.0
133: */
134: public CredentialsManager getCredentialsManager();
135:
136: /**
137: * Sets the {@code SessionManager} that will be used.
138: *
139: * @param sessionManager The new {@code SessionManager}.
140: *
141: * @since 1.0
142: */
143: public void setSessionManager(SessionManager sessionManager);
144:
145: /**
146: * Retrieves the currently used {@code SessionManager}.
147: *
148: * @return The current {@code SessionManager}.
149: *
150: * @since 1.0
151: */
152: public SessionManager getSessionManager();
153:
154: /**
155: * Sets the {@code RememberManager} that will be used.
156: *
157: * @param rememberManager The new {@code RememberManager}.
158: *
159: * @since 1.0
160: */
161: public void setRememberManager(RememberManager rememberManager);
162:
163: /**
164: * Retrieves the currently used {@code RememberManager}.
165: *
166: * @return The current {@code RememberManager}.
167: *
168: * @since 1.0
169: */
170: public RememberManager getRememberManager();
171: }
|