Author: vtence Date: Tue Jan 25 19:25:30 2005 New Revision: 126460 URL: http://svn.apache.org/viewcvs?view=rev&rev=126460 Log: Added some documentation Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/IdentityInUseException.java incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/MutableRealm.java incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/Realm.java
Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/IdentityInUseException.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/IdentityInUseException.java?view=diff&rev=126460&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/IdentityInUseException.java&r1=126459&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/IdentityInUseException.java&r2=126460 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/IdentityInUseException.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/IdentityInUseException.java Tue Jan 25 19:25:30 2005 @@ -17,10 +17,12 @@ package org.apache.authx.authentication.realm; import org.apache.authx.authentication.CredentialSet; +import org.apache.authx.AuthXException; + /** * @author <a href="mailto:[EMAIL PROTECTED]">Apache Directory Project</a> */ -public class IdentityInUseException extends Exception +public class IdentityInUseException extends AuthXException { private final CredentialSet m_identity; Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/MutableRealm.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/MutableRealm.java?view=diff&rev=126460&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/MutableRealm.java&r1=126459&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/MutableRealm.java&r2=126460 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/MutableRealm.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/MutableRealm.java Tue Jan 25 19:25:30 2005 @@ -19,9 +19,28 @@ import org.apache.authx.authentication.CredentialSet; /** + * Realm implementations that support addition of new identities + * should implement this interface. + * <p> + * Identities are unique within the realm, by rules that are + * internal to the realm implementation. For example, in the case + * of username/password identification, the username is the identity + * discriminator. Mutable implementations + * should throw [EMAIL PROTECTED] IdentityInUseException} to prevent + * conflicting identities to reside in the realm. + * * @author <a href="mailto:[EMAIL PROTECTED]">Apache Directory Project</a> */ public interface MutableRealm extends Realm { + /** + * Adds a new identity to this realm. + * + * @param credentials The credentials that uniquely describe the identity + * @throws IdentityInUseException if another credential set in the realm already + * refers to the same identity. + * @throws UnsupportedCredentialsException if this realm does not support + * the provided credentials + */ void addIdentity( CredentialSet credentials ) throws IdentityInUseException; } Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/Realm.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/Realm.java?view=diff&rev=126460&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/Realm.java&r1=126459&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/Realm.java&r2=126460 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/Realm.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm/Realm.java Tue Jan 25 19:25:30 2005 @@ -21,9 +21,28 @@ import java.security.Principal; /** + * A Realm is a grouping of identities, which are + * represented by <code>Principal</code>s. Each identity + * is unique in the realm. + * <p> + * In order to authenticate against a realm, a proof of identity + * in the form of a [EMAIL PROTECTED] CredentialSet} must be presented. + * The result of authentication is the <code>Principal</code> object. + * <p> + * As an example, in the case of username/password authentication, the + * <code>CredentialSet</code> might comprise a username and a password + * and the realm could return a username principal. + * * @author <a href="mailto:[EMAIL PROTECTED]">Apache Directory Project</a> */ public interface Realm { + /** + * Validates a subject's identity against this realm. + * + * @param credentials The proof of identity + * @return the Principal identity or null if the given credential set + * is not matched in the realm + */ Principal validateCredentials( CredentialSet credentials ); }
