svn commit: r126460 - incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/realm

[vt...@apache.org]

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:directory-dev@incubator.apache.org">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 {@link IdentityInUseException} to prevent
+ * conflicting identities to reside in the realm.
+ *
  * @author <a href="mailto:directory-dev@incubator.apache.org">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 {@link 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:directory-dev@incubator.apache.org">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 );
 }