Author: vtence Date: Tue Jan 25 05:09:08 2005 New Revision: 126380 URL: http://svn.apache.org/viewcvs?view=rev&rev=126380 Log: Documentation Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/AuthXException.java incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Authenticator.java incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Credential.java incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/CredentialSet.java incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Authorizer.java incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Permission.java incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultAuthorizer.java incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultRule.java
Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/AuthXException.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/AuthXException.java?view=diff&rev=126380&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/AuthXException.java&r1=126379&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/AuthXException.java&r2=126380 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/AuthXException.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/AuthXException.java Tue Jan 25 05:09:08 2005 @@ -16,6 +16,10 @@ */ package org.apache.authx; +/** + * Superclass for all exceptions in AuthX. Not to be thrown directly, but + * you can use it to catch all AuthX exceptions. + */ public abstract class AuthXException extends RuntimeException { protected AuthXException() Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Authenticator.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Authenticator.java?view=diff&rev=126380&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Authenticator.java&r1=126379&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Authenticator.java&r2=126380 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Authenticator.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Authenticator.java Tue Jan 25 05:09:08 2005 @@ -19,21 +19,20 @@ import javax.security.auth.Subject; /** - * <i><strong>Warning:</strong> This is experimental. Don't know yet if authenticator - * may use a single realm or several realms to perform authentication. In the case of several realms, - * each realm will probably support a unique authentication method and the argument to <code>authenticate</code> - * will change to a grouping of credential collections.</i> + * An <code>Authenticator</code> is responsible for validating a subject + * identity. The result of authentication is a <code>Subject</code> object + * that represents the subject and carries its identity as well as other + * security-related attributes that may be used to render + * authorization decisions. * * @author <a href="mailto:[EMAIL PROTECTED]">Apache Directory Project</a> */ public interface Authenticator { /** - * Returns a populated Subject with the principals which represent the - * identity of the user as well as any other principal for which permissions may be associated. - * <p/> - * If the configured realm implementation has <code>GroupSupport</code> then this - * authenticator may choose to add a principal for each group the user is a member of. + * Returns a populated <code>Subject</code> with the principals which + * represent the identity of the user as well as any other principal + * for which permissions may be associated. * * @param credentials A collection of credential objects provided as proof of identity * @return a Subject populated with appropriate principals or null if authentication fails Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Credential.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Credential.java?view=diff&rev=126380&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Credential.java&r1=126379&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Credential.java&r2=126380 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Credential.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/Credential.java Tue Jan 25 05:09:08 2005 @@ -16,6 +16,13 @@ */ package org.apache.authx.authentication; +/** + * A <code>Credential</code> is a of unit of proof of identity, + * such as a username or a password. + * <p> + * A [EMAIL PROTECTED] CredentialSet} groups together related <code>Credential</code>s + * for subject authentication purposes. + */ public interface Credential { Object getValue(); Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/CredentialSet.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/CredentialSet.java?view=diff&rev=126380&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/CredentialSet.java&r1=126379&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/CredentialSet.java&r2=126380 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/CredentialSet.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authentication/CredentialSet.java Tue Jan 25 05:09:08 2005 @@ -23,7 +23,11 @@ import java.util.Set; /** - * Declared final so we make sure no imposter implementation is possible. + * A <code>CredentialSet</code> is a grouping of related [EMAIL PROTECTED] Credential} + * objects that provides a proof of identity. It serves both identification and + * authentication purposes. + * <p> + * This class is declared final to make sure no imposter implementation can exist. * * @author <a href="mailto:[EMAIL PROTECTED]">Apache Directory Project</a> */ @@ -94,6 +98,15 @@ return subSet; } + /** + * Returns the only credential in this set that matches + * the given type. + * + * @param c the class of credential to be returned. + * @return the sole credential of this type in the set + * @throws IllegalArgumentException if none or more than one + * credential of the given type exists in the set + */ public Object getUniqueCredential( Class c ) { CredentialSet creds = getCredentials( c ); Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Authorizer.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Authorizer.java?view=diff&rev=126380&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Authorizer.java&r1=126379&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Authorizer.java&r2=126380 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Authorizer.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Authorizer.java Tue Jan 25 05:09:08 2005 @@ -18,7 +18,35 @@ import javax.security.auth.Subject; +/** + * An <code>Authorizer</code> is a security + * policy decision point. It is responsible for + * responding to an authorization request + * by rendering an authorization decision. + * <p> + * At this stage, no authorization request + * abstraction exist yet, but that may change + * soon. For the time being, an authorization request + * is composed of a requested <code>Permission</code> + * on behalf of a given subject. + * <p> + * No abstraction of authorization + * decision exist either and a boolean representation + * is used. That should change as well to support + * a richer authorization model that associates positive + * decisions to sets of obligations to which the client + * must compell. + */ public interface Authorizer { + /** + * Renders an authorization decision in response + * to the given authorization request. + * + * @param s The subject requesting a permission + * @param p The targeted permission + * @return true if case of a positive decision, + * false otherwise + */ boolean authorize( Subject s, Permission p ); } Modified: incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Permission.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Permission.java?view=diff&rev=126380&p1=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Permission.java&r1=126379&p2=incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Permission.java&r2=126380 ============================================================================== --- incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Permission.java (original) +++ incubator/directory/authx/trunk/core/api/src/java/org/apache/authx/authorization/Permission.java Tue Jan 25 05:09:08 2005 @@ -17,6 +17,12 @@ package org.apache.authx.authorization; /** + * A <code>Permission</code> represents a resource and a set of actions + * to perform on this resource. + * <p> + * The <code>Permission</code> interface is a simplier abstraction of the + * standard java permission concept. + * * @author <a href="mailto:[EMAIL PROTECTED]">Apache Directory Project</a> */ public interface Permission Modified: incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultAuthorizer.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultAuthorizer.java?view=diff&rev=126380&p1=incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultAuthorizer.java&r1=126379&p2=incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultAuthorizer.java&r2=126380 ============================================================================== --- incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultAuthorizer.java (original) +++ incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultAuthorizer.java Tue Jan 25 05:09:08 2005 @@ -22,9 +22,6 @@ import java.util.HashMap; import java.util.Map; -/** - * Warning: to be renamed to DefaultAuthorizer when moved out of sandbox - */ public class DefaultAuthorizer implements Authorizer { private final Map m_decisions; Modified: incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultRule.java Url: http://svn.apache.org/viewcvs/incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultRule.java?view=diff&rev=126380&p1=incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultRule.java&r1=126379&p2=incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultRule.java&r2=126380 ============================================================================== --- incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultRule.java (original) +++ incubator/directory/authx/trunk/core/impl/src/java/org/apache/authx/authorization/DefaultRule.java Tue Jan 25 05:09:08 2005 @@ -17,14 +17,12 @@ package org.apache.authx.authorization; import org.apache.authx.authorization.effect.Effects; -import org.apache.authx.authorization.predicate.Predicates; -import org.apache.authx.authorization.predicate.AndPredicate; import org.apache.authx.authorization.predicate.OrPredicate; +import org.apache.authx.authorization.predicate.Predicates; import javax.security.auth.Subject; /** - * TODO: consider adding predicates into an And operation instead of replacing * @author <a href="mailto:[EMAIL PROTECTED]">Vincent Tence</a> */ public class DefaultRule implements Rule
