URIPermission (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacardx.security
Class URIPermission

    java.lang.Object
      java.security.Permission
          javacardx.security.URIPermission

Direct Known Subclasses:
  ConnectorPermission, ContextPermission, EventRegistryPermission, ServiceRegistryPermission

    @TransactionType(value=NOT_SUPPORTED)
    public class URIPermission

extends Permission

The URIPermission class extends the Permission class, and can be used as the base class for all permissions that use URIs (Uniform Resource Identifiers) as target names.

The target name represents the URI of a resource: an application, an SIO, an event... The target name may be either:

- an exact URI pattern which designates exactly one resource
- or, a pattern which may designate a collection of resources:
  - a path-prefix pattern ending with a "/*", which may designate a collection of resources
  - an application-generic-path pattern starting with "/~" , which may designate a resource or collection of resources in the current application's namespace
  - a registry-based authority pattern whose registry name equals "*"
  - a server-based authority pattern whose DNS hostname - if one specified - starts with "*." or equals "*" or whose port number - if one specified - equals "*"
  - any combination of the above

For example, `sio:///transit/pos/ticketbook` designates exactly the Shareable Interface Object identified by the `sio:///transit/pos/ticketbook` URI; the URI `sio:///transit/pos/*` designates all the Shareable Interface Objects identified by a URI starting with `sio:///transit/pos/`. The URI `sio:///~/ticketbook` in the context of the application `///transit/pos/` designates the Shareable Interface Object identified by the `sio:///transit/pos/ticketbook` URI, and designates the Shareable Interface Object identified by the `sio:///theater/ticketbook` in the context of the application `///theater/`. The URI `http://*.sun.com:*/*` designates any resource on any host in the `sun.com` DNS domain accessible via the HTTP protocol on any port.

Note that when a target name is a path prefix URI pattern, the root of the namespace designated by the path prefix URI pattern is not itself included in the set of targeted resources. The path prefix pattern `sio:///transit/pos/*` does not include `sio:///transit/pos`. The path prefix pattern `file:///transit/pos/logs/*` does not include the directory designated by `file:///transit/pos/logs`.

URIs of protected resources other than application URIs must be absolute - that is they must include a protocol (URI scheme). URIs are normalized before interpretation.

The actions to be granted are passed to the constructors in a string containing a list of one or more comma-separated keywords. The possible keywords are application or library-specific.

The actions string is canonicalized before processing, that is, it is converted to lowercase and sorted in lexical order.

Since:
  Java Card 3.0
See Also:
  `Permission`, `AccessController`, `AccessControlException`

Constructor Summary
`URIPermission(String uri)` Creates a new URIPermission object with no actions.
`URIPermission(String uri, String actions)` Creates a new URIPermission object with the specified actions.
`URIPermission(String scheme, String uri, String actions)` Creates a new URIPermission object with the specified actions.

Method Summary
`boolean` | `equals(Object obj)` Checks two URIPermission objects for equality.
`String` | `getActions()` Returns the "canonical string representation" of the actions.
`protected String[]` | `getPossibleActions()` Returns an array of all the possible actions in canonical order.
`int` | `hashCode()` Returns the hash code value.
`boolean` | `implies(Permission p)` Checks if the specified permission is "implied" by this object.

Methods inherited from class java.security.Permission
`getName, toString`

Methods inherited from class java.lang.Object
`getClass, notify, notifyAll, wait, wait, wait`

Constructor Detail

### URIPermission

    public URIPermission(String uri)

  Creates a new URIPermission object with no actions. uri is the URI of a resource other than an application: an SIO, an event...

  A URI whose path component ends in "/*" is a path-prefix URI pattern which matches all resources under the namespace designated by the path prefix.

  Calling this constructor is equivalent to calling the `URIPermission(String, String)` constructor with the `actions` parameter set to `null` or to the empty string `""`.

  Parameters:
    `uri` - an exact or path-prefix URI pattern designating a set of resources.
  Throws:
    `NullPointerException` - if `uri` is `null`.
    `IllegalArgumentException` - if `uri` is not a well-formed absolute URI
    `SecurityException` - if `uri` is not accessible in the caller's context.

### URIPermission

    public URIPermission(String uri,
                         String actions)

  Creates a new URIPermission object with the specified actions. uri is the URI of a resource other than an application: an SIO, an event... actions is the list of actions. Possible actions are application or library specific.

  A URI whose path component ends in "/*" is a path-prefix URI pattern which matches all resources under the namespace designated by the path prefix.

  The actions list for the `URIPermission` base class is not constrained. That is, a direct instance of the `URIPermission` base class can be created with any actions list (including an empty or null actions list).

  Parameters:
    `uri` - an exact or path-prefix URI pattern designating a set of resources.
    `actions` - the action string (may be null or empty).
  Throws:
    `NullPointerException` - if `uri` is `null`.
    `IllegalArgumentException` - if `uri` is not a well-formed absolute URI.
    `SecurityException` - if `uri` or `actions` is not accessible in the caller's context.

### URIPermission

    public URIPermission(String scheme,
                         String uri,
                         String actions)

  Creates a new URIPermission object with the specified actions. uri is the URI of a resource: an application, an SIO, an event... scheme is the scheme for the resource URI. actions is the list of actions. Possible actions are application or library specific.

  A URI whose path component ends in "/*" is a path-prefix URI pattern which matches all resources under the namespace designated by the path prefix.

  The actions list for the `URIPermission` base class is not constrained. That is, a direct instance of the `URIPermission` base class can be created with any actions list (including an empty or null actions list).

  This constructor is used for permissions whose target name denotes an application URI (a relative URI that starts with "//") or another resource URI which has a defined scheme.

  - If the provided scheme is null and the provided uri is relative then the uri designates an application.
  - If the provided scheme is not null and the provided uri is absolute, then the provided uri's scheme must match the provided scheme.
  - If the provided scheme is not null and the provided uri is relative, then the provided uri is resolved against the current application's URI for the provided scheme.

  Parameters:
    `scheme` - the scheme of the resource URI.
    `uri` - an exact or path-prefix URI pattern designating a set of resources.
    `actions` - the action string (may be null or empty).
  Throws:
    `NullPointerException` - if `uri` is `null`.
    `IllegalArgumentException` -
    - if `uri` is not a well-formed URI (relative or absolute),
    - or, if `uri` is absolute and `scheme` is not null but `uri`'s scheme does not match `scheme`,
    - or, if `uri` is relative and `scheme` is null but `uri` is not a well-formed application URI.
    `SecurityException` - if `scheme`, `uri` or `actions` is not accessible in the caller's context.
  See Also:
    `ContextPermission`

Method Detail

### equals

    public boolean equals(Object obj)

  Checks two URIPermission objects for equality. Checks that obj's class is the same as this object's class and has the same URI and actions as this object.

  Specified by:
    `equals` in class `Permission`
  Parameters:
    `obj` - the object we are testing for equality with this object.
  Returns:
    true if obj's class is the same as this object's class, and has the same URI and actions as this URIPermission object, false otherwise.
  See Also:
    `Boolean.hashCode()`, `Hashtable`

### getActions

    public String getActions()

  Returns the "canonical string representation" of the actions. That is, this method always returns actions in the lexical order. For example, if this URIPermission object allows both debit and credit actions, a call to `getActions` will return the string "credit,debit".

  If this permission has no actions then this method returns the empty string "".

  Specified by:
    `getActions` in class `Permission`
  Returns:
    the canonical string representation of the actions, or the empty string "" if this permission has no actions.

### getPossibleActions

    protected String[] getPossibleActions()

  Returns an array of all the possible actions in canonical order. That is, this method always returns the list of possible actions in the lexical order.

  Since the actions list for the `URIPermission` base class is not constrained, this method's default implementation returns null.

  Note: This method is intended to be reimplemented by subclasses and can be used to determine if an action passed as parameter to the constructors is one of the possible (supported) action for the permission type defined by the subclass:

  - If this method returns an empty array then the permission type defined by the subclass does not support any actions.
  - If this method returns null then the permission type defined by the subclass allow for any action (actions are not constrained).
  - If this method returns a non-empty array then only the actions listed must be accepted.
  Implementation of this method must guarantee the immutability of `URIPermission` objects, such as by returning a defensive copy of the original array.

  Returns:
    null (i.e., the actions are not constrained).

### hashCode

    public int hashCode()

  Returns the hash code value.

  Specified by:
    `hashCode` in class `Permission`
  Returns:
    a hash code value for this object.
  See Also:
    `Object.equals(java.lang.Object)`, `Hashtable`

### implies

    public boolean implies(Permission p)

  Checks if the specified permission is "implied" by this object.

  More specifically, this method returns true if:

  - p's class is the same as this object's class, and
  - p's actions are a subset of this object's actions, and
  - p's URI equals or (in the case of a path prefix pattern) is implied by this object's URI. For example, `sio:///transit/pos/*` implies `sio:///transit/pos/ticketbook`. Note that the query and fragment components of both URIs are ignored for this test.

  Specified by:
    `implies` in class `Permission`
  Parameters:
    `p` - the permission to check against.
  Returns:
    true if the passed permission is equal to or implied by this permission, false otherwise.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.