Class UIPermission

public class UIPermission implements IPermission, 
            IEncodablePermission
{
  // Fields
  public static final int ALLOW_CLIPBOARD;
  public static final int ALLOW_EVENTQUEUEACCESS;
  public static final int ALLOW_FILEDIALOG;
  public static final int ALLOW_TOPLEVELWINDOW;

  // Constructors
  public UIPermission();

  // Methods
  public void check (Object param);
  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 boolean getClipboardAccess();
  public boolean getEventQueueAccessAllowed();
  public boolean getFileDialogsAllowed();
  public boolean getTopLevelWindowCreationAllowed();
  public boolean getWarningBannersRequired();
  public String mapFormat(String format);
  public void reset();
  public void setClipboardAccess(boolean flag);
  public void setEventQueueAccessAllowed(boolean flag);
  public void setFileDialogsAllowed(boolean flag);
  public void setTopLevelWindowCreationAllowed(boolean flag);
  public void setWarningBanners(boolean flag);
  public String[] supportedFormats();
  public String toString();
}

This class represents a permission that controls the ability to use some of the enhanced functionality of the AWT. Specifically, the UI (user interface) permission controls the ability to do the following:

• Create top-level windows
• Access the system clipboard
• Create file dialog boxes
• Access the AWT event queue

You can also use this permission to determine whether top-level windows require warning banners.

The StandardSecurityManager class checks for this permission type when performing the checkFileDialog, checkSystemClipboardAccess, checkAwtEventQueueAccess, and checkTopLevelWindow operations.

This class implements the IPermission and IEncodablePermission interfaces.

Also see com.ms.security.permissions.UIAccessRequest

Constructors

UIPermission

public UIPermission();

Creates a new UIPermission instance. The new instance will not allow access to any of the extended AWT functionality. Specific features must be explicitly turned on to enable access.

Methods

check

public void check (Object param);

Determines if the permission object allows the specified UI operation.

Return Value:

No return value.

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

Exceptions:

SecurityException if this permission does not allow the specified operation.

combine

public IPermission combine (IPermission source2);

Creates and returns a new UIPermission 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 it was constructed from.

Return Value:

Returns the resulting UIPermission object.

Parameter	Description
source2	The UIPermission object to combine with.

Exceptions:

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

compareSet

public int compareSet (Object target);

Compares the UIPermission instance with the 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 UIPermission instance is compared with. This parameter must be an instance of the UIPermission class.

Exceptions:

IllegalArgumentException if the specified Object is not an instance of UIPermission.

copy

public IPermission copy();

Retrieves a copy of this UIPermission object.

Return Value:

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

getClipboardAccess

public boolean getClipboardAccess();

Determines whether the object indicates permission to access the Clipboard.

Return Value:

Returns true if the object indicates permission to access the Clipboard; otherwise, returns false.

getEventQueueAccessAllowed

public boolean getEventQueueAccessAllowed();

Determines whether the permission object indicates the ability to access the AWT event queue.

Return Value:

Returns true if the permission object indicates the ability to access the AWT event queue.

getFileDialogsAllowed

public boolean getFileDialogsAllowed();

Determines whether the permission object indicates the ability to create file dialog boxes.

Return Value:

Returns true if the permission object indicates the ability to create file dialog boxes; otherwise, returns false.

getTopLevelWindowCreationAllowed

public boolean getTopLevelWindowCreationAllowed();

Determines whether the permission object indicates permission to create top-level windows.

Return Value:

Returns true if the permission object indicates permission to create top-level windows; otherwise, returns false.

getWarningBannersRequired

public boolean getWarningBannersRequired();

Determines whether the permission object indicates that top-level windows require warning banners.

Return Value:

Returns true if the permission object indicates that top-level windows require warning banners; 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 a state in which it allows no access to any of the special UI behaviors.

Return Value:

No return value.

setClipboardAccess

public void setClipboardAccess(boolean flag);

Sets the ability to access the system clipboard. If flag is set to true, the permission object will indicate that access to the Clipboard is allowed; otherwise, it will indicate that access to the Clipboard is not allowed.

Return Value:

No return value.

Parameter	Description
flag	The flag that indicates whether access to the Clipboard should be allowed.

setEventQueueAccessAllowed

public void setEventQueueAccessAllowed(boolean flag);

Sets the ability to access the AWT event queue. If flag is set to true, the permission object will indicate that access to the AWT event queue is allowed; otherwise, it will indicate that access to the AWT event queue is not allowed.

Return Value:

No return value.

Parameter	Description
flag	The flag that indicates whether access to the AWT event queue should be allowed.

setFileDialogsAllowed

public void setFileDialogsAllowed(boolean flag);

Sets the ability to use file dialog boxes. If flag is set to true, the permission object will indicate that top-level windows require warning banners; otherwise, it will indicate that top-level windows do not require warning banners.

Return Value:

No return value.

Parameter	Description
flag	The flag that indicates whether top-level windows should require warning banners.

setTopLevelWindowCreationAllowed

public void setTopLevelWindowCreationAllowed(boolean flag);

Sets the ability to create a top-level window. If flag is set to true, the permission object will indicate that top-level window creation is allowed; otherwise, it will indicate that top level window creation is not allowed.

Return Value:

No return value.

Parameter	Description
flag	The flag that indicates whether top-level window creation should be allowed.

setWarningBanners

public void setWarningBanners(boolean flag);

Sets the ability to display warning banners. If flag is set to true, the permission object will indicate that top-level windows require warning banners; otherwise, it will indicate that top-level windows do not require warning banners.

Return Value:

No return value.

Parameter	Description
flag	The flag that indicates whether top-level windows should require warning banners.

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();

Converts the permission object to a textual representation.

Return Value:

Returns the string representation of the permission object.

Fields

ALLOW_CLIPBOARD

Flag that indicates a request for access to the Clipboard.

ALLOW_EVENTQUEUEACCESS

Flag that indicates a request for access to the AWT event queue.

ALLOW_FILEDIALOG

Flag that indicates a request for access to file dialog boxes.

ALLOW_TOPLEVELWINDOW

Flag that indicates a request for the ability to create top level windows.