Class ExecutionPermission

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

  // Methods
  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 excludeApplications(String pattern);
  public WildcardExpression getExcludedApplications();
  public WildcardExpression getIncludedApplications();
  public void includeApplications(String pattern);
  public boolean isUnrestricted();
  public String mapFormat(String format);
  public void reset ();
  public void setUnrestricted(boolean flag);
  public String[] supportedFormats();
  public String toString();
}

This class represents a permission that controls the ability to run other programs. The StandardSecurityManager checks for this permission type when performing the checkExec operation.

Also see com.ms.security.permissions.ExecutionRequest

Constructors

ExecutionPermission

public ExecutionPermission ();

Creates a new ExecutionPermission instance.

Remarks:

The new instance does not allow access for executing applications. Use either the setUnrestricted or includeApplications methods to add applications to the permission.

Methods

check

public void check(Object param);

Determines whether the permission allows the applications specified in an ExecutionRequest object to be executed.

Return Value:

No return value.

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

Remarks:

The following rules are used to determine whether the check passes or fails.

1. If this permission object allows unrestricted access, the check passes.
2. If the specified application is within the set of explicitly denied applications, the check fails.
3. If the specified application is within the set of explicitly allowed applications, the check succeeds; otherwise, it fails.

Exceptions:

SecurityException if this permission does not allow the specified program to run.

combine

public IPermission combine(IPermission other);

Creates and returns a new ExecutionPermission 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 ExecutionPermission object.

Parameter	Description
other	The ExecutionPermission object to combine with.

Exceptions:

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

compareSet

public int compareSet (Object target);

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

copy

public IPermission copy();

Retrieves a copy of the ExecutionPermission instance.

Return Value:

Returns a copy of the ExecutionPermission 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.

excludeApplications

public void excludeApplications(String pattern);

Explicitly excludes applications from the set of programs that the permission allows.

Return Value:

No return value.

Parameter	Description
pattern	The pattern that specifies the applications that are explicitly prohibited. It can contain wildcard expressions.

Remarks:

Because all applications are prohibited by default, this call is only useful to remove programs from an expression that was previously added with an includeApplications call.

For example, the following code creates an ExecutionPermission object that allows access to all .exe applications, except Notepad.exe.

   ...
   ExecutionPermission eperm = new ExecutionPermission()
   eperm.includeApplications("*.exe");
   eperm.excludeApplications("notepad.exe");
   ...
	

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

See Also: com.ms.util.WildcardExpression

getExcludedApplications

public WildcardExpression getExcludedApplications();

Retrieves a WildcardExpression instance that contains all the applications that have been explicitly denied.

Return Value:

Returns a wildcard expression that contains the denied applications.

getIncludedApplications

public WildcardExpression getIncludedApplications();

Retrieves a WildcardExpression instance that contains all the applications that have been explicitly included in the set of programs that the permission allows.

Return Value:

Returns the wildcard expression that contains the allowed applications.

includeApplications

public void includeApplications(String pattern);

Adds specific applications to the set of programs that the permission allows. Applications are specified by a pattern string that can contain wildcard expressions.

Examples:

  includeApplications("notepad.exe");
  includeApplications("c:\\anything\\*.exe");

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 applications that are allowed. It can contain wildcard expressions.

See Also: com.ms.util.WildcardExpression

isUnrestricted

public boolean isUnrestricted();

Determines whether the permission object allows unrestricted access to execute applications.

Return Value:

Returns true if the permission object allows unrestricted access to execute applications; otherwise, returns false.

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 so that it no longer allows access for executing applications.

Return Value:

No return value.

setUnrestricted

public void setUnrestricted(boolean flag);

Turns the unrestricted state of this permission object on or off.

Return Value:

No return value.

Parameter	Description
flag	The flag that indicates whether to turn the unrestricted state on or off. If true, this method turns the unrestricted state on; otherwise, this method turns the unrestricted state off.

Remarks:

If the unrestricted state is on, the permission object allows any application to be executed by the classes that possess this permission. If the unrestricted state is off, the permission allows only the execution of applications explicitly specified by the includeApplications method. By default, the unrestricted state is 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.