mirror of
https://github.com/openjdk/jdk.git
synced 2025-08-28 07:14:30 +02:00
8284851: Update javax.crypto files to use proper javadoc for mentioned classes
Reviewed-by: weijun, valeriep
This commit is contained in:
Mark Powers
Valerie Peng
parent
8cdead0c94
commit
f804f2ce8e
92 changed files with 2142 additions and 2010 deletions
|
|
@ -40,27 +40,28 @@ import java.util.NoSuchElementException;
|
|||
import java.util.concurrent.ConcurrentHashMap;
|
||||
|
||||
/**
|
||||
* This class represents a heterogeneous collection of Permissions. That is,
|
||||
* it contains different types of Permission objects, organized into
|
||||
* PermissionCollections. For example, if any
|
||||
* This class represents a heterogeneous collection of permissions.
|
||||
* That is, it contains different types of {@code Permission} objects,
|
||||
* organized into {@code PermissionCollection} objects. For example, if any
|
||||
* {@code java.io.FilePermission} objects are added to an instance of
|
||||
* this class, they are all stored in a single
|
||||
* PermissionCollection. It is the PermissionCollection returned by a call to
|
||||
* the {@code newPermissionCollection} method in the FilePermission class.
|
||||
* Similarly, any {@code java.lang.RuntimePermission} objects are
|
||||
* stored in the PermissionCollection returned by a call to the
|
||||
* {@code newPermissionCollection} method in the
|
||||
* RuntimePermission class. Thus, this class represents a collection of
|
||||
* PermissionCollections.
|
||||
* this class, they are all stored in a single {@code PermissionCollection}.
|
||||
* It is the {@code PermissionCollection} returned by a call to
|
||||
* the {@code newPermissionCollection} method in the {@code FilePermission}
|
||||
* class. Similarly, any {@code java.lang.RuntimePermission} objects are
|
||||
* stored in the {@code PermissionCollection} returned by a call to the
|
||||
* {@code newPermissionCollection} method in the {@code RuntimePermission}
|
||||
* class. Thus, this class represents a collection of
|
||||
* {@code PermissionCollection} objects.
|
||||
*
|
||||
* <p>When the {@code add} method is called to add a Permission, the
|
||||
* Permission is stored in the appropriate PermissionCollection. If no such
|
||||
* collection exists yet, the Permission object's class is determined and the
|
||||
* {@code newPermissionCollection} method is called on that class to create
|
||||
* the PermissionCollection and add it to the Permissions object. If
|
||||
* {@code newPermissionCollection} returns null, then a default
|
||||
* PermissionCollection that uses a hashtable will be created and used. Each
|
||||
* hashtable entry stores a Permission object as both the key and the value.
|
||||
* <p>When the {@code add} method is called to add a {@code Permission}, the
|
||||
* {@code Permission} is stored in the appropriate {@code PermissionCollection}.
|
||||
* If no such collection exists yet, the {@code Permission} object's class is
|
||||
* determined and the {@code newPermissionCollection} method is called on that
|
||||
* class to create the {@code PermissionCollection} and add it to the
|
||||
* {@code Permissions} object. If {@code newPermissionCollection} returns
|
||||
* {@code null}, then a default {@code PermissionCollection} that uses a
|
||||
* hashtable will be created and used. Each hashtable entry stores a
|
||||
* {@code Permission} object as both the key and the value.
|
||||
*
|
||||
* <p> Enumerations returned via the {@code elements} method are
|
||||
* not <em>fail-fast</em>. Modifications to a collection should not be
|
||||
|
|
@ -82,8 +83,8 @@ public final class Permissions extends PermissionCollection
|
|||
implements Serializable
|
||||
{
|
||||
/**
|
||||
* Key is permissions Class, value is PermissionCollection for that class.
|
||||
* Not serialized; see serialization section at end of class.
|
||||
* Key is permissions Class, value is {@code PermissionCollection} for
|
||||
* that class. Not serialized; see serialization section at end of class.
|
||||
*/
|
||||
private transient ConcurrentHashMap<Class<?>, PermissionCollection> permsMap;
|
||||
|
||||
|
|
@ -96,7 +97,8 @@ implements Serializable
|
|||
PermissionCollection allPermission;
|
||||
|
||||
/**
|
||||
* Creates a new Permissions object containing no PermissionCollections.
|
||||
* Creates a new {@code Permissions} object containing no
|
||||
* {@code PermissionCollection} objects.
|
||||
*/
|
||||
public Permissions() {
|
||||
permsMap = new ConcurrentHashMap<>(11);
|
||||
|
|
@ -104,18 +106,19 @@ implements Serializable
|
|||
}
|
||||
|
||||
/**
|
||||
* Adds a permission object to the PermissionCollection for the class the
|
||||
* permission belongs to. For example, if <i>permission</i> is a
|
||||
* FilePermission, it is added to the FilePermissionCollection stored
|
||||
* in this Permissions object.
|
||||
* Adds a {@code Permission} object to the {@code PermissionCollection}
|
||||
* for the class the permission belongs to. For example,
|
||||
* if <i>permission</i> is a {@code FilePermission}, it is added to
|
||||
* the {@code FilePermissionCollection} stored in this
|
||||
* {@code Permissions} object.
|
||||
*
|
||||
* This method creates
|
||||
* a new PermissionCollection object (and adds the permission to it)
|
||||
* if an appropriate collection does not yet exist.
|
||||
* This method creates a new {@code PermissionCollection} object
|
||||
* (and adds the permission to it) if an appropriate collection does
|
||||
* not yet exist.
|
||||
*
|
||||
* @param permission the Permission object to add.
|
||||
* @param permission the {@code Permission} object to add.
|
||||
*
|
||||
* @throws SecurityException if this Permissions object is
|
||||
* @throws SecurityException if this {@code Permissions} object is
|
||||
* marked as readonly.
|
||||
*
|
||||
* @see PermissionCollection#isReadOnly()
|
||||
|
|
@ -139,31 +142,30 @@ implements Serializable
|
|||
}
|
||||
|
||||
/**
|
||||
* Checks to see if this object's PermissionCollection for permissions of
|
||||
* the specified permission's class implies the permissions
|
||||
* expressed in the <i>permission</i> object. Returns true if the
|
||||
* combination of permissions in the appropriate PermissionCollection
|
||||
* (e.g., a FilePermissionCollection for a FilePermission) together
|
||||
* imply the specified permission.
|
||||
* Checks to see if this object's {@code PermissionCollection} for
|
||||
* permissions of the specified permission's class implies the permissions
|
||||
* expressed in the <i>permission</i> object. Returns {@code true} if the
|
||||
* combination of permissions in the appropriate
|
||||
* {@code PermissionCollection} (e.g., a {@code FilePermissionCollection}
|
||||
* for a {@code FilePermission}) together imply the specified permission.
|
||||
*
|
||||
* <p>For example, suppose there is a FilePermissionCollection in this
|
||||
* Permissions object, and it contains one FilePermission that specifies
|
||||
* "read" access for all files in all subdirectories of the "/tmp"
|
||||
* directory, and another FilePermission that specifies "write" access
|
||||
* for all files in the "/tmp/scratch/foo" directory.
|
||||
* Then if the {@code implies} method
|
||||
* <p>For example, suppose there is a {@code FilePermissionCollection}
|
||||
* in this {@code Permissions} object, and it contains one
|
||||
* {@code FilePermission} that specifies "read" access for all files
|
||||
* in all subdirectories of the "/tmp" directory, and another
|
||||
* {@code FilePermission} that specifies "write" access for all files
|
||||
* in the "/tmp/scratch/foo" directory. Then if the {@code implies} method
|
||||
* is called with a permission specifying both "read" and "write" access
|
||||
* to files in the "/tmp/scratch/foo" directory, {@code true} is
|
||||
* returned.
|
||||
*
|
||||
* <p>Additionally, if this PermissionCollection contains the
|
||||
* AllPermission, this method will always return true.
|
||||
* <p>Additionally, if this {@code PermissionCollection} contains the
|
||||
* {@code AllPermission}, this method will always return {@code true}.
|
||||
*
|
||||
* @param permission the Permission object to check.
|
||||
* @param permission the {@code Permission} object to check.
|
||||
*
|
||||
* @return true if "permission" is implied by the permissions in the
|
||||
* PermissionCollection it
|
||||
* belongs to, false if not.
|
||||
* @return {@code true} if "permission" is implied by the permissions in the
|
||||
* {@code PermissionCollection} it belongs to, {@code false} if not.
|
||||
*/
|
||||
@Override
|
||||
public boolean implies(Permission permission) {
|
||||
|
|
@ -183,10 +185,10 @@ implements Serializable
|
|||
}
|
||||
|
||||
/**
|
||||
* Returns an enumeration of all the Permission objects in all the
|
||||
* PermissionCollections in this Permissions object.
|
||||
* Returns an enumeration of all the {@code Permission} objects in all the
|
||||
* {@code PermissionCollection} objects in this {@code Permissions} object.
|
||||
*
|
||||
* @return an enumeration of all the Permissions.
|
||||
* @return an enumeration of all the {@code Permission} objects.
|
||||
*/
|
||||
@Override
|
||||
public Enumeration<Permission> elements() {
|
||||
|
|
@ -197,35 +199,36 @@ implements Serializable
|
|||
}
|
||||
|
||||
/**
|
||||
* Gets the PermissionCollection in this Permissions object for
|
||||
* permissions whose type is the same as that of <i>p</i>.
|
||||
* For example, if <i>p</i> is a FilePermission,
|
||||
* the FilePermissionCollection
|
||||
* stored in this Permissions object will be returned.
|
||||
* Gets the {@code PermissionCollection} in this {@code Permissions}
|
||||
* object for permissions whose type is the same as that of <i>p</i>.
|
||||
* For example, if <i>p</i> is a {@code FilePermission},
|
||||
* the {@code FilePermissionCollection} stored in this {@code Permissions}
|
||||
* object will be returned.
|
||||
*
|
||||
* If createEmpty is true,
|
||||
* this method creates a new PermissionCollection object for the specified
|
||||
* type of permission objects if one does not yet exist.
|
||||
* If {@code createEmpty} is {@code true},
|
||||
* this method creates a new {@code PermissionCollection} object for the
|
||||
* specified type of permission objects if one does not yet exist.
|
||||
* To do so, it first calls the {@code newPermissionCollection} method
|
||||
* on <i>p</i>. Subclasses of class Permission
|
||||
* on <i>p</i>. Subclasses of class {@code Permission}
|
||||
* override that method if they need to store their permissions in a
|
||||
* particular PermissionCollection object in order to provide the
|
||||
* particular {@code PermissionCollection} object in order to provide the
|
||||
* correct semantics when the {@code PermissionCollection.implies}
|
||||
* method is called.
|
||||
* If the call returns a PermissionCollection, that collection is stored
|
||||
* in this Permissions object. If the call returns null and createEmpty
|
||||
* is true, then
|
||||
* this method instantiates and stores a default PermissionCollection
|
||||
* If the call returns a {@code PermissionCollection}, that collection is
|
||||
* stored in this {@code Permissions} object. If the call returns
|
||||
* {@code null} and {@code createEmpty} is {@code true}, then this method
|
||||
* instantiates and stores a default {@code PermissionCollection}
|
||||
* that uses a hashtable to store its permission objects.
|
||||
*
|
||||
* createEmpty is ignored when creating empty PermissionCollection
|
||||
* for unresolved permissions because of the overhead of determining the
|
||||
* PermissionCollection to use.
|
||||
* {@code createEmpty} is ignored when creating empty
|
||||
* {@code PermissionCollection} for unresolved permissions because of the
|
||||
* overhead of determining the {@code PermissionCollection} to use.
|
||||
*
|
||||
* createEmpty should be set to false when this method is invoked from
|
||||
* implies() because it incurs the additional overhead of creating and
|
||||
* adding an empty PermissionCollection that will just return false.
|
||||
* It should be set to true when invoked from add().
|
||||
* {@code createEmpty} should be set to {@code false} when this method is
|
||||
* invoked from implies() because it incurs the additional overhead of
|
||||
* creating and adding an empty {@code PermissionCollection} that will
|
||||
* just return {@code false}.
|
||||
* It should be set to {@code true} when invoked from add().
|
||||
*/
|
||||
private PermissionCollection getPermissionCollection(Permission p,
|
||||
boolean createEmpty) {
|
||||
|
|
@ -281,7 +284,7 @@ implements Serializable
|
|||
* @param p the type of unresolved permission to resolve
|
||||
*
|
||||
* @return PermissionCollection containing the unresolved permissions,
|
||||
* or null if there were no unresolved permissions of type p.
|
||||
* or {@code null} if there were no unresolved permissions of type p.
|
||||
*
|
||||
*/
|
||||
private PermissionCollection getUnresolvedPermissions(Permission p)
|
||||
|
|
@ -348,7 +351,8 @@ implements Serializable
|
|||
|
||||
/**
|
||||
* @serialField perms java.util.Hashtable
|
||||
* A table of the Permission classes and PermissionCollections.
|
||||
* A table of the {@code Permission} classes and
|
||||
* {@code PermissionCollection} objects.
|
||||
* @serialField allPermission java.security.PermissionCollection
|
||||
*/
|
||||
@java.io.Serial
|
||||
|
|
@ -488,7 +492,8 @@ final class PermissionsEnumerator implements Enumeration<Permission> {
|
|||
}
|
||||
|
||||
/**
|
||||
* A PermissionsHash stores a homogeneous set of permissions in a hashtable.
|
||||
* A {@code PermissionsHash} stores a homogeneous set of permissions in a
|
||||
* hashtable.
|
||||
*
|
||||
* @see Permission
|
||||
* @see Permissions
|
||||
|
|
@ -509,16 +514,16 @@ implements Serializable
|
|||
private transient ConcurrentHashMap<Permission, Permission> permsMap;
|
||||
|
||||
/**
|
||||
* Create an empty PermissionsHash object.
|
||||
* Create an empty {@code PermissionsHash} object.
|
||||
*/
|
||||
PermissionsHash() {
|
||||
permsMap = new ConcurrentHashMap<>(11);
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds a permission to the PermissionsHash.
|
||||
* Adds a permission to the {@code PermissionsHash}.
|
||||
*
|
||||
* @param permission the Permission object to add.
|
||||
* @param permission the {@code Permission} object to add.
|
||||
*/
|
||||
@Override
|
||||
public void add(Permission permission) {
|
||||
|
|
@ -529,10 +534,10 @@ implements Serializable
|
|||
* Check and see if this set of permissions implies the permissions
|
||||
* expressed in "permission".
|
||||
*
|
||||
* @param permission the Permission object to compare
|
||||
* @param permission the {@code Permission} object to compare
|
||||
*
|
||||
* @return true if "permission" is a proper subset of a permission in
|
||||
* the set, false if not.
|
||||
* @return {@code true} if "permission" is a proper subset of a permission
|
||||
* in the set, {@code false} if not.
|
||||
*/
|
||||
@Override
|
||||
public boolean implies(Permission permission) {
|
||||
|
|
@ -553,9 +558,10 @@ implements Serializable
|
|||
}
|
||||
|
||||
/**
|
||||
* Returns an enumeration of all the Permission objects in the container.
|
||||
* Returns an enumeration of all the {@code Permission} objects in the
|
||||
* container.
|
||||
*
|
||||
* @return an enumeration of all the Permissions.
|
||||
* @return an enumeration of all the {@code Permission} objects.
|
||||
*/
|
||||
@Override
|
||||
public Enumeration<Permission> elements() {
|
||||
|
|
@ -569,7 +575,7 @@ implements Serializable
|
|||
// private Hashtable perms;
|
||||
/**
|
||||
* @serialField perms java.util.Hashtable
|
||||
* A table of the Permissions (both key and value are same).
|
||||
* A table of the permissions (both key and value are same).
|
||||
*/
|
||||
@java.io.Serial
|
||||
private static final ObjectStreamField[] serialPersistentFields = {
|
||||
|
|
@ -599,8 +605,8 @@ implements Serializable
|
|||
}
|
||||
|
||||
/**
|
||||
* Reads in a Hashtable of Permission/Permission and saves them in the
|
||||
* permsMap field.
|
||||
* Reads in a {@code Hashtable} of Permission/Permission and saves them
|
||||
* in the permsMap field.
|
||||
*
|
||||
* @param in the {@code ObjectInputStream} from which data is read
|
||||
* @throws IOException if an I/O error occurs
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue