# HG changeset patch # User juh # Date 1374002381 25200 # Node ID 90956ead732f7f5245eb72fb47a4c4b9c0aa4303 # Parent ec84f0c313b0b0d6ff759708973a902748987e4d 8020557: javadoc cleanup in javax.security Reviewed-by: darcy diff -r ec84f0c313b0 -r 90956ead732f jdk/src/share/classes/javax/security/auth/AuthPermission.java --- a/jdk/src/share/classes/javax/security/auth/AuthPermission.java Mon Jul 15 14:37:01 2013 -0700 +++ b/jdk/src/share/classes/javax/security/auth/AuthPermission.java Tue Jul 16 12:19:41 2013 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2005, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -41,10 +41,10 @@ * *

  *      doAs -                  allow the caller to invoke the
- *                              Subject.doAs methods.
+ *                              {@code Subject.doAs} methods.
  *
  *      doAsPrivileged -        allow the caller to invoke the
- *                              Subject.doAsPrivileged methods.
+ *                              {@code Subject.doAsPrivileged} methods.
  *
  *      getSubject -            allow for the retrieval of the
  *                              Subject(s) associated with the
@@ -52,39 +52,39 @@
  *
  *      getSubjectFromDomainCombiner -  allow for the retrieval of the
  *                              Subject associated with the
- *                              a SubjectDomainCombiner.
+ *                              a {@code SubjectDomainCombiner}.
  *
  *      setReadOnly -           allow the caller to set a Subject
  *                              to be read-only.
  *
- *      modifyPrincipals -      allow the caller to modify the Set
+ *      modifyPrincipals -      allow the caller to modify the {@code Set}
  *                              of Principals associated with a
- *                              Subject
+ *                              {@code Subject}
  *
  *      modifyPublicCredentials - allow the caller to modify the
- *                              Set of public credentials
- *                              associated with a Subject
+ *                              {@code Set} of public credentials
+ *                              associated with a {@code Subject}
  *
  *      modifyPrivateCredentials - allow the caller to modify the
- *                              Set of private credentials
- *                              associated with a Subject
+ *                              {@code Set} of private credentials
+ *                              associated with a {@code Subject}
  *
- *      refreshCredential -     allow code to invoke the refresh
+ *      refreshCredential -     allow code to invoke the {@code refresh}
  *                              method on a credential which implements
- *                              the Refreshable interface.
+ *                              the {@code Refreshable} interface.
  *
- *      destroyCredential -     allow code to invoke the destroy
- *                              method on a credential object
- *                              which implements the Destroyable
+ *      destroyCredential -     allow code to invoke the {@code destroy}
+ *                              method on a credential {@code object}
+ *                              which implements the {@code Destroyable}
  *                              interface.
  *
  *      createLoginContext.{name} -  allow code to instantiate a
- *                              LoginContext with the
+ *                              {@code LoginContext} with the
  *                              specified name.  name
  *                              is used as the index into the installed login
- *                              Configuration
+ *                              {@code Configuration}
  *                              (that returned by
- *                              Configuration.getConfiguration()).
+ *                              {@code Configuration.getConfiguration()}).
  *                              name can be wildcarded (set to '*')
  *                              to allow for any name.
  *
@@ -93,7 +93,7 @@
  *
  *      createLoginConfiguration.{type} - allow code to obtain a Configuration
  *                              object via
- *                              Configuration.getInstance.
+ *                              {@code Configuration.getInstance}.
  *
  *      setLoginConfiguration - allow for the setting of the system-wide
  *                              login Configuration.
@@ -103,15 +103,15 @@
  *

* *

The following target name has been deprecated in favor of - * createLoginContext.{name}. + * {@code createLoginContext.{name}}. * *

  *      createLoginContext -    allow code to instantiate a
- *                              LoginContext.
+ *                              {@code LoginContext}.
  *

* - *

javax.security.auth.Policy has been - * deprecated in favor of java.security.Policy. + *

{@code javax.security.auth.Policy} has been + * deprecated in favor of {@code java.security.Policy}. * Therefore, the following target names have also been deprecated: * *

@@ -139,8 +139,8 @@
      *
      * @param name the name of the AuthPermission
      *
-     * @throws NullPointerException if name is null.
-     * @throws IllegalArgumentException if name is empty.
+     * @throws NullPointerException if {@code name} is {@code null}.
+     * @throws IllegalArgumentException if {@code name} is empty.
      */
     public AuthPermission(String name) {
         // for backwards compatibility --
@@ -160,8 +160,8 @@
      *
      * @param actions should be null.
      *
-     * @throws NullPointerException if name is null.
-     * @throws IllegalArgumentException if name is empty.
+     * @throws NullPointerException if {@code name} is {@code null}.
+     * @throws IllegalArgumentException if {@code name} is empty.
      */
     public AuthPermission(String name, String actions) {
         // for backwards compatibility --
diff -r ec84f0c313b0 -r 90956ead732f jdk/src/share/classes/javax/security/auth/DestroyFailedException.java
--- a/jdk/src/share/classes/javax/security/auth/DestroyFailedException.java	Mon Jul 15 14:37:01 2013 -0700
+++ b/jdk/src/share/classes/javax/security/auth/DestroyFailedException.java	Tue Jul 16 12:19:41 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,10 +26,10 @@
 package javax.security.auth;
 
 /**
- * Signals that a destroy operation failed.
+ * Signals that a {@code destroy} operation failed.
  *
  *  This exception is thrown by credentials implementing
- * the Destroyable interface when the destroy
+ * the {@code Destroyable} interface when the {@code destroy}
  * method fails.
  *
  */
diff -r ec84f0c313b0 -r 90956ead732f jdk/src/share/classes/javax/security/auth/Destroyable.java
--- a/jdk/src/share/classes/javax/security/auth/Destroyable.java	Mon Jul 15 14:37:01 2013 -0700
+++ b/jdk/src/share/classes/javax/security/auth/Destroyable.java	Tue Jul 16 12:19:41 2013 -0700
@@ -34,12 +34,12 @@
 public interface Destroyable {
 
     /**
-     * Destroy this Object.
+     * Destroy this {@code Object}.
      *
-     * 
 Sensitive information associated with this Object
+     * 
 Sensitive information associated with this {@code Object}
      * is destroyed or cleared.  Subsequent calls to certain methods
-     * on this Object will result in an
-     * IllegalStateException being thrown.
+     * on this {@code Object} will result in an
+     * {@code IllegalStateException} being thrown.
      *
      * 

      * The default implementation throws {@code DestroyFailedException}.
@@ -47,19 +47,19 @@
      * @exception DestroyFailedException if the destroy operation fails. 

      *
      * @exception SecurityException if the caller does not have permission
-     *          to destroy this Object.
+     *          to destroy this {@code Object}.
      */
     public default void destroy() throws DestroyFailedException {
         throw new DestroyFailedException();
     }
 
     /**
-     * Determine if this Object has been destroyed.
+     * Determine if this {@code Object} has been destroyed.
      *
      * 

      * The default implementation returns false.
      *
-     * @return true if this Object has been destroyed,
+     * @return true if this {@code Object} has been destroyed,
      *          false otherwise.
      */
     public default boolean isDestroyed() {
diff -r ec84f0c313b0 -r 90956ead732f jdk/src/share/classes/javax/security/auth/Policy.java
--- a/jdk/src/share/classes/javax/security/auth/Policy.java	Mon Jul 15 14:37:01 2013 -0700
+++ b/jdk/src/share/classes/javax/security/auth/Policy.java	Tue Jul 16 12:19:41 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -32,11 +32,11 @@
  * 
 This is an abstract class for representing the system policy for
  * Subject-based authorization.  A subclass implementation
  * of this class provides a means to specify a Subject-based
- * access control Policy.
+ * access control {@code Policy}.
  *
- * 
 A Policy object can be queried for the set of
+ * 
 A {@code Policy} object can be queried for the set of
  * Permissions granted to code running as a
- * Principal in the following manner:
+ * {@code Principal} in the following manner:
  *
  * 
  *      policy = Policy.getPolicy();
@@ -44,20 +44,20 @@
  *                                                      codeSource);
  * 
  *
- * The Policy object consults the local policy and returns
- * and appropriate Permissions object with the
+ * The {@code Policy} object consults the local policy and returns
+ * and appropriate {@code Permissions} object with the
  * Permissions granted to the Principals associated with the
  * provided subject, and granted to the code specified
  * by the provided codeSource.
  *
- *  A Policy contains the following information.
+ * 
 A {@code Policy} contains the following information.
  * Note that this example only represents the syntax for the default
- * Policy implementation. Subclass implementations of this class
+ * {@code Policy} implementation. Subclass implementations of this class
  * may implement alternative syntaxes and may retrieve the
- * Policy from any source such as files, databases,
+ * {@code Policy} from any source such as files, databases,
  * or servers.
  *
- * 
 Each entry in the Policy is represented as
+ * 
 Each entry in the {@code Policy} is represented as
  * a grant entry.  Each grant entry
  * specifies a codebase, code signers, and Principals triplet,
  * as well as the Permissions granted to that triplet.
@@ -84,23 +84,23 @@
  *

* * This grant entry specifies that code from "foo.com", - * signed by "foo', and running as a SolarisPrincipal with the - * name, duke, has one Permission. This Permission + * signed by "foo', and running as a {@code SolarisPrincipal} with the + * name, duke, has one {@code Permission}. This {@code Permission} * permits the executing code to read and write files in the directory, * "/home/duke". * - *

To "run" as a particular Principal, - * code invokes the Subject.doAs(subject, ...) method. + *

To "run" as a particular {@code Principal}, + * code invokes the {@code Subject.doAs(subject, ...)} method. * After invoking that method, the code runs as all the Principals - * associated with the specified Subject. - * Note that this Policy (and the Permissions - * granted in this Policy) only become effective - * after the call to Subject.doAs has occurred. + * associated with the specified {@code Subject}. + * Note that this {@code Policy} (and the Permissions + * granted in this {@code Policy}) only become effective + * after the call to {@code Subject.doAs} has occurred. * *

Multiple Principals may be listed within one grant entry. * All the Principals in the grant entry must be associated with - * the Subject provided to Subject.doAs - * for that Subject to be granted the specified Permissions. + * the {@code Subject} provided to {@code Subject.doAs} + * for that {@code Subject} to be granted the specified Permissions. * *

  *      grant Principal com.sun.security.auth.SolarisPrincipal "duke",
@@ -115,7 +115,7 @@
  * as well as permission to make socket connections to "duke.com".
  *
  *  Note that non Principal-based grant entries are not permitted
- * in this Policy.  Therefore, grant entries such as:
+ * in this {@code Policy}.  Therefore, grant entries such as:
  *
  * 
  *      grant CodeBase "foo.com", Signedby "foo" {
@@ -124,7 +124,7 @@
  * 
  *
  * are rejected.  Such permission must be listed in the
- * java.security.Policy.
+ * {@code java.security.Policy}.
  *
  *  The default {@code Policy} implementation can be changed by
  * setting the value of the {@code auth.policy.provider} security property to
@@ -179,14 +179,14 @@
     /**
      * Returns the installed Policy object.
      * This method first calls
-     * SecurityManager.checkPermission with the
-     * AuthPermission("getPolicy") permission
+     * {@code SecurityManager.checkPermission} with the
+     * {@code AuthPermission("getPolicy")} permission
      * to ensure the caller has permission to get the Policy object.
      *
      * 

      *
      * @return the installed Policy.  The return value cannot be
-     *          null.
+     *          {@code null}.
      *
      * @exception java.lang.SecurityException if the current thread does not
      *      have permission to get the Policy object.
@@ -252,8 +252,8 @@
 
     /**
      * Sets the system-wide Policy object. This method first calls
-     * SecurityManager.checkPermission with the
-     * AuthPermission("setPolicy")
+     * {@code SecurityManager.checkPermission} with the
+     * {@code AuthPermission("setPolicy")}
      * permission to ensure the caller has permission to set the Policy.
      *
      * 

@@ -313,25 +313,25 @@
 
     /**
      * Retrieve the Permissions granted to the Principals associated with
-     * the specified CodeSource.
+     * the specified {@code CodeSource}.
      *
      * 

      *
-     * @param subject the Subject
+     * @param subject the {@code Subject}
      *                  whose associated Principals,
      *                  in conjunction with the provided
-     *                  CodeSource, determines the Permissions
+     *                  {@code CodeSource}, determines the Permissions
      *                  returned by this method.  This parameter
-     *                  may be null. 

+     *                  may be {@code null}. 

      *
-     * @param cs the code specified by its CodeSource
+     * @param cs the code specified by its {@code CodeSource}
      *                  that determines, in conjunction with the provided
-     *                  Subject, the Permissions
+     *                  {@code Subject}, the Permissions
      *                  returned by this method.  This parameter may be
-     *                  null.
+     *                  {@code null}.
      *
      * @return the Collection of Permissions granted to all the
-     *                  Subject and code specified in
+     *                  {@code Subject} and code specified in
      *                  the provided subject and cs
      *                  parameters.
      */
@@ -345,7 +345,7 @@
      * 
This method causes this object to refresh/reload its current
      * Policy. This is implementation-dependent.
      * For example, if the Policy object is stored in
-     * a file, calling refresh will cause the file to be re-read.
+     * a file, calling {@code refresh} will cause the file to be re-read.
      *
      * 

      *
diff -r ec84f0c313b0 -r 90956ead732f jdk/src/share/classes/javax/security/auth/PrivateCredentialPermission.java
--- a/jdk/src/share/classes/javax/security/auth/PrivateCredentialPermission.java	Mon Jul 15 14:37:01 2013 -0700
+++ b/jdk/src/share/classes/javax/security/auth/PrivateCredentialPermission.java	Tue Jul 16 12:19:41 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -34,10 +34,10 @@
 
 /**
  * This class is used to protect access to private Credentials
- * belonging to a particular Subject.  The Subject
+ * belonging to a particular {@code Subject}.  The {@code Subject}
  * is represented by a Set of Principals.
  *
- * 
 The target name of this Permission specifies
+ * 
 The target name of this {@code Permission} specifies
  * a Credential class name, and a Set of Principals.
  * The only valid value for this Permission's actions is, "read".
  * The target name must abide by the following syntax:
@@ -65,12 +65,12 @@
  *
  * If CredentialClass is "*", then access is granted to
  * all private Credentials belonging to the specified
- * Subject.
+ * {@code Subject}.
  * If "PrincipalName" is "*", then access is granted to the
- * specified Credential owned by any Subject that has the
- * specified Principal (the actual PrincipalName doesn't matter).
+ * specified Credential owned by any {@code Subject} that has the
+ * specified {@code Principal} (the actual PrincipalName doesn't matter).
  * For example, the following grants access to the
- * a.b.Credential owned by any Subject that has
+ * a.b.Credential owned by any {@code Subject} that has
  * an a.b.Principal.
  *
  * 
@@ -83,7 +83,7 @@
  *
  * If both the PrincipalClass and "PrincipalName" are "*",
  * then access is granted to the specified Credential owned by
- * any Subject.
+ * any {@code Subject}.
  *
  *  In addition, the PrincipalClass/PrincipalName pairing may be repeated:
  *
@@ -96,7 +96,7 @@
  * 
  *
  * The above grants access to the private Credential, "a.b.Credential",
- * belonging to a Subject with at least two associated Principals:
+ * belonging to a {@code Subject} with at least two associated Principals:
  * "a.b.Principal" with the name, "duke", and "c.d.Principal", with the name,
  * "dukette".
  *
@@ -115,7 +115,7 @@
     /**
      * @serial The Principals associated with this permission.
      *          The set contains elements of type,
-     *          PrivateCredentialPermission.CredOwner.
+     *          {@code PrivateCredentialPermission.CredOwner}.
      */
     private Set principals;  // ignored - kept around for compatibility
     private transient CredOwner[] credOwners;
@@ -126,8 +126,8 @@
     private boolean testing = false;
 
     /**
-     * Create a new PrivateCredentialPermission
-     * with the specified credentialClass and Principals.
+     * Create a new {@code PrivateCredentialPermission}
+     * with the specified {@code credentialClass} and Principals.
      */
     PrivateCredentialPermission(String credentialClass,
                         Set principals) {
@@ -153,19 +153,19 @@
     }
 
     /**
-     * Creates a new PrivateCredentialPermission
-     * with the specified name.  The name
-     * specifies both a Credential class and a Principal Set.
+     * Creates a new {@code PrivateCredentialPermission}
+     * with the specified {@code name}.  The {@code name}
+     * specifies both a Credential class and a {@code Principal} Set.
      *
      * 
      *
      * @param name the name specifying the Credential class and
-     *          Principal Set. 

+     *          {@code Principal} Set. 

      *
      * @param actions the actions specifying that the Credential can be read.
      *
-     * @throws IllegalArgumentException if name does not conform
-     *          to the correct syntax or if actions is not "read".
+     * @throws IllegalArgumentException if {@code name} does not conform
+     *          to the correct syntax or if {@code actions} is not "read".
      */
     public PrivateCredentialPermission(String name, String actions) {
         super(name);
@@ -178,34 +178,34 @@
 
     /**
      * Returns the Class name of the Credential associated with this
-     * PrivateCredentialPermission.
+     * {@code PrivateCredentialPermission}.
      *
      * 

      *
      * @return the Class name of the Credential associated with this
-     *          PrivateCredentialPermission.
+     *          {@code PrivateCredentialPermission}.
      */
     public String getCredentialClass() {
         return credentialClass;
     }
 
     /**
-     * Returns the Principal classes and names
-     * associated with this PrivateCredentialPermission.
+     * Returns the {@code Principal} classes and names
+     * associated with this {@code PrivateCredentialPermission}.
      * The information is returned as a two-dimensional array (array[x][y]).
-     * The 'x' value corresponds to the number of Principal
+     * The 'x' value corresponds to the number of {@code Principal}
      * class and name pairs.  When (y==0), it corresponds to
-     * the Principal class value, and when (y==1),
-     * it corresponds to the Principal name value.
+     * the {@code Principal} class value, and when (y==1),
+     * it corresponds to the {@code Principal} name value.
      * For example, array[0][0] corresponds to the class name of
-     * the first Principal in the array.  array[0][1]
-     * corresponds to the Principal name of the
-     * first Principal in the array.
+     * the first {@code Principal} in the array.  array[0][1]
+     * corresponds to the {@code Principal} name of the
+     * first {@code Principal} in the array.
      *
      * 

      *
-     * @return the Principal class and names associated
-     *          with this PrivateCredentialPermission.
+     * @return the {@code Principal} class and names associated
+     *          with this {@code PrivateCredentialPermission}.
      */
     public String[][] getPrincipals() {
 
@@ -222,8 +222,8 @@
     }
 
     /**
-     * Checks if this PrivateCredentialPermission implies
-     * the specified Permission.
+     * Checks if this {@code PrivateCredentialPermission} implies
+     * the specified {@code Permission}.
      *
      * 

      *
@@ -241,10 +241,10 @@
      *
      * 

      *
-     * @param p the Permission to check against.
+     * @param p the {@code Permission} to check against.
      *
-     * @return true if this PrivateCredentialPermission implies
-     * the specified Permission, false if not.
+     * @return true if this {@code PrivateCredentialPermission} implies
+     * the specified {@code Permission}, false if not.
      */
     public boolean implies(Permission p) {
 
@@ -260,9 +260,9 @@
     }
 
     /**
-     * Checks two PrivateCredentialPermission objects for
+     * Checks two {@code PrivateCredentialPermission} objects for
      * equality.  Checks that obj is a
-     * PrivateCredentialPermission,
+     * {@code PrivateCredentialPermission},
      * and has the same credential class as this object,
      * as well as the same Principals as this object.
      * The order of the Principals in the respective Permission's
@@ -272,7 +272,7 @@
      *
      * @param obj the object we are testing for equality with this object.
      *
-     * @return true if obj is a PrivateCredentialPermission,
+     * @return true if obj is a {@code PrivateCredentialPermission},
      *          has the same credential class as this object,
      *          and has the same Principals as this object.
      */
@@ -311,9 +311,9 @@
 
     /**
      * Return a homogeneous collection of PrivateCredentialPermissions
-     * in a PermissionCollection.
-     * No such PermissionCollection is defined,
-     * so this method always returns null.
+     * in a {@code PermissionCollection}.
+     * No such {@code PermissionCollection} is defined,
+     * so this method always returns {@code null}.
      *
      * 

      *
diff -r ec84f0c313b0 -r 90956ead732f jdk/src/share/classes/javax/security/auth/RefreshFailedException.java
--- a/jdk/src/share/classes/javax/security/auth/RefreshFailedException.java	Mon Jul 15 14:37:01 2013 -0700
+++ b/jdk/src/share/classes/javax/security/auth/RefreshFailedException.java	Tue Jul 16 12:19:41 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,10 +26,10 @@
 package javax.security.auth;
 
 /**
- * Signals that a refresh operation failed.
+ * Signals that a {@code refresh} operation failed.
  *
  * 
 This exception is thrown by credentials implementing
- * the Refreshable interface when the refresh
+ * the {@code Refreshable} interface when the {@code refresh}
  * method fails.
  *
  */
diff -r ec84f0c313b0 -r 90956ead732f jdk/src/share/classes/javax/security/auth/Refreshable.java
--- a/jdk/src/share/classes/javax/security/auth/Refreshable.java	Mon Jul 15 14:37:01 2013 -0700
+++ b/jdk/src/share/classes/javax/security/auth/Refreshable.java	Tue Jul 16 12:19:41 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -37,24 +37,24 @@
 public interface Refreshable {
 
     /**
-     * Determine if this Object is current.
+     * Determine if this {@code Object} is current.
      *
      * 

      *
-     * @return true if this Object is currently current,
+     * @return true if this {@code Object} is currently current,
      *          false otherwise.
      */
     boolean isCurrent();
 
     /**
      * Update or extend the validity period for this
-     * Object.
+     * {@code Object}.
      *
      * 

      *
      * @exception SecurityException if the caller does not have permission
      *          to update or extend the validity period for this
-     *          Object. 

+     *          {@code Object}. 

      *
      * @exception RefreshFailedException if the refresh attempt failed.
      */
diff -r ec84f0c313b0 -r 90956ead732f jdk/src/share/classes/javax/security/auth/Subject.java
--- a/jdk/src/share/classes/javax/security/auth/Subject.java	Mon Jul 15 14:37:01 2013 -0700
+++ b/jdk/src/share/classes/javax/security/auth/Subject.java	Tue Jul 16 12:19:41 2013 -0700
@@ -42,39 +42,39 @@
 import sun.security.util.ResourcesMgr;
 
 /**
- * 
 A Subject represents a grouping of related information
+ * 
 A {@code Subject} represents a grouping of related information
  * for a single entity, such as a person.
  * Such information includes the Subject's identities as well as
  * its security-related attributes
  * (passwords and cryptographic keys, for example).
  *
  * 
 Subjects may potentially have multiple identities.
- * Each identity is represented as a Principal
- * within the Subject.  Principals simply bind names to a
- * Subject.  For example, a Subject that happens
+ * Each identity is represented as a {@code Principal}
+ * within the {@code Subject}.  Principals simply bind names to a
+ * {@code Subject}.  For example, a {@code Subject} that happens
  * to be a person, Alice, might have two Principals:
  * one which binds "Alice Bar", the name on her driver license,
- * to the Subject, and another which binds,
+ * to the {@code Subject}, and another which binds,
  * "999-99-9999", the number on her student identification card,
- * to the Subject.  Both Principals refer to the same
- * Subject even though each has a different name.
+ * to the {@code Subject}.  Both Principals refer to the same
+ * {@code Subject} even though each has a different name.
  *
- * 
 A Subject may also own security-related attributes,
+ * 
 A {@code Subject} may also own security-related attributes,
  * which are referred to as credentials.
  * Sensitive credentials that require special protection, such as
  * private cryptographic keys, are stored within a private credential
- * Set.  Credentials intended to be shared, such as
+ * {@code Set}.  Credentials intended to be shared, such as
  * public key certificates or Kerberos server tickets are stored
- * within a public credential Set.  Different permissions
+ * within a public credential {@code Set}.  Different permissions
  * are required to access and modify the different credential Sets.
  *
- * 
 To retrieve all the Principals associated with a Subject,
- * invoke the getPrincipals method.  To retrieve
- * all the public or private credentials belonging to a Subject,
- * invoke the getPublicCredentials method or
- * getPrivateCredentials method, respectively.
- * To modify the returned Set of Principals and credentials,
- * use the methods defined in the Set class.
+ * 
 To retrieve all the Principals associated with a {@code Subject},
+ * invoke the {@code getPrincipals} method.  To retrieve
+ * all the public or private credentials belonging to a {@code Subject},
+ * invoke the {@code getPublicCredentials} method or
+ * {@code getPrivateCredentials} method, respectively.
+ * To modify the returned {@code Set} of Principals and credentials,
+ * use the methods defined in the {@code Set} class.
  * For example:
  * 
  *      Subject subject;
@@ -86,13 +86,13 @@
  *      subject.getPublicCredentials().add(credential);
  * 
  *
- *  This Subject class implements Serializable.
- * While the Principals associated with the Subject are serialized,
- * the credentials associated with the Subject are not.
- * Note that the java.security.Principal class
- * does not implement Serializable.  Therefore all concrete
- * Principal implementations associated with Subjects
- * must implement Serializable.
+ * 
 This {@code Subject} class implements {@code Serializable}.
+ * While the Principals associated with the {@code Subject} are serialized,
+ * the credentials associated with the {@code Subject} are not.
+ * Note that the {@code java.security.Principal} class
+ * does not implement {@code Serializable}.  Therefore all concrete
+ * {@code Principal} implementations associated with Subjects
+ * must implement {@code Serializable}.
  *
  * @see java.security.Principal
  * @see java.security.DomainCombiner
@@ -102,14 +102,14 @@
     private static final long serialVersionUID = -8308522755600156056L;
 
     /**
-     * A Set that provides a view of all of this
+     * A {@code Set} that provides a view of all of this
      * Subject's Principals
      *
      * 

      *
      * @serial Each element in this set is a
-     *          java.security.Principal.
-     *          The set is a Subject.SecureSet.
+     *          {@code java.security.Principal}.
+     *          The set is a {@code Subject.SecureSet}.
      */
     Set principals;
 
@@ -135,21 +135,21 @@
         = new ProtectionDomain[0];
 
     /**
-     * Create an instance of a Subject
-     * with an empty Set of Principals and empty
+     * Create an instance of a {@code Subject}
+     * with an empty {@code Set} of Principals and empty
      * Sets of public and private credentials.
      *
-     * 
 The newly constructed Sets check whether this Subject
+     * 
 The newly constructed Sets check whether this {@code Subject}
      * has been set read-only before permitting subsequent modifications.
      * The newly created Sets also prevent illegal modifications
      * by ensuring that callers have sufficient permissions.
      *
      * 
 To modify the Principals Set, the caller must have
-     * AuthPermission("modifyPrincipals").
+     * {@code AuthPermission("modifyPrincipals")}.
      * To modify the public credential Set, the caller must have
-     * AuthPermission("modifyPublicCredentials").
+     * {@code AuthPermission("modifyPublicCredentials")}.
      * To modify the private credential Set, the caller must have
-     * AuthPermission("modifyPrivateCredentials").
+     * {@code AuthPermission("modifyPrivateCredentials")}.
      */
     public Subject() {
 
@@ -162,39 +162,39 @@
     }
 
     /**
-     * Create an instance of a Subject with
+     * Create an instance of a {@code Subject} with
      * Principals and credentials.
      *
      * 
 The Principals and credentials from the specified Sets
      * are copied into newly constructed Sets.
-     * These newly created Sets check whether this Subject
+     * These newly created Sets check whether this {@code Subject}
      * has been set read-only before permitting subsequent modifications.
      * The newly created Sets also prevent illegal modifications
      * by ensuring that callers have sufficient permissions.
      *
      * 
 To modify the Principals Set, the caller must have
-     * AuthPermission("modifyPrincipals").
+     * {@code AuthPermission("modifyPrincipals")}.
      * To modify the public credential Set, the caller must have
-     * AuthPermission("modifyPublicCredentials").
+     * {@code AuthPermission("modifyPublicCredentials")}.
      * To modify the private credential Set, the caller must have
-     * AuthPermission("modifyPrivateCredentials").
+     * {@code AuthPermission("modifyPrivateCredentials")}.
      * 

      *
-     * @param readOnly true if the Subject is to be read-only,
+     * @param readOnly true if the {@code Subject} is to be read-only,
      *          and false otherwise. 

      *
-     * @param principals the Set of Principals
-     *          to be associated with this Subject. 

+     * @param principals the {@code Set} of Principals
+     *          to be associated with this {@code Subject}. 

      *
-     * @param pubCredentials the Set of public credentials
-     *          to be associated with this Subject. 

+     * @param pubCredentials the {@code Set} of public credentials
+     *          to be associated with this {@code Subject}. 

      *
-     * @param privCredentials the Set of private credentials
-     *          to be associated with this Subject.
+     * @param privCredentials the {@code Set} of private credentials
+     *          to be associated with this {@code Subject}.
      *
      * @exception NullPointerException if the specified
-     *          principals, pubCredentials,
-     *          or privCredentials are null.
+     *          {@code principals}, {@code pubCredentials},
+     *          or {@code privCredentials} are {@code null}.
      */
     public Subject(boolean readOnly, Set principals,
                    Set pubCredentials, Set privCredentials)
@@ -216,24 +216,24 @@
     }
 
     /**
-     * Set this Subject to be read-only.
+     * Set this {@code Subject} to be read-only.
      *
      * 
 Modifications (additions and removals) to this Subject's
-     * Principal Set and
+     * {@code Principal} {@code Set} and
      * credential Sets will be disallowed.
-     * The destroy operation on this Subject's credentials will
+     * The {@code destroy} operation on this Subject's credentials will
      * still be permitted.
      *
-     * 
 Subsequent attempts to modify the Subject's Principal
+     * 
 Subsequent attempts to modify the Subject's {@code Principal}
      * and credential Sets will result in an
-     * IllegalStateException being thrown.
-     * Also, once a Subject is read-only,
+     * {@code IllegalStateException} being thrown.
+     * Also, once a {@code Subject} is read-only,
      * it can not be reset to being writable again.
      *
      * 

      *
      * @exception SecurityException if the caller does not have permission
-     *          to set this Subject to be read-only.
+     *          to set this {@code Subject} to be read-only.
      */
     public void setReadOnly() {
         java.lang.SecurityManager sm = System.getSecurityManager();
@@ -245,40 +245,40 @@
     }
 
     /**
-     * Query whether this Subject is read-only.
+     * Query whether this {@code Subject} is read-only.
      *
      * 

      *
-     * @return true if this Subject is read-only, false otherwise.
+     * @return true if this {@code Subject} is read-only, false otherwise.
      */
     public boolean isReadOnly() {
         return this.readOnly;
     }
 
     /**
-     * Get the Subject associated with the provided
-     * AccessControlContext.
+     * Get the {@code Subject} associated with the provided
+     * {@code AccessControlContext}.
      *
-     * 
 The AccessControlContext may contain many
-     * Subjects (from nested doAs calls).
-     * In this situation, the most recent Subject associated
-     * with the AccessControlContext is returned.
+     * 
 The {@code AccessControlContext} may contain many
+     * Subjects (from nested {@code doAs} calls).
+     * In this situation, the most recent {@code Subject} associated
+     * with the {@code AccessControlContext} is returned.
      *
      * 

      *
-     * @param  acc the AccessControlContext from which to retrieve
-     *          the Subject.
+     * @param  acc the {@code AccessControlContext} from which to retrieve
+     *          the {@code Subject}.
      *
-     * @return  the Subject associated with the provided
-     *          AccessControlContext, or null
-     *          if no Subject is associated
-     *          with the provided AccessControlContext.
+     * @return  the {@code Subject} associated with the provided
+     *          {@code AccessControlContext}, or {@code null}
+     *          if no {@code Subject} is associated
+     *          with the provided {@code AccessControlContext}.
      *
      * @exception SecurityException if the caller does not have permission
-     *          to get the Subject. 

+     *          to get the {@code Subject}. 

      *
      * @exception NullPointerException if the provided
-     *          AccessControlContext is null.
+     *          {@code AccessControlContext} is {@code null}.
      */
     public static Subject getSubject(final AccessControlContext acc) {
 
@@ -306,36 +306,36 @@
     }
 
     /**
-     * Perform work as a particular Subject.
+     * Perform work as a particular {@code Subject}.
      *
      * 
 This method first retrieves the current Thread's
-     * AccessControlContext via
-     * AccessController.getContext,
-     * and then instantiates a new AccessControlContext
+     * {@code AccessControlContext} via
+     * {@code AccessController.getContext},
+     * and then instantiates a new {@code AccessControlContext}
      * using the retrieved context along with a new
-     * SubjectDomainCombiner (constructed using
-     * the provided Subject).
-     * Finally, this method invokes AccessController.doPrivileged,
-     * passing it the provided PrivilegedAction,
-     * as well as the newly constructed AccessControlContext.
+     * {@code SubjectDomainCombiner} (constructed using
+     * the provided {@code Subject}).
+     * Finally, this method invokes {@code AccessController.doPrivileged},
+     * passing it the provided {@code PrivilegedAction},
+     * as well as the newly constructed {@code AccessControlContext}.
      *
      * 

      *
-     * @param subject the Subject that the specified
-     *                  action will run as.  This parameter
-     *                  may be null. 

+     * @param subject the {@code Subject} that the specified
+     *                  {@code action} will run as.  This parameter
+     *                  may be {@code null}. 

      *
      * @param  the type of the value returned by the PrivilegedAction's
      *                  {@code run} method.
      *
      * @param action the code to be run as the specified
-     *                  Subject. 

+     *                  {@code Subject}. 

      *
      * @return the value returned by the PrivilegedAction's
-     *                  run method.
+     *                  {@code run} method.
      *
-     * @exception NullPointerException if the PrivilegedAction
-     *                  is null. 

+     * @exception NullPointerException if the {@code PrivilegedAction}
+     *                  is {@code null}. 

      *
      * @exception SecurityException if the caller does not have permission
      *                  to invoke this method.
@@ -362,41 +362,41 @@
     }
 
     /**
-     * Perform work as a particular Subject.
+     * Perform work as a particular {@code Subject}.
      *
      * 
 This method first retrieves the current Thread's
-     * AccessControlContext via
-     * AccessController.getContext,
-     * and then instantiates a new AccessControlContext
+     * {@code AccessControlContext} via
+     * {@code AccessController.getContext},
+     * and then instantiates a new {@code AccessControlContext}
      * using the retrieved context along with a new
-     * SubjectDomainCombiner (constructed using
-     * the provided Subject).
-     * Finally, this method invokes AccessController.doPrivileged,
-     * passing it the provided PrivilegedExceptionAction,
-     * as well as the newly constructed AccessControlContext.
+     * {@code SubjectDomainCombiner} (constructed using
+     * the provided {@code Subject}).
+     * Finally, this method invokes {@code AccessController.doPrivileged},
+     * passing it the provided {@code PrivilegedExceptionAction},
+     * as well as the newly constructed {@code AccessControlContext}.
      *
      * 

      *
-     * @param subject the Subject that the specified
-     *                  action will run as.  This parameter
-     *                  may be null. 

+     * @param subject the {@code Subject} that the specified
+     *                  {@code action} will run as.  This parameter
+     *                  may be {@code null}. 

      *
      * @param  the type of the value returned by the
      *                  PrivilegedExceptionAction's {@code run} method.
      *
      * @param action the code to be run as the specified
-     *                  Subject. 

+     *                  {@code Subject}. 

      *
      * @return the value returned by the
-     *                  PrivilegedExceptionAction's run method.
+     *                  PrivilegedExceptionAction's {@code run} method.
      *
      * @exception PrivilegedActionException if the
-     *                  PrivilegedExceptionAction.run
+     *                  {@code PrivilegedExceptionAction.run}
      *                  method throws a checked exception. 

      *
      * @exception NullPointerException if the specified
-     *                  PrivilegedExceptionAction is
-     *                  null. 

+     *                  {@code PrivilegedExceptionAction} is
+     *                  {@code null}. 

      *
      * @exception SecurityException if the caller does not have permission
      *                  to invoke this method.
@@ -424,36 +424,36 @@
     }
 
     /**
-     * Perform privileged work as a particular Subject.
+     * Perform privileged work as a particular {@code Subject}.
      *
-     * 
 This method behaves exactly as Subject.doAs,
+     * 
 This method behaves exactly as {@code Subject.doAs},
      * except that instead of retrieving the current Thread's
-     * AccessControlContext, it uses the provided
-     * AccessControlContext.  If the provided
-     * AccessControlContext is null,
-     * this method instantiates a new AccessControlContext
+     * {@code AccessControlContext}, it uses the provided
+     * {@code AccessControlContext}.  If the provided
+     * {@code AccessControlContext} is {@code null},
+     * this method instantiates a new {@code AccessControlContext}
      * with an empty collection of ProtectionDomains.
      *
      * 

      *
-     * @param subject the Subject that the specified
-     *                  action will run as.  This parameter
-     *                  may be null. 

+     * @param subject the {@code Subject} that the specified
+     *                  {@code action} will run as.  This parameter
+     *                  may be {@code null}. 

      *
      * @param  the type of the value returned by the PrivilegedAction's
      *                  {@code run} method.
      *
      * @param action the code to be run as the specified
-     *                  Subject. 

+     *                  {@code Subject}. 

      *
-     * @param acc the AccessControlContext to be tied to the
+     * @param acc the {@code AccessControlContext} to be tied to the
      *                  specified subject and action. 

      *
      * @return the value returned by the PrivilegedAction's
-     *                  run method.
+     *                  {@code run} method.
      *
-     * @exception NullPointerException if the PrivilegedAction
-     *                  is null. 

+     * @exception NullPointerException if the {@code PrivilegedAction}
+     *                  is {@code null}. 

      *
      * @exception SecurityException if the caller does not have permission
      *                  to invoke this method.
@@ -485,41 +485,41 @@
     }
 
     /**
-     * Perform privileged work as a particular Subject.
+     * Perform privileged work as a particular {@code Subject}.
      *
-     * 
 This method behaves exactly as Subject.doAs,
+     * 
 This method behaves exactly as {@code Subject.doAs},
      * except that instead of retrieving the current Thread's
-     * AccessControlContext, it uses the provided
-     * AccessControlContext.  If the provided
-     * AccessControlContext is null,
-     * this method instantiates a new AccessControlContext
+     * {@code AccessControlContext}, it uses the provided
+     * {@code AccessControlContext}.  If the provided
+     * {@code AccessControlContext} is {@code null},
+     * this method instantiates a new {@code AccessControlContext}
      * with an empty collection of ProtectionDomains.
      *
      * 

      *
-     * @param subject the Subject that the specified
-     *                  action will run as.  This parameter
-     *                  may be null. 

+     * @param subject the {@code Subject} that the specified
+     *                  {@code action} will run as.  This parameter
+     *                  may be {@code null}. 

      *
      * @param  the type of the value returned by the
      *                  PrivilegedExceptionAction's {@code run} method.
      *
      * @param action the code to be run as the specified
-     *                  Subject. 

+     *                  {@code Subject}. 

      *
-     * @param acc the AccessControlContext to be tied to the
+     * @param acc the {@code AccessControlContext} to be tied to the
      *                  specified subject and action. 

      *
      * @return the value returned by the
-     *                  PrivilegedExceptionAction's run method.
+     *                  PrivilegedExceptionAction's {@code run} method.
      *
      * @exception PrivilegedActionException if the
-     *                  PrivilegedExceptionAction.run
+     *                  {@code PrivilegedExceptionAction.run}
      *                  method throws a checked exception. 

      *
      * @exception NullPointerException if the specified
-     *                  PrivilegedExceptionAction is
-     *                  null. 

+     *                  {@code PrivilegedExceptionAction} is
+     *                  {@code null}. 

      *
      * @exception SecurityException if the caller does not have permission
      *                  to invoke this method.
@@ -568,19 +568,19 @@
     }
 
     /**
-     * Return the Set of Principals associated with this
-     * Subject.  Each Principal represents
-     * an identity for this Subject.
+     * Return the {@code Set} of Principals associated with this
+     * {@code Subject}.  Each {@code Principal} represents
+     * an identity for this {@code Subject}.
      *
-     * 
 The returned Set is backed by this Subject's
-     * internal Principal Set.  Any modification
-     * to the returned Set affects the internal
-     * Principal Set as well.
+     * 
 The returned {@code Set} is backed by this Subject's
+     * internal {@code Principal} {@code Set}.  Any modification
+     * to the returned {@code Set} affects the internal
+     * {@code Principal} {@code Set} as well.
      *
      * 

      *
-     * @return  The Set of Principals associated with this
-     *          Subject.
+     * @return  The {@code Set} of Principals associated with this
+     *          {@code Subject}.
      */
     public Set getPrincipals() {
 
@@ -590,28 +590,28 @@
     }
 
     /**
-     * Return a Set of Principals associated with this
-     * Subject that are instances or subclasses of the specified
-     * Class.
+     * Return a {@code Set} of Principals associated with this
+     * {@code Subject} that are instances or subclasses of the specified
+     * {@code Class}.
      *
-     * 
 The returned Set is not backed by this Subject's
-     * internal Principal Set.  A new
-     * Set is created and returned for each method invocation.
-     * Modifications to the returned Set
-     * will not affect the internal Principal Set.
+     * 
 The returned {@code Set} is not backed by this Subject's
+     * internal {@code Principal} {@code Set}.  A new
+     * {@code Set} is created and returned for each method invocation.
+     * Modifications to the returned {@code Set}
+     * will not affect the internal {@code Principal} {@code Set}.
      *
      * 

      *
      * @param  the type of the class modeled by {@code c}
      *
-     * @param c the returned Set of Principals will all be
+     * @param c the returned {@code Set} of Principals will all be
      *          instances of this class.
      *
-     * @return a Set of Principals that are instances of the
-     *          specified Class.
+     * @return a {@code Set} of Principals that are instances of the
+     *          specified {@code Class}.
      *
-     * @exception NullPointerException if the specified Class
-     *                  is null.
+     * @exception NullPointerException if the specified {@code Class}
+     *                  is {@code null}.
      */
     public  Set getPrincipals(Class c) {
 
@@ -625,18 +625,18 @@
     }
 
     /**
-     * Return the Set of public credentials held by this
-     * Subject.
+     * Return the {@code Set} of public credentials held by this
+     * {@code Subject}.
      *
-     * 
 The returned Set is backed by this Subject's
-     * internal public Credential Set.  Any modification
-     * to the returned Set affects the internal public
-     * Credential Set as well.
+     * 
 The returned {@code Set} is backed by this Subject's
+     * internal public Credential {@code Set}.  Any modification
+     * to the returned {@code Set} affects the internal public
+     * Credential {@code Set} as well.
      *
      * 

      *
-     * @return  A Set of public credentials held by this
-     *          Subject.
+     * @return  A {@code Set} of public credentials held by this
+     *          {@code Subject}.
      */
     public Set

Package Specification

Package Specification

Package Specification

Package Specification

SASL Overview

Usage

Related Documentation

SASL Overview

Usage

Related Documentation