ServiceRegistry (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.facilities
Class ServiceRegistry

    java.lang.Object
      javacardx.facilities.ServiceRegistry

    @TransactionType(value=NOT_SUPPORTED)
    public final class ServiceRegistry

extends Object

The ServiceRegistry class allows for applications to register SIO-based services which they want to expose to other applications. Service-providing applications (server applications) may typically - but not necessarily - run in contexts different from those of the client applications.

Services are Shareable Interface Objects (SIO). They implement interfaces which extend the `Shareable` interface. Services are uniquely identified in the registry with Service URIs.

Applications actually register a `ServiceFactory` object under a unique Service URI. Other applications may look up the service using that same URI. When looked up the registered service factory is invoked to create or return an instance of the requested service.

Application-defined services are named relatively to their application's service root URI. An application cannot register a service under a URI not rooted in its own namespace. An application, if authorized, may register a service under the standard service namespace rooted at `sio:///standard/`. This namespace defines a set of service URIs for common, well-defined services - such as standard authentication services.

Standard authentication services are registered under the following URIs:

- Global card holder authentication services: `sio:///standard/auth/holder/global/<auth-service-path>` (see `SERVICE_STANDARD_GLOBAL_HOLDER_AUTH_URI`)
- Session card holder authentication services: `sio:///standard/auth/holder/session/<auth-service-path>` (see `SERVICE_STANDARD_SESSION_HOLDER_AUTH_URI`)
- Session user authentication services: `sio:///standard/auth/user/session/<auth-service-path>` (see `SERVICE_STANDARD_SESSION_USER_AUTH_URI`)
- Definition of additional standard authentication services is reserved to the Java Card specifications.

The registry ensures that service factory objects are persistent across card session. Therefore applications do not have to hold on to references on these objects to ensure their persistence. Additionally, the registry provides facilities to retrieve and manage registered service factories.

A service factory remains registered until it is removed from the registry by the application that registered it or when that application is deleted.

Service URIs passed as parameter to the registry methods may be absolute or relative. These URIs are canonicalized, that is resolved then normalized.
If a service URI is absolute, its URI scheme must be "sio". For example, `sio:///transit/pos/ticketbook` is a valid absolute URI. If a service URI is relative, it is resolved against the application's service (SIO) root URI. For example, the relative service URI `ticketbook` may be resolved to `sio:///transit/pos/ticketbook` in the context of the application `///transit/pos`.

The registry implements a fallback mechanism for Classic applet SIO lookup. The registry delegates to the classic Java Card RE SIO lookup mechanism if all the following conditions apply:

- the looked up service URI does not map to any registered service factory
- the calling application (the client) is an applet application
- the looked up service URI translates to an AID
- the optional data parameter is provided, is not null and is assignable to a `byte` primitive type, that is it is a `Byte` instance

The delegation to the classic Java Card RE SIO lookup mechanism is equivalent to invoking the `JCSystem.getAppletShareableInterfaceObject(javacard.framework.AID, byte)` method with the `AID` instance corresponding to the looked up service URI and the optional data parameter converted to a `byte` primitive type. If any of the above conditions does not apply, the lookup operation returns as if no service factory was registered for the looked up service URI.

The service registry operates in the Java Card runtime environment context: it is a permanent Java Card runtime environment Entry Point Object.

Service registry operations are subject to permission checks.

See Runtime Environment Specification for the Java Card Platform, Connected Edition , chapter 7 for details regarding the SIO-based service registry.

Since:
  Java Card 3.0
See Also:
  `ServiceFactory`, `Shareable`

Field Summary
`static String` | `SERVICE_STANDARD_AUTH_URI` The standard authentication service root URI.
`static String` | `SERVICE_STANDARD_GLOBAL_HOLDER_AUTH_URI` The standard global card holder authentication service root URI.
`static String` | `SERVICE_STANDARD_SESSION_HOLDER_AUTH_URI` The standard session card holder authentication service root URI.
`static String` | `SERVICE_STANDARD_SESSION_USER_AUTH_URI` The standard session user authentication service root URI.

Method Summary
`static ServiceRegistry` | `getServiceRegistry()` Retrieves the service registry.
`Enumeration<ServiceFactory>` | `list()` Lists all the service factories registered by the current application.
`Shareable` | `lookup(String serviceURI)` Looks up the service registered with the provided URI.
`Shareable` | `lookup(String serviceURI, Object parameter)` Looks up the service registered with the provided URI.
`Shareable` | `lookup(String serverURI, String serviceURI)` Looks up the service registered with the provided service URI by the server identified by the provided server URI.
`Shareable` | `lookup(String serverURI, String serviceURI, Object parameter)` Looks up the service registered with the provided service URI by the server identified by the provided server URI.
`void` | `register(String serviceURI, ServiceFactory factory)` Registers a service factory with the provided URI.
`void` | `unregister(String serviceURI)` Unregisters the service factory registered by the current application with the provided URI.

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

Field Detail

### SERVICE_STANDARD_AUTH_URI

    public static final String SERVICE_STANDARD_AUTH_URI

  The standard authentication service root URI.

  See Also:
    Constant Field Values

### SERVICE_STANDARD_GLOBAL_HOLDER_AUTH_URI

    public static final String SERVICE_STANDARD_GLOBAL_HOLDER_AUTH_URI

  The standard global card holder authentication service root URI.

  See Also:
    Constant Field Values

### SERVICE_STANDARD_SESSION_HOLDER_AUTH_URI

    public static final String SERVICE_STANDARD_SESSION_HOLDER_AUTH_URI

  The standard session card holder authentication service root URI.

  See Also:
    Constant Field Values

### SERVICE_STANDARD_SESSION_USER_AUTH_URI

    public static final String SERVICE_STANDARD_SESSION_USER_AUTH_URI

  The standard session user authentication service root URI.

  See Also:
    Constant Field Values

Method Detail

### getServiceRegistry

    public static final ServiceRegistry getServiceRegistry()

  Retrieves the service registry.

  Returns:
    the Java Card RE-owned ServiceRegistry singleton instance.

### list

    public Enumeration<ServiceFactory> list()

  Lists all the service factories registered by the current application.

  Returns:
    an enumeration of all the service factories registered by the current application.

### lookup

    public Shareable lookup(String serviceURI)

  Looks up the service registered with the provided URI.

  Before lookup, the provided service URI is canonicalized (resolved against the current application's service (SIO) root URI then normalized). For example, `ticketbook` is a relative URI which may be resolved to `sio:///transit/pos/ticketbook` in the context of the application `///transit/pos`.

  Calling this method is equivalent to calling `lookup(String, Object)` with `parameter` set to `null`.

  Parameters:
    `serviceURI` - the URI of the service to lookup.
  Returns:
    the service SIO registered with the provided URI; or null if no service was registered with the provided service URI.
  Throws:
    `NullPointerException` - if `serviceURI` is null.
    `IllegalArgumentException` - if `serviceURI` is not a well-formed service URI.
    `SecurityException` - if lookup is not granted for the canonicalized service URI.

### lookup

    public Shareable lookup(String serverURI,
                            String serviceURI)

  Looks up the service registered with the provided service URI by the server identified by the provided server URI.

  If the provided server URI is null, then it designates any server that registered the service with the provided service URI.

  Before lookup, the provided server URI is first normalized then the provided service URI is canonicalized (resolved against the server's service root URI then normalized):

  - If the provided service URI is relative, it is resolved against the provided server's service (SIO) root URI, if any.
  - If the provided service URI is relative, and the provided server URI is null, the provided service URI is resolved against the current application's service root URI.

  Calling this method is equivalent to calling `lookup(String, String, Object)` with `parameter` set to `null`.

  Parameters:
    `serverURI` - the application URI of the server of the service to lookup (may be null)
    `serviceURI` - the URI of the service to lookup.
  Returns:
    the service SIO registered with the provided URI; or null if no service was registered with the provided service URI by the designated server application.
  Throws:
    `NullPointerException` - if `serviceURI` is null.
    `IllegalArgumentException` -
    - if `serverURI` is not null and is not a well-formed application URI
    - or, if `serviceURI` is not a well-formed service URI.
    `SecurityException` - if lookup is not granted for the canonicalized service URI.

### lookup

    public Shareable lookup(String serviceURI,
                            Object parameter)

  Looks up the service registered with the provided URI.

  Before lookup, the provided service URI is canonicalized (resolved against the current application's service (SIO) root URI then normalized). For example, `ticketbook` is a relative URI which may be resolved to `sio:///transit/pos/ticketbook` in the context of the application `///transit/pos`.

  Calling this method is equivalent to calling `lookup(String, String, Object)` with `serverURI` set to `null`.

  Parameters:
    `serviceURI` - the URI of the service to lookup.
    `parameter` - an optional parameter (may be null). The parameter may be used by the client to further specify which shareable interface object is being requested. This parameter is passed to the `ServiceFactory.create(java.lang.String, java.lang.Object)` method. Developers must account for context isolation and should typically provide data in the form of an SIO or an "implicitly transferable" object.
  Returns:
    the service SIO registered with the provided URI; or null if no service was registered with the provided service URI.
  Throws:
    `NullPointerException` - if `serviceURI` is null.
    `IllegalArgumentException` - if `serviceURI` is not a well-formed service URI.
    `SecurityException` - if lookup is not granted for the canonicalized service URI.

### lookup

    public Shareable lookup(String serverURI,
                            String serviceURI,
                            Object parameter)

  Looks up the service registered with the provided service URI by the server identified by the provided server URI.

  If the provided server URI is null, then it designates any server that registered the service with the provided service URI.

  Before lookup, the provided server URI is first normalized then the provided service URI is canonicalized (resolved against the server's service root URI then normalized):

  - If the provided service URI is relative, it is resolved against the provided server's service (SIO) root URI, if any.
  - If the provided service URI is relative, and the provided server URI is null, the provided service URI is resolved against the current application's service root URI.

  Parameters:
    `serverURI` - the application URI of the server of the service to lookup (may be null).
    `serviceURI` - the URI of the service to lookup.
    `parameter` - an optional parameter (may be null). The parameter may be used by the client to further specify which shareable interface object is being requested. This parameter is passed to the `ServiceFactory.create(java.lang.String, java.lang.Object)` method. Developers must account for context isolation and should typically provide data in the form of an SIO or an "implicitly transferable" object.
  Returns:
    the service SIO registered with the provided URI; or null if no service was registered with the provided service URI by the designated server application.
  Throws:
    `NullPointerException` - if `serviceURI` is null.
    `IllegalArgumentException` -
    - if `serverURI` is not null and is not a well-formed application URI
    - or, if `serviceURI` is not a well-formed service URI.
    `SecurityException` - if lookup is not granted for the canonicalized service URI.

### register

    public void register(String serviceURI,
                         ServiceFactory factory)

  Registers a service factory with the provided URI.

  Before registration, the provided service URI is canonicalized (resolved against the current application's service (SIO) root URI then normalized). For example, `ticketbook` is a relative URI which may be resolved to `sio:///transit/pos/ticketbook` in the context of the application `///transit/pos`.

  Parameters:
    `serviceURI` - the URI of the service to register.
    `factory` - the ServiceFactory object to be registered.
  Throws:
    `NullPointerException` - if `serviceURI` or `factory` is null.
    `IllegalArgumentException` -
    - if `serviceURI` is not a well-formed service URI,
    - or, if `serviceURI` is in the standard authentication service namespace but is not in one of the standard authenticator sub-namespaces defined above.
    `SecurityException` -
    - if registration is not granted for the canonicalized service URI
    - or, if the service URI is not in the application's or the standard namespace,
    - or, if the factory is not owned by the current application (or its group context).

### unregister

    public void unregister(String serviceURI)

  Unregisters the service factory registered by the current application with the provided URI.

  Before unregistration, the provided service URI is canonicalized (resolved against the current application's service (SIO) root URI then normalized). For example, `ticketbook` is a relative URI which may be resolved to `sio:///transit/pos/ticketbook` in the context of the application `///transit/pos`.

  Parameters:
    `serviceURI` - the URI of the service to unregister.
  Throws:
    `NullPointerException` - if `serviceURI` is null.
    `IllegalArgumentException` - if `serviceURI` is not a well-formed service URI.
    `SecurityException` -
    - if unregistration is not granted for the canonicalized service URI,
    - or, if the service URI is not in the application's or the standard namespace,
    - or if there is a service registered for the provided service URI and the service has not been registered by the current application (such as it can be the case for a service in the standard namespace).

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.