javacardx.facilities
Class ServiceRegistry

java.lang.Object
  extended by 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:

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 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):

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):

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).


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