archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 06:45:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8284851: Update javax.crypto files to use proper javadoc for mentioned classes

Browse source 
Reviewed-by: weijun, valeriep
This commit is contained in:
Mark Powers 2022-07-07 23:20:58 +00:00 • committed by Valerie Peng
parent 8cdead0c94
commit f804f2ce8e
92 changed files with 2142 additions and 2010 deletions
Download patch file Download diff file Expand all files Collapse all files

118
src/java.base/share/classes/java/security/PermissionCollection.java
View file

@ -32,7 +32,7 @@ import java.util.stream.StreamSupport;
/**
* Abstract class representing a collection of Permission objects.
*
* <p>With a PermissionCollection, you can:
* <p>With a {@code PermissionCollection}, you can:
* <UL>
* <LI> add a permission to the collection using the {@code add} method.
* <LI> check to see if a particular permission is implied in the
@ -40,46 +40,49 @@ import java.util.stream.StreamSupport;
* <LI> enumerate all the permissions, using the {@code elements} method.
* </UL>
*
* <p>When it is desirable to group together a number of Permission objects
* of the same type, the {@code newPermissionCollection} method on that
* particular type of Permission object should first be called. The default
* behavior (from the Permission class) is to simply return null.
* Subclasses of class Permission override the method if they need to store
* their permissions in a particular PermissionCollection object in order
* to provide the correct semantics when the
* {@code PermissionCollection.implies} method is called.
* If a non-null value is returned, that PermissionCollection must be used.
* If null is returned, then the caller of {@code newPermissionCollection}
* is free to store permissions of the
* given type in any PermissionCollection they choose
* (one that uses a Hashtable, one that uses a Vector, etc.).
* <p>When it is desirable to group together a number of {@code Permission}
* objects of the same type, the {@code newPermissionCollection} method on that
* particular type of {@code Permission} object should first be called. The
* default behavior (from the {@code Permission} class) is to simply return
* {@code null}. Subclasses of class {@code Permission} override the method if
* they need to store their permissions in a particular
* {@code PermissionCollection} object in order to provide the correct
* semantics when the {@code PermissionCollection.implies} method is called.
* If a non-null value is returned, that {@code PermissionCollection} must be
* used. If {@code null} is returned, then the caller of
* {@code newPermissionCollection} is free to store permissions of the
* given type in any {@code PermissionCollection} they choose
* (one that uses a {@code Hashtable}, one that uses a {@code Vector}, etc.).
*
* <p>The PermissionCollection returned by the
* {@code Permission.newPermissionCollection}
* method is a homogeneous collection, which stores only Permission objects
* for a given Permission type. A PermissionCollection may also be
* heterogeneous. For example, Permissions is a PermissionCollection
* subclass that represents a collection of PermissionCollections.
* That is, its members are each a homogeneous PermissionCollection.
* For example, a Permissions object might have a FilePermissionCollection
* for all the FilePermission objects, a SocketPermissionCollection for all the
* SocketPermission objects, and so on. Its {@code add} method adds a
* <p>The collection returned by the {@code Permission.newPermissionCollection}
* method is a homogeneous collection, which stores only {@code Permission}
* objects for a given permission type. A {@code PermissionCollection} may
* also be heterogeneous. For example, {@code Permissions} is a
* {@code PermissionCollection} subclass that represents a collection of
* {@code PermissionCollection} objects.
* That is, its members are each a homogeneous {@code PermissionCollection}.
* For example, a {@code Permission} object might have a
* {@code FilePermissionCollection} for all the {@code FilePermission} objects,
* a {@code SocketPermissionCollection} for all the {@code SocketPermission}
* objects, and so on. Its {@code add} method adds a
* permission to the appropriate collection.
*
* <p>Whenever a permission is added to a heterogeneous PermissionCollection
* such as Permissions, and the PermissionCollection doesn't yet contain a
* PermissionCollection of the specified permission's type, the
* PermissionCollection should call
* <p>Whenever a permission is added to a heterogeneous
* {@code PermissionCollection} such as {@code Permissions}, and the
* {@code PermissionCollection} doesn't yet contain a
* {@code PermissionCollection} of the specified permission's type, the
* {@code PermissionCollection} should call
* the {@code newPermissionCollection} method on the permission's class
* to see if it requires a special PermissionCollection. If
* to see if it requires a special {@code PermissionCollection}. If
* {@code newPermissionCollection}
* returns null, the PermissionCollection
* is free to store the permission in any type of PermissionCollection it
* desires (one using a Hashtable, one using a Vector, etc.). For example,
* the Permissions object uses a default PermissionCollection implementation
* that stores the permission objects in a Hashtable.
* returns {@code null}, the {@code PermissionCollection}
* is free to store the permission in any type of {@code PermissionCollection}
* it desires (one using a {@code Hashtable}, one using a {@code Vector}, etc.).
* For example, the {@code Permissions} object uses a default
* {@code PermissionCollection} implementation that stores the permission
* objects in a {@code Hashtable}.
*
* <p> Subclass implementations of PermissionCollection should assume
* <p> Subclass implementations of {@code PermissionCollection} should assume
* that they may be called simultaneously from multiple threads,
* and therefore should be synchronized properly. Furthermore,
* Enumerations returned via the {@code elements} method are
@ -116,9 +119,10 @@ public abstract class PermissionCollection implements java.io.Serializable {
*
* @param permission the Permission object to add.
*
* @throws SecurityException if this PermissionCollection object
* has been marked readonly
* @throws IllegalArgumentException if this PermissionCollection
* @throws SecurityException if this {@code PermissionCollection}
* object has been marked readonly
* @throws IllegalArgumentException if this
* {@code PermissionCollection}
* object is a homogeneous collection and the permission
* is not of the correct type.
*/
@ -126,12 +130,13 @@ public abstract class PermissionCollection implements java.io.Serializable {
/**
* Checks to see if the specified permission is implied by
* the collection of Permission objects held in this PermissionCollection.
* the collection of {@code Permission} objects held in this
* {@code PermissionCollection}.
*
* @param permission the Permission object to compare.
* @param permission the {@code Permission} object to compare.
*
* @return true if "permission" is implied by the permissions in
* the collection, false if not.
* @return {@code true} if "permission" is implied by the permissions in
* the collection, {@code false} if not.
*/
public abstract boolean implies(Permission permission);
@ -168,32 +173,32 @@ public abstract class PermissionCollection implements java.io.Serializable {
}
/**
* Marks this PermissionCollection object as "readonly". After
* a PermissionCollection object
* is marked as readonly, no new Permission objects can be added to it
* using {@code add}.
* Marks this {@code PermissionCollection} object as "readonly". After
* a {@code PermissionCollection} object
* is marked as readonly, no new {@code Permission} objects
* can be added to it using {@code add}.
*/
public void setReadOnly() {
readOnly = true;
}
/**
* Returns true if this PermissionCollection object is marked as readonly.
* If it is readonly, no new Permission objects can be added to it
* using {@code add}.
* Returns {@code true} if this {@code PermissionCollection} object is
* marked as readonly. If it is readonly, no new {@code Permission}
* objects can be added to it using {@code add}.
*
* <p>By default, the object is <i>not</i> readonly. It can be set to
* readonly by a call to {@code setReadOnly}.
*
* @return true if this PermissionCollection object is marked as readonly,
* false otherwise.
* @return {@code true} if this {@code PermissionCollection} object is
* marked as readonly, {@code false} otherwise.
*/
public boolean isReadOnly() {
return readOnly;
}
/**
* Returns a string describing this PermissionCollection object,
* Returns a string describing this {@code PermissionCollection} object,
* providing information about all the permissions it contains.
* The format is:
* <pre>
@ -205,12 +210,13 @@ public abstract class PermissionCollection implements java.io.Serializable {
*
* {@code super.toString} is a call to the {@code toString}
* method of this
* object's superclass, which is Object. The result is
* this PermissionCollection's type name followed by this object's
* object's superclass, which is {@code Object}. The result is
* this collection's type name followed by this object's
* hashcode, thus enabling clients to differentiate different
* PermissionCollections object, even if they contain the same permissions.
* {@code PermissionCollection} objects, even if they contain the
* same permissions.
*
* @return information about this PermissionCollection object,
* @return information about this {@code PermissionCollection} object,
* as described above.
*
*/