javax.microedition.content
Class Registry

java.lang.Object
  javax.microedition.content.Registry

public class Registry
extends 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.

Selecting a Content Handler from Matching Handlers

The content handler API allows multiple handlers to register for the same content type. Although the specification allows applications to explicitly call a given handler, it also allows calls that match with multiple handlers. As a result of this, a call to Registry.invoke() may find multiple matching handlers and the implementation needs to choose the one to invoke. The usability of CHAPI implementations is improved when the user can choose which ContentHandler is selected from those that match.

• As a general rule, the device MUST provide a mechanism for the user to control which of the multiple matching handers is invoked and not arbitrarily select one for the user. This mechanism can be either a user prompt during the call to Registry.invoke() or a handler configuration that the user can make in advance to select which handler gets precedence when multiple handlers match. A possible implementation can also be a combination of the two or the handler may be selected based on the order of handler registrations, giving a later registered handler a priority over earlier ones.
• As an exception to the rule above, an implementation MAY give precedence to some prebuilt content handlers over later downloaded ones. This may be important for security and usability reasons. There may be content types that by default should be handled by the prebuilt handler and not by a 3rd party handler. It should be noted that all registered handlers can still be called. They just will not get selected when multiple handlers match the invocation.
• If prompting is used:
  • The prompt MUST include the names of the matching handlers. If the invocation includes a specific action, the localized name of the action SHOULD also be displayed in the prompt.
  • The most common use cases of the device SHOULD NOT be complicated with excessive prompting. For example, the MIDlet installer (JAD handler) SHOULD always be invoked without extra prompting when the user selects a link to a JAD file from the device browser.

RIM Implementation Details

RIM registers the following applications with the Content Handler API. Their IDs can be found in the BlackBerryContentHandler class.

Content Handler	ID
Media Content Handler This application opens any file type supported natively by the handheld (i.e. audio and video files, HTML documents, etc.).	ID_MEDIA_CONTENT_HANDLER
Send As Email Content Handler This content handler can be invoked to make use of the 'Send As Email' functionality for local content such as audio, video, images, etc. as is found in the menu of the BlackBerry file explorer application.	net.rim.device.api.content.BlackBerryContentHandler.ID_SEND_AS_EMAIL_CONTENT_HANDLER
Send As MMS Content Handler This content handler can be invoked to make use of the 'Send As MMS' functionality for local content such as audio, video, images, etc. as is found in the menu of the BlackBerry file explorer application.	net.rim.device.api.content.BlackBerryContentHandler.ID_SEND_AS_MMS_CONTENT_HANDLER
Send using Bluetooth Content Handler This content handler is only available on devices that support Bluetooth. This content handler can be invoked to make use of the 'Send Using Bluetooth' functionality for local content such as audio, video, images, etc. as is found in the menu of the BlackBerry file explorer application.	net.rim.device.api.content.BlackBerryContentHandler.ID_SEND_AS_MMS_CONTENT_HANDLER

Since:

BlackBerry API 4.3.0

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(String action) Gets the registered content handlers that support the action.
ContentHandler	forID(String ID, boolean exact) Gets the registered content handler for the ID.
ContentHandler[]	forSuffix(String suffix) Gets the content handlers for the suffix.
ContentHandler[]	forType(String type) Gets the registered content handlers for the content type.
String[]	getActions() Gets the unique actions of the registered content handlers.
String	getID() Gets the content handler ID for the current application.
String[]	getIDs() Gets the IDs of the registered content handlers.
static Registry	getRegistry(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(String classname) Gets the content handler server registered for the content handler.
String[]	getSuffixes() Gets the unique suffixes of the registered content handlers.
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(String classname, String[] types, String[] suffixes, String[] actions, ActionNameMap[] actionnames, String ID, 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(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(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:

IllegalArgumentException - is thrown if the classname is not a registered application or content handler

NullPointerException - if classname is null

Since:

BlackBerry API 4.3.0

getServer

public static ContentHandlerServer getServer(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:

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

Since:

BlackBerry API 4.3.0

register

public ContentHandlerServer register(String classname,
                                     String[] types,
                                     String[] suffixes,
                                     String[] actions,
                                     ActionNameMap[] actionnames,
                                     String ID,
                                     String[] accessAllowed)
                              throws SecurityException,
                                     IllegalArgumentException,
                                     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:

• zero or more content types
• zero or more suffixes
• zero or more actions
• zero or more mappings from actions to action names
• zero or more IDs of applications allowed access
• an optional application ID

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:

NullPointerException - if any of the following items is null:

• classname
• any array element of types, suffixes, actions, actionnames, and accessAllowed

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.

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

SecurityException - if registration is not permitted

Since:

BlackBerry API 4.3.0

unregister

public boolean unregister(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:

NullPointerException - if classname is null

Since:

BlackBerry API 4.3.0

getTypes

public 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

Since:

BlackBerry API 4.3.0

getIDs

public 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

Since:

BlackBerry API 4.3.0

getActions

public 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

Since:

BlackBerry API 4.3.0

getSuffixes

public 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

Since:

BlackBerry API 4.3.0

forType

public ContentHandler[] forType(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:

NullPointerException - if type is null

Since:

BlackBerry API 4.3.0

forAction

public ContentHandler[] forAction(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:

NullPointerException - if action is null

Since:

BlackBerry API 4.3.0

forSuffix

public ContentHandler[] forSuffix(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:

NullPointerException - if suffix is null

Since:

BlackBerry API 4.3.0

forID

public ContentHandler forID(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:

NullPointerException - if ID is null

Since:

BlackBerry API 4.3.0

findHandler

public ContentHandler[] findHandler(Invocation invocation)
                             throws IOException,
                                    ContentHandlerException,
                                    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:

• If the ID is non-null, then a candidate handler is determined by the forID method with the parameter exact set to false. The type and URL are ignored. If there is no handler that matches the requested ID then a ContentHandlerException is thrown.
• If the ID and type are null and the URL is non-null and if the protocol supports typing of content, then the type is determined as described in Invocation.findType(). If the type cannot be determined from the content, the type is set to null.
• If the ID is null and type is non-null, then the set of candidate handlers is determined from the forType method. If there are no handlers that match the requested type then a ContentHandlerException is thrown.
• If both the ID and type are null and the URL is non-null and if the protocol does not support typing of content or the type was not available from the content, then the set of candidate handlers includes any handler with a suffix that matches the end of the path component of the URL. If there are no handlers that match a registered suffix then a ContentHandlerException is thrown.
• If the ID, type, and URL are all null, the set of candidate handlers includes all of the accessible handlers.
• If the action is non-null, the set of candidate handlers is reduced to contain only handlers that support the action.
• If the set of candidate handlers is empty then a ContentHandlerException is thrown.

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:

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

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

NullPointerException - is thrown if the invocation is null

SecurityException - is thrown if access to the content is not permitted

Since:

BlackBerry API 4.3.0

invoke

public boolean invoke(Invocation invocation,
                      Invocation previous)
               throws IllegalArgumentException,
                      IOException,
                      ContentHandlerException,
                      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:

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

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

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

NullPointerException - is thrown if the invocation is null

SecurityException - if access to the content is not permitted

Since:

BlackBerry API 4.3.0

invoke

public boolean invoke(Invocation invocation)
               throws IllegalArgumentException,
                      IOException,
                      ContentHandlerException,
                      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:

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

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

IllegalStateException - is thrown if the status of this Invocation is not INIT

NullPointerException - is thrown if the invocation is null

SecurityException - if access to the content is not permitted

Since:

BlackBerry API 4.3.0

reinvoke

public boolean reinvoke(Invocation invocation)
                 throws IllegalArgumentException,
                        IOException,
                        ContentHandlerException,
                        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:

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

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

IllegalStateException - is thrown if the status of this Invocation is not ACTIVE

NullPointerException - is thrown if the invocation is null

SecurityException - if access to the content is not permitted

Since:

BlackBerry API 4.3.0

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 Registry.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 Registry.cancelGetResponse()

See Also:

Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation), Registry.cancelGetResponse()

Since:

BlackBerry API 4.3.0

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.

Since:

BlackBerry API 4.3.0

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

Since:

BlackBerry API 4.3.0

getID

public 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

Since:

BlackBerry API 4.3.0