Class ThreadPermission

public class ThreadPermission implements IPermission, 
            IEncodablePermission, IAdjustablePermission
{
  // Constructors
  public ThreadPermission();

  // Methods
  public void adjustPermission (String tag, Object adjustment);
  public void check (Object param) throws SecurityException;
  public IPermission combine (IPermission source2);
  public int compareSet (Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public ThreadGroup getAllowedThreadGroup();
  public boolean isThreadAccessUnrestricted();
  public boolean isThreadGroupAccessUnrestricted();
  public String mapFormat(String format);
  public void reset();
  public void setAllowedThreadGroup(ThreadGroup tg);
  public void setUnrestrictedThreadAccess(boolean f);
  public void setUnrestrictedThreadGroupAccess(boolean flag);
  public String[] supportedFormats();
  public String toString();
}

This class represents a permission that controls the ability to create and manipulate threads and thread groups. The StandardSecurityManager class checks for this permission type when performing its checkAccess methods.

You can use a ThreadPermission object to allow unrestricted thread or thread group access. Or, you can specify a ThreadGroup instance that defines a subset of the thread group space, within which the ThreadPermission object allows threading operations to take place.

Constructors

ThreadPermission

public ThreadPermission();

Creates a new ThreadPermission instance that does not allow any threading operations.

Methods

adjustPermission

public void adjustPermission (String tag, Object adjustment);

Adjusts the ThreadPermission object with some runtime state.

Return Value:

No return value.

Parameter	Description
tag	The adjustment type. Any value other than "threadgroup" is ignored.
adjustment	This parameter must be an instance of java.lang.ThreadGroup. It indicates a portion of the thread group space.

Remarks:

The ThreadPermission object only responds to the "threadgroup" adjustment type, and it expects the adjustment parameter to be a ThreadGroup object (in that case). All other adjustment types are ignored.

Usually, a ThreadPermission object allows unrestricted thread and thread group access within a specific ThreadGroup. However, this method can be called to allow a loader to grant some loaded code (an applet, for example) a portion of the thread group space in which it can perform threading operations.

Note The "threadgroup" adjustment to a ThreadPermission object is equivalent to explicitly calling the setAllowedThreadGroup method.

check

public void check (Object param) throws SecurityException;

Determines whether the specified threading object can be manipulated.

Return Value:

No return value.

Parameter	Description
param	The security request parameter. It must be an instance of Thread or ThreadGroup.

Remarks:

If the specified Object is a Thread, the check takes place as follows.

1. If the permission allows unrestricted thread access, the check succeeds.
2. If the Thread exists within the ThreadGroup object associated with this permission or within one of its children, the check succeeds. Otherwise, it fails.

If the specified Object is a ThreadGroup, the check takes place as follows.

1. If the permission allows unrestricted thread group access, the check succeeds.
2. If the ThreadGroup is the ThreadGroup object associated with this permission or one of its children, the check succeeds. Otherwise, it fails.

Exceptions:

SecurityException if the permission does not allow access to the specified threading object.

combine

public IPermission combine (IPermission source2);

Creates and returns a new ThreadPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Return Value:

Returns the ThreadPermission object that results from combining.

Parameter	Description
source2	The other ThreadPermission object to combine with.

Exceptions:

IllegalArgumentException if the specified object to combine with is not an instance of ThreadPermission.

compareSet

public int compareSet (Object target);

Compares the ThreadPermission instance with a specified permission object.

Return Value:

Returns one of the following constants:

• DISJOINT
• EMPTY
• OVERLAP
• EQUAL
• SUBSET
• SUPERSET
• EMPTY_SUBSET
• EMPTY_SUPERSET

Parameter	Description
target	The permission object that the ThreadPermission instance is compared with.

copy

public IPermission copy();

Retrieves a copy of the ThreadPermission instance.

Return Value:

Returns the copy of the ThreadPermission instance.

decode

public boolean decode(String tag, InputStream data);

Decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Return Value:

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameter	Description
tag	The encoding type identifier.
data	The raw data to construct the object from. The type of data is specified by the tag parameter.

encode

public boolean encode(String tag, OutputStream out);

Encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Return Value:

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameter	Description
tag	The encoding type identifier.
out	The output stream to send the encoded data to.

getAllowedThreadGroup

public ThreadGroup getAllowedThreadGroup();

Retrieves the ThreadGroup object that defines the domain in which classes that possess this permission are allowed to perform threading operations.

Return Value:

Returns the thread group that can be manipulated.

isThreadAccessUnrestricted

public boolean isThreadAccessUnrestricted();

Determines whether this permission grants unlimited access to Thread objects.

Return Value:

Returns true if access to Thread objects is unrestricted; otherwise, returns false.

isThreadGroupAccessUnrestricted

public boolean isThreadGroupAccessUnrestricted();

Determines whether this permission grants unlimited access to ThreadGroup objects.

Return Value:

Returns true if access to ThreadGroup objects is unrestricted; otherwise, returns false.

mapFormat

public String mapFormat(String format);

Retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Return Value:

Returns the permission-specific tag that corresponds to the specified format.

Parameter	Description
format	The encoding format to retrieve the tag for.

reset

public void reset();

Resets the permission object to empty, which is a state in which the permission allows no threading operations.

Return Value:

No return value.

setAllowedThreadGroup

public void setAllowedThreadGroup(ThreadGroup tg);

Sets a ThreadGroup that defines the domain in which the permission object allows manipulation of Thread or ThreadGroup objects.

Return Value:

No return value.

Parameter	Description
tg	The thread group that can be manipulated.

Remarks:

Classes that possess this permission can manipulate any threads within this ThreadGroup or within any child ThreadGroup of this ThreadGroup. The permission also allows the manipulation of the specified ThreadGroup or any of its children.

setUnrestrictedThreadAccess

public void setUnrestrictedThreadAccess(boolean f);

Sets the ability to manipulate any Thread object in the system.

Return Value:

No return value.

Parameter	Description
f	The flag that indicates whether to turn unrestricted Thread access on or off. If the value is true, the ability to manipulate all Thread objects is turned on; otherwise, it is turned off.

setUnrestrictedThreadGroupAccess

public void setUnrestrictedThreadGroupAccess(boolean flag);

Sets the ability to manipulate any ThreadGroup object in the system.

Return Value:

No return value.

Parameter	Description
flag	The flag that indicates whether to turn unrestricted ThreadGroup access on or off. If the value is true, the ability to manipulate all ThreadGroup objects is turned on; otherwise, it is turned off.

supportedFormats

public String[] supportedFormats();

Retrieves the encoding formats that the permission type supports.

Return Value:

Returns an array of the supported format identifiers.

toString

public String toString();

Retrieves a textual representation of the permission object.

Return Value:

Returns the string representation of the permission object.