jdk.dio

Class DevicePermission

java.lang.Object

java.security.Permission

jdk.dio.DevicePermission

Direct Known Subclasses:

ADCPermission, ATPermission, CounterPermission, DACPermission, GenericPermission, GPIOPinPermission, GPIOPortPermission, I2CPermission, MMIOPermission, PWMPermission, SPIPermission, UARTPermission, WatchdogTimerPermission

public abstract class DevicePermission
extends java.security.Permission

The DevicePermission abstract class is the superclass of all device permissions.

A DevicePermission permission has a target name and, optionally, a list of actions.

The target name contains hardware addressing information. It takes the following form:

( {controller-spec} ) [ ":" {channel-spec}]

where {controller-spec} and {channel-spec} are defined as follows:

{controller-spec}

The {controller-spec} takes the following form:

{controller-name-spec} | {controller-number} | "*" | ""

where {controller-name-spec} and {controller-number} are defined as follows:

{controller-name-spec}

The {controller-name-spec} string is the string representation of a controller name as may be returned by a call to DeviceConfig.HardwareAddressing.getControllerName. A controller name is Operating System specific such as a device file name on UNIX systems. Occurrences of the semicolon character ( ":") must be escaped with a backslash ("\"). A {controller-name-spec} string that ends with an asterisk ("*") is a prefix pattern that matches all the controller names starting with the same prefix.

{controller-number}

The {controller-number} string is the decimal string representation of a controller number as may be returned by a call to DeviceConfig.HardwareAddressing.getControllerNumber. The characters in the string must all be decimal digits.

A {controller-spec} specification consisting of the asterisk ("*") matches all controller names or numbers. A {controller-spec} specification consisting of the empty string ("") designates an undefined controller name or number that may only be matched by an empty string or an asterisk.

{channel-spec}

The {channel-spec} takes the following form:

{channel-desc} | "*" | ""

where {channel-desc} is defined as follows:

{channel-desc}

The {channel-desc} string is device type-specific and must be defined by subclasses.

A {channel-spec} specification consisting of the asterisk ("*") matches all channels. A {channel-spec} specification consisting of the empty string ("") designates an undefined channel that may only be matched by an empty string or an asterisk.
The DevicePermission abstract class treats the {channel-desc} string as an opaque string: a {channel-spec} string may therefore only be matched by the exact same {channel-spec} string or by the asterisk ("*").

Subclasses of DevicePermission may defined additional specific target name formats to designate devices using their specific hardware addressing information.

The actions to be granted are passed to the constructor in a string containing a list of one or more comma-separated keywords. The supported common actions are open and powermanage. Their meaning is defined as follows:

open

open a device (see DeviceManager.open)

powermanage

manage the power saving mode of a device (see PowerManaged)

Additional actions to be granted may be defined by subclasses of DevicePermission.

Since:

1.0

See Also:

DeviceManager.open, PowerManaged

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	OPEN The open action.
static java.lang.String	POWER_MANAGE The powermanage action.

Constructor Summary

Constructors

Constructor and Description
DevicePermission(java.lang.String name) Constructs a new DevicePermission with the specified target name and the implicit open action.
DevicePermission(java.lang.String name, java.lang.String actions) Constructs a new DevicePermission instance with the specified target name and action list.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(java.lang.Object obj) Checks two DevicePermission objects for equality.
java.lang.String	getActions() Returns the list of possible actions in the following canonical order: open or powermanage.
int	hashCode() Returns the hash code value for this object.
boolean	implies(java.security.Permission permission) Checks if this object "implies" the specified permission.
java.security.PermissionCollection	newPermissionCollection() Returns a new PermissionCollection for storing DevicePermission objects.

Methods inherited from class java.security.Permission

getName, toString

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Field Detail

OPEN

public static final java.lang.String OPEN

The open action.

See Also:

Constant Field Values

POWER_MANAGE

public static final java.lang.String POWER_MANAGE

The powermanage action.

See Also:

Constant Field Values

Constructor Detail

DevicePermission

public DevicePermission(java.lang.String name)

Constructs a new DevicePermission with the specified target name and the implicit open action. The target name is normalized so that leading and trailing spaces are removed and each occurrence of {controller-number} is represented in its canonical decimal representation form (without leading zeros).

Parameters:

name - the target name (as defined above).

Throws:

java.lang.NullPointerException - if name is null.

java.lang.IllegalArgumentException - if name is not properly formatted.

See Also:

getName

DevicePermission

public DevicePermission(java.lang.String name,
                java.lang.String actions)

Constructs a new DevicePermission instance with the specified target name and action list. The target name is normalized so that leading and trailing spaces are removed and each occurrence of {controller-number} is represented in its canonical decimal representation form (without leading zeros).

Parameters:

name - the target name (as defined above).

actions - comma-separated list of device operations: open or powermanage (additional actions may be defined by subclasses).

Throws:

java.lang.NullPointerException - if name is null.

java.lang.IllegalArgumentException -

• if actions is null, empty or contains an action other than the specified possible actions,
• if name is not properly formatted.

See Also:

getName

Method Detail

equals

public boolean equals(java.lang.Object obj)

Checks two DevicePermission objects for equality. Checks that obj's class is the same as this object's class and has the same name (as returned by Permission.getName) and same actions (sorted as per getActions) as this object.

Specified by:

equals in class java.security.Permission

Parameters:

obj - the object to test for equality with this object.

Returns:

true if obj's class is the same as this object's class and has the same target name and actions as this object; false otherwise.

getActions

public java.lang.String getActions()

Returns the list of possible actions in the following canonical order: open or powermanage. Subclasses defining additional actions should always return actions in what they consider to be their canonical form.

Specified by:

getActions in class java.security.Permission

Returns:

comma-separated list of possible actions.

hashCode

public int hashCode()

Returns the hash code value for this object. The hash code is calculated from this permission's name (as returned by Permission.getName) and actions (sorted as per getActions) in a way that ensures that permission1.equals(permission2) implies that permission1.hashCode()==permission2.hashCode() for any two permissions, permission1 and permission2, as required by the general contract of Object.hashCode and the contract of Permission.hashCode.

Specified by:

hashCode in class java.security.Permission

Returns:

a hash code value for this object.

implies

public boolean implies(java.security.Permission permission)

Checks if this object "implies" the specified permission.

More specifically, this method returns true if:

• permission's class is the same as this object's class, and
• permission's actions (as returned by getActions) are a proper subset of this object's action list, and
• permission's hardware addressing information or range thereof is included in this object's hardware addressing information range; the implementation of this method by the DevicePermission abstract class treats the channel description ({channel-desc}) string as an opaque string: a channel specification ({channel-spec}) string may therefore only be matched by the exact same a channel specification string or by the asterisk ("*").

Specified by:

implies in class java.security.Permission

Parameters:

permission - the permission to check against.

Returns:

true if the specified permission is not null and is implied by this object, false otherwise.

newPermissionCollection

public java.security.PermissionCollection newPermissionCollection()

Returns a new PermissionCollection for storing DevicePermission objects.

DevicePermission objects must be stored in a manner that allows them to be inserted into the collection in any order, but that also enables the PermissionCollection.implies method to be implemented in an efficient (and consistent) manner.

For example, assuming a PermissionCollection object containing the two following DevicePermissions:

1. "adc:1", "powermanage"
2. "adc:*", "open"

when calling the implies method on that PermissionCollection object with the DevicePermission:

   "adc:1", "open,powermanage",
 

the implies method must take into account both the "adc:*" and "adc:1" permissions, so the effective permission is "open,powermanage", and implies returns true. The "implies" semantics for DevicePermissions are handled properly by the PermissionCollection object returned by this method. If a device-specific subclass of DevicePermission defines a different "implies" semantics then that subclass must re-implement this method accordingly.

Overrides:

newPermissionCollection in class java.security.Permission

Returns:

a new PermissionCollection suitable for storing DevicePermission.