public interface ContentHandlerServer extends ContentHandler
ContentHandlerto 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
new requests with the
A content handler receives an Invocation by calling
The content handler should use the
method to determine the requested action and act on the content
The content handler will typically call the
Invocation.open method to read the content.
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
When an Invocation is completed either by using the
method or when the AMS is handling an error condition,
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
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 chained use cases, the methods
are used to establish
the sequence and to retrieve the previous Invocation.
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
so the content handler can complete its processing.
An Invocation can be delegated to another handler with the
Responses to the reinvocation will be queued to the original invoking
ACTIVEis dequeued by the content handler, but the handler does not call
finishor 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.
ACTIVEare completed with the
Invocations and invocation state MUST NOT be preserved across soft and hard restarts of the device software including unexpected power interruptions.
|Modifier and Type||Method and Description|
Gets the number of IDs allowed access by the content handler.
Cancels a pending
Finishes the Invocation and sets the status for the response.
Gets the ID at the specified index of an application or content handler allowed access to this content handler.
Gets the next Invocation request pending for this ContentHandlerServer.
Determines if an ID MUST be allowed access by the content handler.
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
actionon the content.
trueif the method must wait for an Invocation if one is not available;
falseif the method MUST NOT wait.
nullif no Invocation is available;
nullif canceled with
getRequest. This method will force all threads blocked in a call to the
getRequestmethod for this ContentHandlerServer to return. If no threads are blocked; this call has no effect.
boolean finish(Invocation invocation, int status)
finishmethod can only be called when the Invocation has a status of
The content handler may modify the URL, type, action, or
arguments before invoking
If the method
true, then the modified
values MUST be returned to the invoking application.
invocation- the Invocation to finish
status- the new status of the Invocation; MUST be either
trueif the application MUST voluntarily exit to allow pending responses or requests to be handled;
java.lang.IllegalArgumentException- if the new
statusof the Invocation is not
java.lang.IllegalStateException- if the current
statusof the Invocation is not
java.lang.NullPointerException- if the invocation is
void setListener(RequestListener listener)
getRequest. If the listener is
non-nulland a request is available, the listener MUST be notified.
listener- the listener to register;
nullto remove the listener.
java.lang.String getAccessAllowed(int index)
index- the index of the ID
java.lang.IndexOutOfBoundsException- if index is less than zero or greater than or equal to the value of the
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
ID- the ID for which to check access
trueif access MUST be allowed by the content handler;
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.