Use is subject to License Terms. Your use of this web site or any of its contents or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

Java™ 2 Platform, Micro Edition Content Handler API (Final Release, June 3, 2005)

javax.microedition.content
Class Registry

java.lang.Object
  extended byjavax.microedition.content.Registry

public class Registry
extends java.lang.Object

The Registry provides method to invoke, register, unregister, and query information about content handlers. An application registers, for each content handler, zero or more content types, suffixes, and actions. Access to the registry is via the getRegistry method. The Registry class is thread safe. Applications are responsible for the thread safety of Invocation objects passed as arguments to Registry methods.

Multiple content handlers can be registered for each type, suffix, and action. The types, suffixes, and actions registered for a handler can be used to select a handler. The content handler ID is set during registration and is used to uniquely identify the content handler and to enforce access controls.

A content handler is any application that is registered to handle some content. It responds to requests and displays or acts on the content. Registration can occur dynamically or statically. Static registration occurs during the installation of the application package, while dynamic registration occurs via this API. A content handler may be a Java or a non-Java application. For example, MIDlet suites and Personal Basis Profile applications using the Xlet application model can be content handlers. Refer to the ContentHandler class for information on registering Java platform content handlers.

When a content handler is processing an invocation, it may be necessary to invoke another content handler before it is able to satisfy the first request. The invocation and chaining of content handlers is managed to maintain the context and sequence across application executions.

The term application is used more generally than the term content handler. The term application is used to refer to the common handling for making requests, handling responses, and querying the content handler registrations. The term content handler is used for an application that registers for types, suffixes, actions, etc. and processes the requests queued to it.

Content Types

A content handler can register a set of types that it can handle. Content types are simple opaque strings that are NOT case sensitive. Type strings are not case sensitive, types that differ only by case are treated as a single type.

Suffix Processing

A content handler can register a set of suffixes that identify from the syntax of a URL the content it can handle. Suffixes are NOT case sensitive.

Content Handler Actions

Each content handler may register a set of actions it supports. The set of actions is extensible but applications should choose from the actions defined in the ContentHandler class when they are appropriate. The predefined actions are: open, edit, new, send, save, execute, select, install, print, and stop.

Content Handler IDs

The content handler ID is a string chosen by the application vendor to identify the content handler. The ID registered by a content handler MUST be unique and MUST NOT match the prefix of any other registered content handler. IDs are case sensitive and are treated as opaque strings. They are compared for equality or as prefixes of IDs when used to locate an appropriate content handler.

Content handler IDs should follow the form of fully qualified Java class names or any naming syntax that provides a natural way to disambiguate between vendors. For example, IDs may be URLs including scheme, authority (server), and path information.

For example, if registered in the order below, the following content handler IDs would be valid or invalid as indicated because there is an ambiguity due to prefix comparisons.

  1. com.sun.applications.calc - valid
  2. com.sun.applications.trig - valid
  3. com.sun.application - invalid, this is the prefix of the calc ID
  4. com.sun.applications.calc.decimal - invalid, the calc ID is prefix of decimal

Java Application Class

The content handler to be launched is identified by the application class. The class MUST contain entry point(s) and be packaged according to the Java runtime environment. For MIDP, the application class MUST extend javax.microedition.midlet.MIDlet. The application class uniquely identifies a content handler within the application package, which is usually a JAR file. Each application class can only be registered to a single content handler. Registering a content handler for a class will replace any content handler previously registered to that class.

Content Handler Authentication

Applications and content handlers using the API may, for security purposes, need or want to authenticate the invoked content handler or the invoking application. The CHAPI implementation cooperates with the application management software to authenticate the applications (if possible) and pass the authentication information to the application. If the application can be authenticated, then the ContentHandler.getAuthority method will return the authority used in the authentication.

While processing an invocation request the content handler can use the Invocation.getInvokingAuthority method to verify the authenticity of the invoking application.

Content Handler Access Control

The visibility and accessibility of a content handler can be controlled by the content handler itself either through dynamic or static registration. To restrict access and visibility, the content handler MUST provide the IDs of the content handlers that MUST be allowed access. If any of the allowed IDs match the beginning of the ID of the content handler requesting access, then the application will be granted visibility and access to the content handler. The comparison is performed as if the java.lang.string.startsWith method was used. The access controls are only visible to the content handler itself using the method ContentHandlerServer.getAccessAllowed. By default, access is allowed to all applications and content handlers. Access restrictions are established when the content handler is registered with the register method.

Dynamic Registration

Dynamic registration is performed by initializing the classname, types, suffixes, actions, action names, ID, and access restrictions, and passing them to the register method. The unregister method removes a registered content handler.

The current registrations can be examined by using various methods to get the types, IDs, suffixes, actions, or to find a content handler by content handler classname, or to get all of the matching content handlers by ID, by content type, by suffix, or by action. Only content handlers that are accessible and visible to the application will be returned.

Invoking a Content Handler

To invoke a content handler, an application initializes an Invocation instance with the information needed to identify the content and/or the content handler. Typically this could include the URL, type, action, and content handler ID. The application may also supply arguments and data, and set whether a response is required. The application may request information about the content and the content handler that will process it before invocation. Calling the Registry.invoke method starts the request.

When invoked, the ID, type, URL, and action are used to identify a target content handler. If multiple content handlers are registered for the ID, type, suffixes or action, the implementation can decide which to use to satisfy the request. If the application needs to select which handler to use, the findHandler method will return the set of matching ContentHandlers. The application can choose from the content handlers returned and use Invocation.setID to select a specific handler.

In a runtime environment in which only a single application can run at a time, the invoking application must exit before the content handler can be started to handle the request. Invocation requests are queued so that the invoking application and the content handler can be run sequentially in resource-constrained environments. The return value of invoke is true to indicate that the application must exit. This allows the invoking application to save the users context and leave the user interface, if any, with some visual that the user will see until the content handler is ready.

Invocation processing involves the invoking application, the invoked content handler, and the application management software (AMS). The implementation of the API and the AMS MUST implement the queuing of invocations to the appropriate content handler and the necessary interactions with the lifecycle to start and restart applications and content handlers.

The invoke methods initiate the request. The URL, type, action, and ID, as described above, are used to dispatch the request to an appropriate content handler. If the content handler is not running, it MUST be started to process the request. If the content handler is already running, then the new request MUST be queued to the content handler. Only a single instance of each content handler application can be active at a time. The ContentHandlerServer class is used to dequeue and process requests.


Method Summary
 void cancelGetResponse()
          Cancels a pending getResponse.
 ContentHandler[] findHandler(Invocation invocation)
          Gets the registered content handlers that could be used for this Invocation.
 ContentHandler[] forAction(java.lang.String action)
          Gets the registered content handlers that support the action.
 ContentHandler forID(java.lang.String ID, boolean exact)
          Gets the registered content handler for the ID.
 ContentHandler[] forSuffix(java.lang.String suffix)
          Gets the content handlers for the suffix.
 ContentHandler[] forType(java.lang.String type)
          Gets the registered content handlers for the content type.
 java.lang.String[] getActions()
          Gets the unique actions of the registered content handlers.
 java.lang.String getID()
          Gets the content handler ID for the current application.
 java.lang.String[] getIDs()
          Gets the IDs of the registered content handlers.
static Registry getRegistry(java.lang.String classname)
          Gets the Registry for the application or content handler that will be calling registry methods.
 Invocation getResponse(boolean wait)
          Gets the next Invocation response pending for this application.
static ContentHandlerServer getServer(java.lang.String classname)
          Gets the content handler server registered for the content handler.
 java.lang.String[] getSuffixes()
          Gets the unique suffixes of the registered content handlers.
 java.lang.String[] getTypes()
          Gets all of the unique content types for which there are registered handlers.
 boolean invoke(Invocation invocation)
          Checks the Invocation and uses the ID, type, URL, and action, if present, to find a matching ContentHandler and queues this request to it.
 boolean invoke(Invocation invocation, Invocation previous)
          Checks the Invocation and uses the ID, type, URL, and action, if present, to find a matching ContentHandler and queues this request to it.
 ContentHandlerServer register(java.lang.String classname, java.lang.String[] types, java.lang.String[] suffixes, java.lang.String[] actions, ActionNameMap[] actionnames, java.lang.String ID, java.lang.String[] accessAllowed)
          Registers the application class using content type(s), suffix(es), and action(s), action name(s), access restrictions and content handler ID.
 boolean reinvoke(Invocation invocation)
          Reinvokes the Invocation and uses the ID, type, URL, and action to find a matching ContentHandler and re-queues this request to it.
 void setListener(ResponseListener listener)
          Sets the listener to be notified when a new response is available for the application context.
 boolean unregister(java.lang.String classname)
          Removes the content handler registration for the application class and any bindings made during registration to the content ID, type(s), suffix(es), and action(s), etc.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getRegistry

public static Registry getRegistry(java.lang.String classname)
Gets the Registry for the application or content handler that will be calling registry methods. The application is identified by the classname that implements the lifecycle of the Java runtime environment. The classname must be the name of a registered application class or a registered content handler.

For a MIDP implementation, application classes must be registered with the MIDlet-<n> attribute; content handlers are registered with the MicroEdition-Handler-<n> attribute or the register method.

Parameters:
classname - the application class
Returns:
a Registry instance providing access to content handler registrations and invocations; MUST NOT be null
Throws:
java.lang.IllegalArgumentException - is thrown if the classname is not a registered application or content handler
java.lang.NullPointerException - if classname is null

getServer

public static ContentHandlerServer getServer(java.lang.String classname)
                                      throws ContentHandlerException
Gets the content handler server registered for the content handler. The classname MUST be registered as a content handler in the current application package using either the register method or the static registration attributes.

Parameters:
classname - the name of an application class or content handler registered by this application package
Returns:
the content handler for the registered classname registered by this application package; MUST NOT be null
Throws:
java.lang.NullPointerException - if classname is null
ContentHandlerException - is thrown with a reason of NO_REGISTERED_HANDLER if there is no content handler registered for the classname in the current application package

register

public ContentHandlerServer register(java.lang.String classname,
                                     java.lang.String[] types,
                                     java.lang.String[] suffixes,
                                     java.lang.String[] actions,
                                     ActionNameMap[] actionnames,
                                     java.lang.String ID,
                                     java.lang.String[] accessAllowed)
                              throws java.lang.SecurityException,
                                     java.lang.IllegalArgumentException,
                                     java.lang.ClassNotFoundException,
                                     ContentHandlerException
Registers the application class using content type(s), suffix(es), and action(s), action name(s), access restrictions and content handler ID.

This method will replace any content handler registration in the application package that has the same classname. The update occurs atomically: the update to the registry either occurs or it does not.

The content handler may register the following items:

If no exceptions are thrown, then the type(s), suffix(s), action(s), action names, access restrictions, and ID will be registered for the application class.

If an exception is thrown, then the previous registration, if any, will not be removed or modified.

Parameters:
classname - the name of an application class or content handler in this application package; the value MUST NOT be null; and the handler MUST implement the lifecycle of the Java runtime environment
types - an array of types to register; if null it is treated the same as an empty array
suffixes - an array of suffixes to register; if null it is treated the same as an empty array
actions - an array of actions to register; if null it is treated the same as an empty array
actionnames - an array of ActionNameMaps to register; if null it is treated the same as an empty array
ID - the content handler ID; if null a default non-null value MUST be provided by the implementation
accessAllowed - the IDs of applications and content handlers that are allowed visibility and access to this content handler; if null or an empty array then all applications and content handlers are allowed access; otherwise ONLY applications and content handlers with matching IDs are allowed access.
Returns:
the registered ContentHandler; MUST NOT be null
Throws:
java.lang.NullPointerException - if any of the following items is null:
  • classname
  • any array element of types, suffixes, actions, actionnames, and accessAllowed
java.lang.IllegalArgumentException - is thrown:
  • if any of the types, suffix, actions, or accessAllowed strings have a length of zero, or
  • if the classname does not implement the valid lifecycle for the Java runtime environment,
  • if the ID has a length of zero or contains any control character or space (U+0000-U+00020),
  • if the sequence of actions in any ActionNameMap is not the same as the sequence of actions, or
  • if the locales of the ActionNameMaps are not unique.
java.lang.ClassNotFoundException - if the classname is not present
ContentHandlerException - with an error code of ContentHandlerException.AMBIGUOUS if ID (or if ID is null, the default ID) is a prefix of any registered handler or if any registered handler ID is a prefix of this ID, except where the registration is replacing or updating an existing registration with the same classname
java.lang.SecurityException - if registration is not permitted

unregister

public boolean unregister(java.lang.String classname)
Removes the content handler registration for the application class and any bindings made during registration to the content ID, type(s), suffix(es), and action(s), etc. Only content handlers registered either statically or dynamically in the current application package will be removed.

Parameters:
classname - the name of the content handler class
Returns:
true if the content handler registered by this application was found and removed; false otherwise
Throws:
java.lang.NullPointerException - if classname is null

getTypes

public java.lang.String[] getTypes()
Gets all of the unique content types for which there are registered handlers. Type strings are not case sensitive, types that differ only by case are treated as a single type. Each type is returned only once. After a successful registration, the content handler's type(s), if any, will appear in this list.

Only content handlers that this application is allowed to access will be included.

Returns:
an array of types; MUST NOT be null

getIDs

public java.lang.String[] getIDs()
Gets the IDs of the registered content handlers.

Only content handlers that this application is allowed to access will be included.

Returns:
an array of content handler IDs; MUST NOT be null

getActions

public java.lang.String[] getActions()
Gets the unique actions of the registered content handlers. No duplicate strings will be returned. After a successful registration the content handler's action(s), if any, will appear in this list.

Only content handlers that this application is allowed to access will be included.

Returns:
an array of content handler actions; MUST NOT be null

getSuffixes

public java.lang.String[] getSuffixes()
Gets the unique suffixes of the registered content handlers. Suffix strings are not case sensitive, suffixes that differ only by case are treated as a single suffix. Each suffix is returned only once. After a successful registration the content handler's suffix(es), if any, will appear in this list.

Only content handlers that this application is allowed to access will be included.

Returns:
an array of content handler suffixes; MUST NOT be null

forType

public ContentHandler[] forType(java.lang.String type)
Gets the registered content handlers for the content type.

Only content handlers that are visible and accessible to this application are returned.

Parameters:
type - the type of the requested content handlers
Returns:
an array of the ContentHandlers registered for the type; MUST NOT be null. An empty array is returned if there are no ContentHandlers accessible to this application with the type equal to the request type.
Throws:
java.lang.NullPointerException - if type is null

forAction

public ContentHandler[] forAction(java.lang.String action)
Gets the registered content handlers that support the action.

Only content handlers that are visible and accessible to this application are returned.

Parameters:
action - content handlers for which the action is supported
Returns:
an array of the ContentHandlers registered for the action; MUST NOT be null; an empty array is returned if no ContentHandlers are accessible to this application
Throws:
java.lang.NullPointerException - if action is null

forSuffix

public ContentHandler[] forSuffix(java.lang.String suffix)
Gets the content handlers for the suffix.

Only content handlers that are visible and accessible to this application are returned.

Parameters:
suffix - the suffix to be used to get the associated content handlers
Returns:
an array of the ContentHandlers registered for the suffix; MUST NOT be null. An empty array is returned if there are none accessible to this application
Throws:
java.lang.NullPointerException - if suffix is null

forID

public ContentHandler forID(java.lang.String ID,
                            boolean exact)
Gets the registered content handler for the ID. The query can be for an exact match or for the handler matching the prefix of the requested ID.

Only a content handler which is visible to and accessible to this application will be returned.

The forID method may be useful for applications with multiple components or subsystems to define a base ID for the application. A request to a particular component can be made by appending an additional string to the base ID. The additional string can be used by the handler itself to dispatch to the component or subsystem. The forID method can be used to query for the registered content handler.

Parameters:
ID - the content handler application ID of the content handler requested
exact - true to require an exact match; false to allow a registered content handler ID to match a prefix of the requested ID
Returns:
the content handler that matches the ID, otherwise null
Throws:
java.lang.NullPointerException - if ID is null

findHandler

public ContentHandler[] findHandler(Invocation invocation)
                             throws java.io.IOException,
                                    ContentHandlerException,
                                    java.lang.SecurityException
Gets the registered content handlers that could be used for this Invocation. Only handlers accessible to the application are considered. The values for ID, type, URL, and action are used in the following order:

The calling thread blocks while the ID and type are being determined. If a network access is needed there may be an associated delay.

Parameters:
invocation - the ID, type, action, and URL that are needed to identify one or more content handlers; must not be null
Returns:
an array of the ContentHandler(s) that could be used for this Invocation; MUST NOT be null;
Throws:
java.io.IOException - is thrown if access to the content fails
ContentHandlerException - is thrown with a reason of NO_REGISTERED_HANDLER if there is no registered content handler that matches the requested ID, type, URL, and action
java.lang.IllegalArgumentException - is thrown if ID, type, URL, and action are all null or if the content is accessed via the URL and the URL is invalid
java.lang.NullPointerException - is thrown if the invocation is null
java.lang.SecurityException - is thrown if access to the content is not permitted

invoke

public boolean invoke(Invocation invocation,
                      Invocation previous)
               throws java.lang.IllegalArgumentException,
                      java.io.IOException,
                      ContentHandlerException,
                      java.lang.SecurityException
Checks the Invocation and uses the ID, type, URL, and action, if present, to find a matching ContentHandler and queues this request to it.

If the previous Invocation is null, then a new transaction is created; otherwise, this Invocation will use the same transaction as the previous Invocation.

The status of this Invocation MUST be INIT. If there is a previous Invocation, that Invocation MUST have a status of ACTIVE and this Invocation MUST require a response.

Candidate content handlers are found as described in findHandler. If any handlers are found, one is selected for this Invocation. The choice of content handler is implementation dependent.

A copy of the Invocation is made, the status is set to ACTIVE and then queued to the target content handler. If the invoked content handler is not running, it MUST be started as described in Invoking a Content Handler.

The status of this Invocation is set to WAITING. If there is a non-null previous Invocation, its status is set to HOLD. The previous Invocation is saved in the waiting Invocation. It can be retrieved by the getPrevious method.

The calling thread blocks while the content handler is being determined. If a network access is needed, there may be an associated delay.

Parameters:
invocation - the Invocation containing the target ID, type, URL, actions, arguments, and responseRequired parameters; MUST NOT be null
previous - a previous Invocation for this Invocation; may be null
Returns:
true if the application MUST voluntarily exit to allow the target content handler to be started; false otherwise
Throws:
java.lang.IllegalArgumentException - is thrown if:
  • the ID, type, URL, and action are all null,
  • the argument array contains any null references, or
  • the content is accessed via the URL and the URL is invalid, or
  • the invocation.getResponseRequired method returns false and previous is non-null
java.io.IOException - is thrown if access to the content fails
ContentHandlerException - is thrown with a reason of NO_REGISTERED_HANDLER if there is no registered content handler that matches the requested ID, type, URL, and action
java.lang.IllegalStateException - is thrown if the status of this Invocation is not INIT or if the status of the previous Invocation, if any, is not ACTIVE
java.lang.NullPointerException - is thrown if the invocation is null
java.lang.SecurityException - if access to the content is not permitted

invoke

public boolean invoke(Invocation invocation)
               throws java.lang.IllegalArgumentException,
                      java.io.IOException,
                      ContentHandlerException,
                      java.lang.SecurityException
Checks the Invocation and uses the ID, type, URL, and action, if present, to find a matching ContentHandler and queues this request to it. The behavior is identical to invoke(invocation, null).

Parameters:
invocation - the Invocation containing the target ID, type, URL, action, arguments, and responseRequired parameters; MUST NOT be null
Returns:
true if the application MUST voluntarily exit to allow the target content handler to be started; false otherwise
Throws:
java.lang.IllegalArgumentException - is thrown if:
  • the ID, type, URL, and action are all null, or
  • the content is accessed via the URL and the URL is invalid, or
  • the argument array contains any null references
java.io.IOException - is thrown if access to the content fails
ContentHandlerException - is thrown with a reason of NO_REGISTERED_HANDLER if there is no registered content handler that matches the requested ID, type, URL, and action
java.lang.IllegalStateException - is thrown if the status of this Invocation is not INIT
java.lang.NullPointerException - is thrown if the invocation is null
java.lang.SecurityException - if access to the content is not permitted

reinvoke

public boolean reinvoke(Invocation invocation)
                 throws java.lang.IllegalArgumentException,
                        java.io.IOException,
                        ContentHandlerException,
                        java.lang.SecurityException
Reinvokes the Invocation and uses the ID, type, URL, and action to find a matching ContentHandler and re-queues this request to it. Reinvocation is used to delegate the handling of an active Invocation to another content handler. The processing of the Invocation instance is complete and the status is set to OK. Responses to the reinvocation will be queued to the original invoking application, if a response is required.

The status of this Invocation MUST be ACTIVE.

Candidate content handlers are found as described in findHandler. If any handlers are found, one is selected for this Invocation. The choice of content handler is implementation dependent.

The status of this Invocation is set to OK. A copy of the Invocation is made, the status is set to ACTIVE, and then queued to the target content handler. If the invoked content handler application is not running, it MUST be started as described in Invocation Processing.

The calling thread blocks while the content handler is being determined. If a network access is needed there may be an associated delay.

Parameters:
invocation - an Invocation containing the target ID, type, action, arguments, and responseRequired parameters; MUST NOT be null
Returns:
true if the application MUST voluntarily exit to allow the target content handler to be started; false otherwise
Throws:
java.lang.IllegalArgumentException - is thrown if:
  • the ID, type, and URL are all null, or
  • the content is accessed via the URL and the URL is invalid, or
  • the argument array contains any null references
java.io.IOException - is thrown if access to the content fails
ContentHandlerException - is thrown with a reason of: NO_REGISTERED_HANDLER if there is no registered content handler that matches the requested ID, type, URL, and action
java.lang.IllegalStateException - is thrown if the status of this Invocation is not ACTIVE
java.lang.NullPointerException - is thrown if the invocation is null
java.lang.SecurityException - if access to the content is not permitted

getResponse

public Invocation getResponse(boolean wait)
Gets the next Invocation response pending for this application. If requested, the method waits until an Invocation response is available. The method can be unblocked with a call to cancelGetResponse. The application can process the Invocation based on its status. The status is one of OK, CANCELLED, ERROR, or INITIATED.

If the Invocation was invoked with invoke(Invocation invocation, Invocation previous), the getPrevious method MUST return the previous Invocation. If the status of the previous Invocation is HOLD then its status is restored to ACTIVE.

If the original Invocation instance is reachable, then it MUST be updated with the values from the response and be returned to the application. If it is not reachable, then a new instance is returned from getResponse with the response values.

Parameters:
wait - true if the method MUST wait for an Invocation if one is not available; otherwise false if the method MUST NOT wait
Returns:
the next pending response Invocation or null if the wait is false and no Invocation is available or if cancelled with cancelGetResponse()
See Also:
invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation), cancelGetResponse()

cancelGetResponse

public void cancelGetResponse()
Cancels a pending getResponse. This method will force a thread blocked in a call to the getResponse method for this Registry instance to return early. If no thread is blocked; this call has no effect.


setListener

public void setListener(ResponseListener listener)
Sets the listener to be notified when a new response is available for the application context. The request must be retrieved using getResponse. If the listener is non-null and a response is available, the listener MUST be notified.
Note that if getResponse is being called concurrently with the listener then the listener may not be called because the response has already been returned to the application. The invocationResponseNotify is only used as a hint that a response may be available.

Parameters:
listener - the listener to register; null to remove the listener

getID

public java.lang.String getID()
Gets the content handler ID for the current application. The ID uniquely identifies the content handler. If the application is a content handler as returned from getServer then the ID MUST be the content handler ID returned from ContentHandlerServer.getID. Otherwise, the ID will be generated for the profile. The package documentation for "Content Handlers and the Mobile Information Device Profile" defines the value for MIDP.

Returns:
the ID; MUST NOT be null

Java™ 2 Platform, Micro Edition Content Handler API (Final Release, June 3, 2005)

Copyright © 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

For more information, please consult the JSR 211 specification.