Class PermissionDataSet

public class PermissionDataSet implements IEncodablePermission,
             com.ms.util.SetComparison
{
  // Constructors
  public PermissionDataSet();
  public PermissionDataSet(PermissionDataSet other);

  // Methods
  public synchronized boolean add(PermissionID pid,
        IPermission perm);
  public void adjust (String tag, Object adjustment);
  public void adjustForCodebase(URL codebase);
  public void adjustWithReflectionLoader(ClassLoader cl);
  public void adjustWithThreadGroup(ThreadGroup tg);
  public synchronized PermissionDataSet combine(
        PermissionDataSet other);
  public synchronized int compare(PermissionDataSet other);
  public int compareSet (Object other);
  public synchronized PermissionDataSet copy ();
  public boolean decode(String tag, InputStream data);
  public PermissionDataSetEnumerator elements();
  public boolean encode(String tag, OutputStream out);
  public synchronized IPermission find(PermissionID pid);
  public boolean isFullyTrusted();
  public String mapFormat(String format);
  public void remove(PermissionID pid);
  public void setFullyTrusted(boolean flag);
  public int size();
  public String[] supportedFormats();
  public synchronized PermissionSet toPermissionSet();
  public String toString();
}

This class represents sets of permission objects. Methods are provided for normal container operations such as insertion, deletion, and enumeration.

While in the PermissionDataSet form, the set can be manipulated freely. However, if the PermissionDataSet is converted to a PermissionSet, the new set cannot be modified.

This class implements the IEncodablePermission and the com.ms.util.SetComparison interfaces.

Constructors

PermissionDataSet

public PermissionDataSet();

Creates a new, empty set of permission objects.

PermissionDataSet

public PermissionDataSet(PermissionDataSet other);

Creates a new set of permission objects, based on an existing PermissionDataSet object. The new set will be a copy of the existing set.

Parameter	Description
other	The existing PermissionDataSet object.

Methods

add

public synchronized boolean add(PermissionID pid,IPermission perm);

Adds a permission to the set.

Return Value:

Returns false if a permission of the same type already exists in the set; otherwise, returns true.

Parameter	Description
pid	The permission type.
perm	The permission object.

Remarks:

The permission is specified by its type, and an IPermission instance that corresponds to that type must be specified. If a permission of that type already exists in the set, the add operation fails.

adjust

public void adjust (String tag, Object adjustment);

Adjusts each permission in the set with the given parameters.

Return Value:

No return value.

Parameter	Description
tag	The adjustment type.
adjustment	The adjustment-specific object.

Remarks:

This method calls the adjustPermission method on all of the permission objects in the set that implement the IAdjustablePermission interface.

adjustForCodebase

public void adjustForCodebase(URL codebase);

Adjusts a PermissionDataSet object to include additional access based on a codebase URL.

Return Value:

No return value.

Parameter	Description
codebase	The URL instance to pass as the second parameter when calling the adjustPermission method on the permission objects.

Remarks:

This method calls adjustPermission("codebase",codebase) on all the permission objects in the set that implement the IAdjustablePermission interface.

adjustWithReflectionLoader

public void adjustWithReflectionLoader(ClassLoader cl);

Adjusts a PermissionDataSet with a class loader that indicates whether reflection access to a given class is allowed.

Return Value:

No return value.

Parameter	Description
cl	The class loader instance to pass as the second parameter when calling the adjustPermission method on the permission objects.

Remarks:

This method calls adjustPermission("classloader",cl) on all the permission objects in the set that implement the IAdjustablePermission interface.

adjustWithThreadGroup

public void adjustWithThreadGroup(ThreadGroup tg);

Adjusts a PermissionDataSet object to include additional thread access, based on a master thread group.

Return Value:

No return value.

Parameter	Description
tg	The master thread group that is passed as the second parameter when calling the adjustPermission method on the permission objects.

Remarks:

This method calls adjustPermission("threadgroup",tg) on all the permission objects in the set that implement the IAdjustablePermission interface.

combine

public synchronized PermissionDataSet combine(PermissionDataSet other);

Combines the data in the permission set with another permission set, and returns it as a third permission set.

Return Value:

Returns a new PermissionDataSet object that contains the combined permissions.

Parameter	Description
other	The permission set to combine with the first set.

compare

public synchronized int compare(PermissionDataSet other);

Compares the permissions in the PermissionDataSet object against the permissions in another set.

Return Value:

Returns one of the following com.ms.util.SetComparison result codes:

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

Parameter	Description
other	The second permission set to compare against the first.

compareSet

public int compareSet (Object other);

Compares the PermissionDataSet object to another set.

Return Value:

Returns one of the following com.ms.util.SetComparison result codes:

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

Parameter	Description
other	The object that the PermissionDataSet object is being compared with.

copy

public synchronized PermissionDataSet copy ();

Copies the permission set.

Return Value:

Returns a copy of the set.

decode

public boolean decode(String tag, InputStream data);

Decodes the contents of the specified data stream into a set of permission objects.

Return Value:

Returns true if the decoding process is completed successfully; otherwise, returns false.

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

elements

public PermissionDataSetEnumerator elements();

Returns an enumeration of the permission types stored within this PermissionDataSet object. This method calls the constructor for the PermissionDataSetEnumerator class.

Return Value:

Returns the enumeration object.

encode

public boolean encode(String tag, OutputStream out);

Encodes the contents of the set of permissions and sends 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 process is completed successfully; otherwise, returns false.

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

find

public synchronized IPermission find(PermissionID pid);

Looks for a specific type of permission in the set.

Return Value:

Returns the permission object, if one is found; otherwise, returns null.

Parameter	Description
pid	The type of permission to find.

isFullyTrusted

public boolean isFullyTrusted();

Determines whether the state of the permission set is fully trusted.

Return Value:

Returns true if the permission set is fully trusted; otherwise, returns false.

mapFormat

public String mapFormat(String format);

Given an encoding type, returns a tag which can then be used to perform encode and decode operations.

Return Value:

Returns the permission-specific tag for the specified encoding format. If the specified format is not supported, null is returned.

Parameter	Description
format	The requested encoding format.

remove

public void remove(PermissionID pid);

Removes a permission from the set. If a permission of the specified type exists within the permission set, this method removes it.

Return Value:

No return value.

Parameter	Description
pid	The type of permission to remove.

setFullyTrusted

public void setFullyTrusted(boolean flag);

Sets the fully trusted state of the permission set. If the flag parameter is true, the set is put in the special "fully trusted" state, and it is considered to contain all possible permissions.

Return Value:

No return value.

Parameter	Description
flag	The value that indicates how to set the state. If the value is true, the state will be set to fully trusted. If the value is false, the state will no longer be set to fully trusted.

size

public int size();

Retrieves the number of permissions objects contained in the set.

Return Value:

Returns the number of permission objects in the set.

supportedFormats

public String[] supportedFormats();

Returns the encoding formats that the PermissionDataSet supports.

Return Value:

Returns an array that contains identifiers for the supported formats.

toPermissionSet

public synchronized PermissionSet toPermissionSet();

Turns the PermissionDataSet into a PermissionSet. The PermissionSet form is immutable and can no longer be modified.

Return Value:

Returns the PermissionSet object that is an immutable form of the PermissionDataSet object.

toString

public String toString();

Converts the contents of the PermissionDataSet object to its textual form.

Return Value:

Returns the textual form of the permission data set.