public interface ContentHandlerServer extends ContentHandler
ContentHandler
to make available the registration information for types,
suffixes, actions, ID, etc.
Instances are thread safe.
Content handler applications process requests using
either blocking calls to getRequest
or can be
notified of
new requests with the setListener
method.
A content handler receives an Invocation by calling
getRequest
.
The content handler should use the
Invocation.getAction
method to determine the requested action and act on the content
appropriately.
The content handler will typically call the
Invocation.open
method to read the content.
The open
method returns a Connection from the Generic
Connection framework that provides access to the content.
When the content handler is finished processing the Invocation,
it must call the
finish
method to report the status.
If a response was required the status and parameters are returned
to the invoking application.
The invoking application decides whether it needs a response and
sets the request state before calling
Registry.invoke
.
When an Invocation is completed either by using the
finish
method or when the AMS is handling an error condition,
the Invocation.getResponseRequired
method is checked.
If it is true
, then the values from the Invocation are
queued to the invoking application with the status set
by the ContentHandler or AMS.
When a response is queued, it will be dispatched to the invoking
application.
If a response is not required, it is not delivered to the invoking
application and the invoking application is not started.
Content handlers link Invocations that are part of a user-driven task and depend on each other as part of a transaction. Suppose an application A creates an invocation a. When invoked, it is dispatched to content handler B which in-turn creates an invocation b and it is dispatched to content handler C. C displays the content and returns a response b' to B, B in turn completes processing and returns a response a' to A.
The implementation MUST have the capacity and mechanisms to support the chaining of requests required for an application to invoke a content handler, and the content handler invoking another content handler, and for each content handler to return a response. This chain length of two active invocations is the minimum requirement. The implementation should not artificially limit the number of invocations and responses that are supported except as constrained by the resources of the device.
To maintain continuity across the applications, chained invocations are part of the same transaction. Invoking an Invocation places it in a transaction. The transaction maintains the sequence of invocations across all of the applications involved. The transaction maintains the invocations regardless of whether a single application can run at a time or the applications execute in parallel in different runtime environments. The transaction is used to record and manage the steps in processing and dispatching to applications.
For simple non-chaining use cases that involve only two
applications with a single invocation and response,
only the methods
getRequest
, finish
,
Registry.invoke
, and
Registry.getResponse
are needed.
For chained use cases, the methods Registry.invoke
and Invocation.getPrevious
are used to establish
the sequence and to retrieve the previous Invocation.
The Registry.invoke
method places the new
Invocation in the same transaction as a previous Invocation.
The previous Invocation will be held in the transaction until
the new Invocation is completed. When the response to the new
Invocation is returned, the previously active Invocation can be
retrieved with Invocation.getPrevious
so the content handler can complete its processing.
An Invocation can be delegated to another handler with the
Registry.reinvoke
method.
Responses to the reinvocation will be queued to the original invoking
application.
ACTIVE
is dequeued by
the content handler, but the handler does not call
finish
or make a request to chain a new Invocation to the ACTIVE
invocation before the content handler exits, then the AMS MUST
complete the request with an ERROR status.
This ensures that the invoking application
will always get a response, if required, for each invocation
regardless of whether the content handler correctly handles it.
ACTIVE
are completed with the ERROR
status.getRequest
or
Registry.getResponse
.
Invocations and invocation state MUST NOT be preserved across soft and hard restarts of the device software including unexpected power interruptions.
ACTION_DELETE, ACTION_EDIT, ACTION_EXECUTE, ACTION_INSTALL, ACTION_INSTALL_ONLY, ACTION_NEW, ACTION_OPEN, ACTION_PRINT, ACTION_REMOVE, ACTION_SAVE, ACTION_SELECT, ACTION_SEND, ACTION_STOP, UNIVERSAL_TYPE
Modifier and Type | Method and Description |
---|---|
int |
accessAllowedCount()
Gets the number of IDs allowed access by the content handler.
|
void |
cancelGetRequest()
Cancels a pending
getRequest . |
boolean |
finish(Invocation invocation,
int status)
Finishes the Invocation and sets the status for the response.
|
java.lang.String |
getAccessAllowed(int index)
Gets the ID at the specified index of an application or content
handler allowed access to this content handler.
|
Invocation |
getRequest(boolean wait)
Gets the next Invocation request pending for this
ContentHandlerServer.
|
boolean |
isAccessAllowed(java.lang.String ID)
Determines if an ID MUST be allowed access by the content handler.
|
void |
setListener(RequestListener listener)
Sets the listener to be notified when a new request is
available for this content handler.
|
getAction, getActionCount, getActionNameMap, getActionNameMap, getActionNameMap, getActionNameMapCount, getAppName, getAuthority, getID, getSuffix, getSuffixCount, getType, getTypeCount, getVersion, hasAction, hasSuffix, hasType
Invocation getRequest(boolean wait)
cancelGetRequest
.
The application should process the Invocation as
a request to perform the action
on the content.wait
- true
if the method must wait
for an Invocation if one is not available;
false
if the method MUST NOT wait.null
if no Invocation is available; null
if canceled with cancelGetRequest
Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation)
,
finish(javax.microedition.content.Invocation, int)
void cancelGetRequest()
getRequest
.
This method will force all threads blocked in a call to the
getRequest
method for this ContentHandlerServer
to return.
If no threads are blocked; this call has no effect.boolean finish(Invocation invocation, int status)
finish
method can only be called when the
Invocation
has a status of ACTIVE
or HOLD
.
The content handler may modify the URL, type, action, or
arguments before invoking finish
.
If the method
Invocation.getResponseRequired
returns true
, then the modified
values MUST be returned to the invoking application.
invocation
- the Invocation to finishstatus
- the new status of the Invocation;
MUST be either OK
, CANCELLED
or INITIATED
true
if the application MUST
voluntarily exit to allow pending responses or requests
to be handled;
false
otherwisejava.lang.IllegalArgumentException
- if the new
status
of the Invocation
is not OK
, CANCELLED
,
or INITIATED
java.lang.IllegalStateException
- if the current
status
of the
Invocation is not ACTIVE
or HOLD
java.lang.NullPointerException
- if the invocation is null
void setListener(RequestListener listener)
getRequest
.
If the listener is non-null
and a request is
available, the listener MUST be notified.listener
- the listener to register;
null
to remove the listener.java.lang.String getAccessAllowed(int index)
Registry.register
.index
- the index of the IDjava.lang.IndexOutOfBoundsException
- if index is less than zero or
greater than or equal to the value of the
accessAllowedCount
method.int accessAllowedCount()
accessAllowed
passed to
Registry.register
.
If the number of IDs is zero then all applications and
content handlers are allowed access.boolean isAccessAllowed(java.lang.String ID)
getAccessAllowed(int)
.
The prefix comparison is equivalent to
java.lang.String.startsWith
.ID
- the ID for which to check accesstrue
if access MUST be allowed by the
content handler;
false
otherwisejava.lang.NullPointerException
- if ID
is null
Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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.