harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ndbe...@apache.org
Subject svn commit: r768124 - in /harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth: ./ callback/ login/ x500/
Date Fri, 24 Apr 2009 02:02:46 GMT
Author: ndbeyer
Date: Fri Apr 24 02:02:45 2009
New Revision: 768124

URL: http://svn.apache.org/viewvc?rev=768124&view=rev
Log:
Apply modified patch for HARMONY-6174 - Javadoc for javax.security.auth.*

Modified:
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java
    harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java
Fri Apr 24 02:02:45 2009
@@ -21,6 +21,37 @@
 
 import org.apache.harmony.auth.internal.nls.Messages;
 
+/**
+ * Governs the use of methods in this package and also its subpackages. A
+ * <i>target name</i> of the permission specifies which methods are allowed
+ * without specifying the concrete action lists. Possible target names and
+ * associated authentication permissions are:
+ *
+ * <pre>
+ *    doAs                      invoke Subject.doAs methods.
+ *    doAsPrivileged            invoke the Subject.doAsPrivileged methods.
+ *    getSubject                invoke Subject.getSubject().
+ *    getSubjectFromDomainCombiner    invoke SubjectDomainCombiner.getSubject().
+ *    setReadOnly               invoke Subject.setReadonly().
+ *    modifyPrincipals          modify the set of principals
+ *                              associated with a Subject.
+ *    modifyPublicCredentials   modify the set of public credentials
+ *                              associated with a Subject.
+ *    modifyPrivateCredentials  modify the set of private credentials
+ *                              associated with a Subject.
+ *    refreshCredential         invoke the refresh method on a credential of a
+ *                              refreshable credential class.
+ *    destroyCredential         invoke the destroy method on a credential of a
+ *                              destroyable credential class.
+ *    createLoginContext.<i>name</i>   instantiate a LoginContext with the
+ *                              specified name. The wildcard name ('*')
+ *                              allows to a LoginContext of any name.
+ *    getLoginConfiguration     invoke the getConfiguration method of
+ *                              javax.security.auth.login.Configuration.
+ *    refreshLoginConfiguration Invoke the refresh method of
+ *                              javax.security.auth.login.Configuration.
+ * </pre>
+ */
 public final class AuthPermission extends BasicPermission {
 
     private static final long serialVersionUID = 5806031445061587174L;
@@ -42,10 +73,24 @@
         return name;
     }
 
+    /**
+     * Creates an authentication permission with the specified target name.
+     *
+     * @param name
+     *            the target name of this authentication permission.
+     */
     public AuthPermission(String name) {
         super(init(name));
     }
 
+    /**
+     * Creates an authentication permission with the specified target name.
+     *
+     * @param name
+     *            the target name of this authentication permission.
+     * @param actions
+     *            this parameter is ignored and should be {@code null}.
+     */
     public AuthPermission(String name, String actions) {
         super(init(name), actions);
     }

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java
Fri Apr 24 02:02:45 2009
@@ -17,14 +17,26 @@
 
 package javax.security.auth;
 
+/**
+ * Signals that the {@link Destroyable#destroy()} method failed.
+ */
 public class DestroyFailedException extends Exception {
 
     private static final long serialVersionUID = -7790152857282749162L;
 
+    /**
+     * Creates an exception of type {@code DestroyFailedException}.
+     */
     public DestroyFailedException() {
         super();
     }
 
+    /**
+     * Creates an exception of type {@code DestroyFailedException}.
+     *
+     * @param message
+     *            A detail message that describes the reason for this exception.
+     */
     public DestroyFailedException(String message) {
         super(message);
     }

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java
Fri Apr 24 02:02:45 2009
@@ -17,10 +17,27 @@
 
 package javax.security.auth;
 
+/**
+ * Allows for special treatment of sensitive information, when it comes to
+ * destroying or clearing of the data.
+ */
 public interface Destroyable {
 
+    /**
+     * Erases the sensitive information. Once an object is destroyed any calls
+     * to its methods will throw an {@code IllegalStateException}. If it does
+     * not succeed a DestroyFailedException is thrown.
+     *
+     * @throws DestroyFailedException
+     *             if the information cannot be erased.
+     */
     void destroy() throws DestroyFailedException;
 
+    /**
+     * Returns {@code true} once an object has been safely destroyed.
+     *
+     * @return whether the object has been safely destroyed.
+     */
     boolean isDestroyed();
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java
Fri Apr 24 02:02:45 2009
@@ -27,6 +27,28 @@
 
 import org.apache.harmony.auth.internal.nls.Messages;
 
+/**
+ * Protects private credential objects belonging to a {@code Subject}. It has
+ * only one action which is "read". The target name of this permission has a
+ * special syntax:
+ *
+ * <pre>
+ * targetName = CredentialClass {PrincipalClass &quot;PrincipalName&quot;}*
+ * </pre>
+ *
+ * First it states a credential class and is followed then by a list of one or
+ * more principals identifying the subject.
+ * <p>
+ * The principals on their part are specified as the name of the {@code
+ * Principal} class followed by the principal name in quotes. For example, the
+ * following file may define permission to read the private credentials of a
+ * principal named "Bob": "com.sun.PrivateCredential com.sun.Principal \"Bob\""
+ * <p>
+ * The syntax also allows the use of the wildcard "*" in place of {@code
+ * CredentialClass} or {@code PrincipalClass} and/or {@code PrincipalName}.
+ *
+ * @see Principal
+ */
 public final class PrivateCredentialPermission extends Permission {
 
     private static final long serialVersionUID = 5284372143517237068L;
@@ -42,6 +64,16 @@
     // owners set
     private transient CredOwner[] set;
     
+    /**
+     * Creates a new permission for private credentials specified by the target
+     * name {@code name} and an {@code action}. The action is always
+     * {@code "read"}.
+     *
+     * @param name
+     *            the target name of the permission.
+     * @param action
+     *            the action {@code "read"}.
+     */
     public PrivateCredentialPermission(String name, String action) {
         super(name);
         if (READ.equalsIgnoreCase(action)) {
@@ -52,11 +84,13 @@
     }
 
     /**
-     * Creates a <code>PrivateCredentialPermission</code> from the Credential
Class 
-     * and Set of Principals
+     * Creates a {@code PrivateCredentialPermission} from the {@code Credential}
+     * class and set of principals.
      * 
-     * @param credentialClass - credential class name
-     * @param principals - principal set
+     * @param credentialClass
+     *            the credential class name.
+     * @param principals
+     *            the set of principals.
      */
     PrivateCredentialPermission(String credentialClass, Set<Principal> principals)
{
         super(credentialClass);
@@ -156,6 +190,22 @@
         initTargetName(getName());
     }
 
+    /**
+     * Returns the principal's classes and names associated with this {@code
+     * PrivateCredentialPermission} as a two dimensional array. The first
+     * dimension of the array corresponds to the number of principals. The
+     * second dimension defines either the name of the {@code PrincipalClass}
+     * [x][0] or the value of {@code PrincipalName} [x][1].
+     * <p>
+     * This corresponds to the the target name's syntax:
+     *
+     * <pre>
+     * targetName = CredentialClass {PrincipalClass &quot;PrincipalName&quot;}*
+     * </pre>
+     *
+     * @return the principal classes and names associated with this {@code
+     *         PrivateCredentialPermission}.
+     */
     public String[][] getPrincipals() {
 
         String[][] s = new String[offset][2];
@@ -172,6 +222,11 @@
         return READ;
     }
 
+    /**
+     * Returns the class name of the credential associated with this permission.
+     *
+     * @return the class name of the credential associated with this permission.
+     */
     public String getCredentialClass() {
         return credentialClass;
     }

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java
Fri Apr 24 02:02:45 2009
@@ -38,6 +38,20 @@
 
 import org.apache.harmony.auth.internal.nls.Messages;
 
+/**
+ * The central class of the {@code javax.security.auth} package representing an
+ * authenticated user or entity (both referred to as "subject"). IT defines also
+ * the static methods that allow code to be run, and do modifications according
+ * to the subject's permissions.
+ * <p>
+ * A subject has the following features:
+ * <ul>
+ * <li>A set of {@code Principal} objects specifying the identities bound to a
+ * {@code Subject} that distinguish it.</li>
+ * <li>Credentials (public and private) such as certificates, keys, or
+ * authentication proofs such as tickets</li>
+ * </ul>
+ */
 public final class Subject implements Serializable {
 
     private static final long serialVersionUID = -8308522755600156056L;
@@ -72,6 +86,10 @@
     // set of public credentials
     private transient SecureSet<Object> publicCredentials;
     
+    /**
+     * The default constructor initializing the sets of public and private
+     * credentials and principals with the empty set.
+     */
     public Subject() {
         super();
         principals = new SecureSet<Principal>(_PRINCIPALS);
@@ -81,6 +99,23 @@
         readOnly = false;
     }
 
+    /**
+     * The constructor for the subject, setting its public and private
+     * credentials and principals according to the arguments.
+     *
+     * @param readOnly
+     *            {@code true} if this {@code Subject} is read-only, thus
+     *            preventing any modifications to be done.
+     * @param subjPrincipals
+     *            the set of Principals that are attributed to this {@code
+     *            Subject}.
+     * @param pubCredentials
+     *            the set of public credentials that distinguish this {@code
+     *            Subject}.
+     * @param privCredentials
+     *            the set of private credentials that distinguish this {@code
+     *            Subject}.
+     */
     public Subject(boolean readOnly, Set<? extends Principal> subjPrincipals,
             Set<?> pubCredentials, Set<?> privCredentials) {
 
@@ -95,6 +130,16 @@
         this.readOnly = readOnly;
     }
 
+    /**
+     * Runs the code defined by {@code action} using the permissions granted to
+     * the {@code Subject} itself and to the code as well.
+     *
+     * @param subject
+     *            the distinguished {@code Subject}.
+     * @param action
+     *            the code to be run.
+     * @return the {@code Object} returned when running the {@code action}.
+     */
     @SuppressWarnings("unchecked")
     public static Object doAs(Subject subject, PrivilegedAction action) {
 
@@ -103,6 +148,21 @@
         return doAs_PrivilegedAction(subject, action, AccessController.getContext());
     }
 
+    /**
+     * Run the code defined by {@code action} using the permissions granted to
+     * the {@code Subject} and to the code itself, additionally providing a more
+     * specific context.
+     *
+     * @param subject
+     *            the distinguished {@code Subject}.
+     * @param action
+     *            the code to be run.
+     * @param context
+     *            the specific context in which the {@code action} is invoked.
+     *            if {@code null} a new {@link AccessControlContext} is
+     *            instantiated.
+     * @return the {@code Object} returned when running the {@code action}.
+     */
     @SuppressWarnings("unchecked")
     public static Object doAsPrivileged(Subject subject, PrivilegedAction action,
             AccessControlContext context) {
@@ -144,6 +204,18 @@
         return AccessController.doPrivileged(action, newContext);
     }
 
+    /**
+     * Runs the code defined by {@code action} using the permissions granted to
+     * the subject and to the code itself.
+     *
+     * @param subject
+     *            the distinguished {@code Subject}.
+     * @param action
+     *            the code to be run.
+     * @return the {@code Object} returned when running the {@code action}.
+     * @throws PrivilegedActionException
+     *             if running the {@code action} throws an exception.
+     */
     @SuppressWarnings("unchecked")
     public static Object doAs(Subject subject, PrivilegedExceptionAction action)
             throws PrivilegedActionException {
@@ -153,6 +225,23 @@
         return doAs_PrivilegedExceptionAction(subject, action, AccessController.getContext());
     }
 
+    /**
+     * Runs the code defined by {@code action} using the permissions granted to
+     * the subject and to the code itself, additionally providing a more
+     * specific context.
+     *
+     * @param subject
+     *            the distinguished {@code Subject}.
+     * @param action
+     *            the code to be run.
+     * @param context
+     *            the specific context in which the {@code action} is invoked.
+     *            if {@code null} a new {@link AccessControlContext} is
+     *            instantiated.
+     * @return the {@code Object} returned when running the {@code action}.
+     * @throws PrivilegedActionException
+     *             if running the {@code action} throws an exception.
+     */
     @SuppressWarnings("unchecked")
     public static Object doAsPrivileged(Subject subject,
             PrivilegedExceptionAction action, AccessControlContext context)
@@ -195,6 +284,17 @@
         return AccessController.doPrivileged(action, newContext);
     }
 
+    /**
+     * Checks two Subjects for equality. More specifically if the principals,
+     * public and private credentials are equal, equality for two {@code
+     * Subjects} is implied.
+     *
+     * @param obj
+     *            the {@code Object} checked for equality with this {@code
+     *            Subject}.
+     * @return {@code true} if the specified {@code Subject} is equal to this
+     *         one.
+     */
     @Override
     public boolean equals(Object obj) {
 
@@ -216,46 +316,117 @@
         return false;
     }
 
+    /**
+     * Returns this {@code Subject}'s {@link Principal}.
+     *
+     * @return this {@code Subject}'s {@link Principal}.
+     */
     public Set<Principal> getPrincipals() {
         return principals;
     }
 
+
+    /**
+     * Returns this {@code Subject}'s {@link Principal} which is a subclass of
+     * the {@code Class} provided.
+     *
+     * @param c
+     *            the {@code Class} as a criteria which the {@code Principal}
+     *            returned must satisfy.
+     * @return this {@code Subject}'s {@link Principal}. Modifications to the
+     *         returned set of {@code Principal}s do not affect this {@code
+     *         Subject}'s set.
+     */
     public <T extends Principal> Set<T> getPrincipals(Class<T> c) {
         return ((SecureSet<Principal>) principals).get(c);
     }
 
+    /**
+     * Returns the private credentials associated with this {@code Subject}.
+     *
+     * @return the private credentials associated with this {@code Subject}.
+     */
     public Set<Object> getPrivateCredentials() {
         return privateCredentials;
     }
 
+    /**
+     * Returns this {@code Subject}'s private credentials which are a subclass
+     * of the {@code Class} provided.
+     *
+     * @param c
+     *            the {@code Class} as a criteria which the private credentials
+     *            returned must satisfy.
+     * @return this {@code Subject}'s private credentials. Modifications to the
+     *         returned set of credentials do not affect this {@code Subject}'s
+     *         credentials.
+     */
     public <T> Set<T> getPrivateCredentials(Class<T> c) {
         return privateCredentials.get(c);
     }
 
+    /**
+     * Returns the public credentials associated with this {@code Subject}.
+     *
+     * @return the public credentials associated with this {@code Subject}.
+     */
     public Set<Object> getPublicCredentials() {
         return publicCredentials;
     }
 
+
+    /**
+     * Returns this {@code Subject}'s public credentials which are a subclass of
+     * the {@code Class} provided.
+     *
+     * @param c
+     *            the {@code Class} as a criteria which the public credentials
+     *            returned must satisfy.
+     * @return this {@code Subject}'s public credentials. Modifications to the
+     *         returned set of credentials do not affect this {@code Subject}'s
+     *         credentials.
+     */
     public <T> Set<T> getPublicCredentials(Class<T> c) {
         return publicCredentials.get(c);
     }
 
+    /**
+     * Returns a hash code of this {@code Subject}.
+     *
+     * @return a hash code of this {@code Subject}.
+     */
     @Override
     public int hashCode() {
         return principals.hashCode() + privateCredentials.hashCode()
                 + publicCredentials.hashCode();
     }
 
+    /**
+     * Prevents from modifications being done to the credentials and {@link
+     * Principal} sets. After setting it to read-only this {@code Subject} can
+     * not be made writable again. The destroy method on the credentials still
+     * works though.
+     */
     public void setReadOnly() {
         checkPermission(_READ_ONLY);
 
         readOnly = true;
     }
 
+    /**
+     * Returns whether this {@code Subject} is read-only or not.
+     *
+     * @return whether this {@code Subject} is read-only or not.
+     */
     public boolean isReadOnly() {
         return readOnly;
     }
 
+    /**
+     * Returns a {@code String} representation of this {@code Subject}.
+     *
+     * @return a {@code String} representation of this {@code Subject}.
+     */
     @Override
     public String toString() {
 
@@ -303,6 +474,16 @@
         out.defaultWriteObject();
     }
 
+    /**
+     * Returns the {@code Subject} that was last associated with the {@code
+     * context} provided as argument.
+     *
+     * @param context
+     *            the {@code context} that was associated with the
+     *            {@code Subject}.
+     * @return the {@code Subject} that was last associated with the {@code
+     *         context} provided as argument.
+     */
     public static Subject getSubject(final AccessControlContext context) {
         checkPermission(_SUBJECT);
         if (context == null) {

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java
Fri Apr 24 02:02:45 2009
@@ -22,6 +22,10 @@
 import java.security.ProtectionDomain;
 import java.util.Set;
 
+/**
+ * Merges permissions based on code source and code signers with permissions
+ * granted to the specified {@link Subject}.
+ */
 public class SubjectDomainCombiner implements DomainCombiner {
 
     // subject to be associated
@@ -31,6 +35,12 @@
     private static final AuthPermission _GET = new AuthPermission(
             "getSubjectFromDomainCombiner"); //$NON-NLS-1$
 
+    /**
+     * Creates a domain combiner for the entity provided in {@code subject}.
+     *
+     * @param subject
+     *            the entity to which this domain combiner is associated.
+     */
     public SubjectDomainCombiner(Subject subject) {
         super();
         if (subject == null) {
@@ -39,6 +49,11 @@
         this.subject = subject;
     }
 
+    /**
+     * Returns the entity to which this domain combiner is associated.
+     *
+     * @return the entity to which this domain combiner is associated.
+     */
     public Subject getSubject() {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -48,6 +63,22 @@
         return subject;
     }
 
+    /**
+     * Merges the {@code ProtectionDomain} with the {@code Principal}s
+     * associated with the subject of this {@code SubjectDomainCombiner}.
+     *
+     * @param currentDomains
+     *            the {@code ProtectionDomain}s associated with the context of
+     *            the current thread. The domains must be sorted according to
+     *            the execution order, the most recent residing at the
+     *            beginning.
+     * @param assignedDomains
+     *            the {@code ProtectionDomain}s from the parent thread based on
+     *            code source and signers.
+     * @return a single {@code ProtectionDomain} array computed from the two
+     *         provided arrays, or {@code null}.
+     * @see ProtectionDomain
+     */
     public ProtectionDomain[] combine(ProtectionDomain[] currentDomains,
             ProtectionDomain[] assignedDomains) {
         // get array length for combining protection domains

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java
Fri Apr 24 02:02:45 2009
@@ -17,5 +17,9 @@
 
 package javax.security.auth.callback;
 
+/**
+ * Defines an empty base interface for all {@code Callback}s used during
+ * authentication.
+ */
 public interface Callback {
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java
Fri Apr 24 02:02:45 2009
@@ -17,8 +17,38 @@
 
 package javax.security.auth.callback;
 
+import java.io.IOException;
+
+/**
+ * Needs to be implemented by classes that want to handle authentication
+ * {@link Callback}s. A single method {@link #handle(Callback[])} must be
+ * provided that checks the type of the incoming {@code Callback}s and reacts
+ * accordingly. {@code CallbackHandler}s can be installed per application. It is
+ * also possible to configure a system-default {@code CallbackHandler} by
+ * setting the {@code auth.login.defaultCallbackHandler} property in the
+ * standard {@code security.properties} file.
+ */
 public interface CallbackHandler {
 
-    void handle(Callback[] callbacks) throws java.io.IOException, UnsupportedCallbackException;
+    /**
+     * Handles the actual {@link Callback}. A {@code CallbackHandler} needs to
+     * implement this method. In the method, it is free to select which {@code
+     * Callback}s it actually wants to handle and in which way. For example, a
+     * console-based {@code CallbackHandler} might choose to sequentially ask
+     * the user for login and password, if it implements these {@code Callback}
+     * s, whereas a GUI-based one might open a single dialog window for both
+     * values. If a {@code CallbackHandler} is not able to handle a specific
+     * {@code Callback}, it needs to throw an
+     * {@link UnsupportedCallbackException}.
+     *
+     * @param callbacks
+     *            the array of {@code Callback}s that need handling
+     * @throws IOException
+     *             if an I/O related error occurs
+     * @throws UnsupportedCallbackException
+     *             if the {@code CallbackHandler} is not able to handle a
+     *             specific {@code Callback}
+     */
+    void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException;
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java
Fri Apr 24 02:02:45 2009
@@ -22,6 +22,10 @@
 
 import org.apache.harmony.auth.internal.nls.Messages;
 
+/**
+ * Is used in conjunction with a {@link CallbackHandler} to retrieve a password
+ * when needed.
+ */
 public class PasswordCallback implements Callback, Serializable {
 
     private static final long serialVersionUID = 2267422647454909926L;
@@ -39,20 +43,49 @@
         this.prompt = prompt;
     }
 
+    /**
+     * Creates a new {@code PasswordCallback} instance.
+     *
+     * @param prompt
+     *            the message that should be displayed to the user
+     * @param echoOn
+     *            determines whether the user input should be echoed
+     */
     public PasswordCallback(String prompt, boolean echoOn) {
         super();
         setPrompt(prompt);
         this.echoOn = echoOn;
     }
 
+    /**
+     * Returns the prompt that was specified when creating this {@code
+     * PasswordCallback}
+     *
+     * @return the prompt
+     */
     public String getPrompt() {
         return prompt;
     }
 
+    /**
+     * Queries whether this {@code PasswordCallback} expects user input to be
+     * echoed, which is specified during the creation of the object.
+     *
+     * @return {@code true} if (and only if) user input should be echoed
+     */
     public boolean isEchoOn() {
         return echoOn;
     }
 
+    /**
+     * Sets the password. The {@link CallbackHandler} that performs the actual
+     * provisioning or input of the password needs to call this method to hand
+     * back the password to the security service that requested it.
+     *
+     * @param password
+     *            the password. A copy of this is stored, so subsequent changes
+     *            to the input array do not affect the {@code PasswordCallback}.
+     */
     public void setPassword(char[] password) {
         if (password == null) {
             this.inputPassword = password;
@@ -62,6 +95,15 @@
         }
     }
 
+    /**
+     * Returns the password. The security service that needs the password
+     * usually calls this method once the {@link CallbackHandler} has finished
+     * its work.
+     *
+     * @return the password. A copy of the internal password is created and
+     *         returned, so subsequent changes to the internal password do not
+     *         affect the result.
+     */
     public char[] getPassword() {
         if (inputPassword != null) {
             char[] tmp = new char[inputPassword.length];
@@ -71,6 +113,9 @@
         return null;
     }
 
+    /**
+     * Clears the password stored in this {@code PasswordCallback}.
+     */
     public void clearPassword() {
         if (inputPassword != null) {
             Arrays.fill(inputPassword, '\u0000');

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java
Fri Apr 24 02:02:45 2009
@@ -17,22 +17,47 @@
 
 package javax.security.auth.callback;
 
+/**
+ * Thrown when a {@link CallbackHandler} does not support a particular {@link
+ * Callback}.
+ */
 public class UnsupportedCallbackException extends Exception {
 
     private static final long serialVersionUID = -6873556327655666839L;
 
     private Callback callback;
 
+    /**
+     * Creates a new exception instance and initializes it with just the
+     * unsupported {@code Callback}, but no error message.
+     *
+     * @param callback
+     *            the {@code Callback}
+     */
     public UnsupportedCallbackException(Callback callback) {
         super();
         this.callback = callback;
     }
 
+    /**
+     * Creates a new exception instance and initializes it with both the
+     * unsupported {@code Callback} and an error message.
+     *
+     * @param callback
+     *            the {@code Callback}
+     * @param message
+     *            the error message
+     */
     public UnsupportedCallbackException(Callback callback, String message) {
         super(message);
         this.callback = callback;
     }
 
+    /**
+     * Returns the unsupported {@code Callback} that triggered this exception.
+     *
+     * @return the {@code Callback}
+     */
     public Callback getCallback() {
         return callback;
     }

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java
Fri Apr 24 02:02:45 2009
@@ -19,14 +19,25 @@
 
 import java.security.GeneralSecurityException;
 
+/**
+ * Base class for exceptions that are thrown when a login error occurs.
+ */
 public class LoginException extends GeneralSecurityException {
 
     private static final long serialVersionUID = -4679091624035232488L;
 
+    /**
+     * Creates a new exception instance and initializes it with default values.
+     */
     public LoginException() {
         super();
     }
 
+    /**
+     * Creates a new exception instance and initializes it with a given message.
+     *
+     * @param message the error message
+     */
     public LoginException(String message) {
         super(message);
     }

Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java
Fri Apr 24 02:02:45 2009
@@ -27,19 +27,49 @@
 import org.apache.harmony.auth.internal.nls.Messages;
 import org.apache.harmony.security.x501.Name;
 
+/**
+ * Represents an X.500 principal, which holds the distinguished name of some
+ * network entity. An example of a distinguished name is {@code "O=SomeOrg,
+ * OU=SomeOrgUnit, C=US"}. The class can be instantiated from a byte representation
+ * of an object identifier (OID), an ASN.1 DER-encoded version, or a simple
+ * string holding the distinguished name. The representations must follow either
+ * RFC 2253, RFC 1779, or RFC2459.
+ */
 public final class X500Principal implements Serializable, Principal {
 
     private static final long serialVersionUID = -500463348111345721L;
 
+    /**
+     * Defines a constant for the canonical string format of distinguished
+     * names.
+     */
     public static final String CANONICAL = "CANONICAL"; //$NON-NLS-1$
 
+    /**
+     * Defines a constant for the RFC 1779 string format of distinguished
+     * names.
+     */
     public static final String RFC1779 = "RFC1779"; //$NON-NLS-1$
 
+    /**
+     * Defines a constant for the RFC 2253 string format of distinguished
+     * names.
+     */
     public static final String RFC2253 = "RFC2253"; //$NON-NLS-1$
 
     //Distinguished Name
     private transient Name dn;
 
+    /**
+     * Creates a new X500Principal from a given ASN.1 DER encoding of a
+     * distinguished name.
+     *
+     * @param name
+     *            the ASN.1 DER-encoded distinguished name
+     *
+     * @throws IllegalArgumentException
+     *             if the ASN.1 DER-encoded distinguished name is incorrect
+     */
     public X500Principal(byte[] name) {
         super();
         if (name == null) {
@@ -56,6 +86,17 @@
         }
     }
 
+    /**
+     * Creates a new X500Principal from a given ASN.1 DER encoding of a
+     * distinguished name.
+     *
+     * @param in
+     *            an {@code InputStream} holding the ASN.1 DER-encoded
+     *            distinguished name
+     *
+     * @throws IllegalArgumentException
+     *             if the ASN.1 DER-encoded distinguished name is incorrect
+     */
     public X500Principal(InputStream in) {
         super();
         if (in == null) {
@@ -72,6 +113,17 @@
         }
     }
 
+    /**
+     * Creates a new X500Principal from a string representation of a
+     * distinguished name.
+     *
+     * @param name
+     *            the string representation of the distinguished name
+     *
+     * @throws IllegalArgumentException
+     *             if the string representation of the distinguished name is
+     *             incorrect
+     */
     public X500Principal(String name) {
         super();
         if (name == null) {
@@ -99,6 +151,12 @@
         return dn.getName(CANONICAL).equals(principal.dn.getName(CANONICAL));
     }
 
+    /**
+     * Returns an ASN.1 DER-encoded representation of the distinguished name
+     * contained in this X.500 principal.
+     *
+     * @return the ASN.1 DER-encoded representation
+     */
     public byte[] getEncoded() {
         byte[] src = dn.getEncoded();
         byte[] dst = new byte[src.length];
@@ -106,10 +164,35 @@
         return dst;
     }
 
+    /**
+     * Returns a human-readable string representation of the distinguished name
+     * contained in this X.500 principal.
+     *
+     * @return the string representation
+     */
     public String getName() {
         return dn.getName(RFC2253);
     }
 
+    /**
+     * Returns a string representation of the distinguished name contained in
+     * this X.500 principal. The format of the representation can be chosen.
+     * Valid arguments are {@link #RFC1779}, {@link #RFC2253}, and
+     * {@link #CANONICAL}. The representations are specified in RFC 1779 and RFC
+     * 2253, respectively. The canonical form is based on RFC 2253, but adds
+     * some canonicalizing operations like removing leading and trailing
+     * whitespace, lower-casing the whole name, and bringing it into a
+     * normalized Unicode representation.
+     *
+     * @param format
+     *            the name of the format to use for the representation
+     *
+     * @return the string representation
+     *
+     * @throws IllegalArgumentException
+     *             if the {@code format} argument is not one of the three
+     *             mentioned above
+     */
     public String getName(String format) {
         return dn.getName(format);
     }



Mime
View raw message