Class PropertyPermission

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

  // Methods
  public void addAllowedSuffix(String suffix);
  public boolean allowsUnrestrictedAccess();
  public void allowUnrestrictedAccess(boolean flag);
  public void check(Object param);
  public IPermission combine(IPermission other);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public void excludeProperties(String pattern);
  public String[] getAllowedSuffixes();
  public WildcardExpression getExcludedProperties();
  public WildcardExpression getIncludedProperties();
  public void includeProperties(String pattern);
  public String mapFormat(String format);
  public String mapFormat(String format);
  public void reset();
  public String[] supportedFormats();
  public String toString();
}

This class represents a permission that controls the ability to access and manipulate the global system properties. The StandardSecurityManager checks for this permission type when performing the checkPropertiesAccess and checkPropertyAccess operations.

This class implements the IPermission and IEncodablePermission interfaces.

Also see com.ms.security.permissions.PropertyAccessRequest

Constructors

PropertyPermission

public PropertyPermission();

Creates a new PropertyPermission instance.

Remarks:

The new instance does not allow access to any of the system properties. To add property names to the allowed set, you can use the allowUnrestrictedAccess, addAllowedSuffix, and the includeProperties methods.

Methods

addAllowedSuffix

public void addAllowedSuffix(String suffix);

Adds an allowed property suffix to the permission object.

Return Value:

No return value.

Parameter	Description
suffix	The property suffix to be added.

Remarks:

Property suffixes work like this: If you have access to a suffix "X", you have access to any system property "Y" if and only if a second system property named "Y.X" exists that is set to "true."

allowsUnrestrictedAccess

public boolean allowsUnrestrictedAccess();

Determines whether this permission object allows unrestricted access to system properties.

Return Value:

Returns true if this permission object allows unrestricted access to system properties.

allowUnrestrictedAccess

public void allowUnrestrictedAccess(boolean flag);

Turns unrestricted property access on or off, depending on the value of the flag. Unrestricted property access allows you to read all system properties, and to obtain the system properties object and manipulate it.

Return Value:

No return value.

Parameter	Description
flag	The flag that indicates whether access to unrestricted properties should be turned on or off.

check

public void check(Object param);

Determines whether the permission allows the system property access specified by the PropertyAccessRequest parameter.

Parameter	Description
param	The security request parameter. It must be an instance of PropertyAccessRequest.

Remarks:

If the PropertyAccessRequest is requesting ALL access, this check will only succeed if this permission object has unrestricted access to the system properties. Otherwise, the PropertyAccessRequest parameter indicates a request for access to a specific system property by name. In this case, the following rules are used to determine whether the check passes or fails.

1. If the permission object allows unrestricted access, the check passes.
2. If the specified property is within the set of explicitly denied properties, the check fails.
3. If the specified property is within the set of explicitly allowed properties, the check succeeds. Otherwise, the check fails.

Exceptions:

SecurityException if this permission does not allow access to the specified system property.

combine

public IPermission combine(IPermission other);

Creates and returns a new PropertyPermission 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 resulting PropertyPermission.

Parameter	Description
other	The PropertyPermission to combine with.

Exceptions:

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

compareSet

public int compareSet(Object target);

Compares the PropertyPermission 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 PropertyPermission instance is compared with.

copy

public IPermission copy();

Retrieves a copy of the PropertyPermission object.

Return Value:

Returns the PropertyPermission object that is a copy of the current PropertyPermission object.

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.

excludeProperties

public void excludeProperties(String pattern);

Explicitly excludes system properties from the set of properties that this permission allows access to.

Return Value:

No return value.

Parameter	Description
pattern	The pattern that specifies the system properties that are explicitly prohibited. This pattern can contain wildcard expressions.

Remarks:

Because access to all system properties is prohibited by default, this method is only useful to remove properties from those explicitly included by a wildcard expression.

For example, the following code allows access to all properties beginning with 'java.', except for the property named "java.class.path".

   ...
   PropertyPermission perm = new PropertyPermission()
   eperm.includeProperties("java.*");
   eperm.excludeProperties("java.class.path");
   ...

Note This method does nothing if the permission object already specifies unrestricted access.

See Also: com.ms.util.WildcardExpression

getAllowedSuffixes

public String[] getAllowedSuffixes();

Retrieves the list of property suffixes that the permission object allows access to.

Return Value:

Returns the list of property suffixes that the permission object allows access to.

getExcludedProperties

public WildcardExpression getExcludedProperties();

Retrieves a wildcard expression that represents all the properties that this permission object explicitly denies access to.

Return Value:

Returns the wildcard expression that represents all the properties that this permission object explicitly denies access to.

See Also: com.ms.util.WildcardExpression

getIncludedProperties

public WildcardExpression getIncludedProperties();

Retrieves a wildcard expression that represents all the properties that this permission object allows access to.

Return Value:

Returns the wildcard expression that represents all the properties that this permission object allows access to.

See Also: com.ms.util.WildcardExpression

includeProperties

public void includeProperties(String pattern);

Adds specific properties to the set of properties that the permission allows access to. The properties are specified by a pattern string that can contain wildcard expressions.

Examples:

  includeProperties("java.class.path");
  includeProperties("java.*");

Note This method does nothing if the permission object already specifies unrestricted access.

Return Value:

No return value.

Parameter	Description
pattern	The pattern that specifies the system properties that can be accessed. This pattern can contain wildcard expressions.

See Also: com.ms.util.WildcardExpression

mapFormat

public String mapFormat(String format);

Retrieves a permission-specific tag when 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.

mapFormat

public String mapFormat(String format);

Retrieves a permission-specific tag when 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 a state in which it allows access to no system properties.

Return Value:

No return value.

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.