javax.microedition.content
Interface ContentHandlerServer

All Superinterfaces:
ContentHandler

public interface ContentHandlerServer
extends ContentHandler

ContentHandlerServer provides methods to get new Invocation requests, to finish the processing of requests and to get the access control information. This server interface extends ContentHandler to make available the registration information for types, suffixes, actions, ID, etc. Instances are thread safe.

Responding to an Invocation

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.

Required Response 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.

Chaining Content Handlers

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.

Handling Faults

If the content handler cannot or does not correctly handle the Invocation, then the AMS MUST handle it correctly. These actions prevent an incorrectly written content handler from being unresponsive or being run repeatedly but never processing queued invocations.

Invocations and invocation state MUST NOT be preserved across soft and hard restarts of the device software including unexpected power interruptions.

Since:
JDE 4.3.0

Field Summary
 
Fields inherited from interface javax.microedition.content.ContentHandler
ACTION_EDIT, ACTION_EXECUTE, ACTION_INSTALL, ACTION_NEW, ACTION_OPEN, ACTION_PRINT, ACTION_SAVE, ACTION_SELECT, ACTION_SEND, ACTION_STOP, UNIVERSAL_TYPE
 
Method Summary
 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.
 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(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.
 
Methods inherited from interface javax.microedition.content.ContentHandler
getAction, getActionCount, getActionNameMap, getActionNameMap, getActionNameMap, getActionNameMapCount, getAppName, getAuthority, getID, getSuffix, getSuffixCount, getType, getTypeCount, getVersion, hasAction, hasSuffix, hasType
 

Method Detail

accessAllowedCount

public int accessAllowedCount()
Gets the number of IDs allowed access by the content handler. The number of IDs MUST be equal to the length of the array of accessAllowed passed to Registry.register. If the number of IDs is zero then all applications and content handlers are allowed access.
Returns:
the number of IDs allowed access
Since:
JDE 4.3.0

cancelGetRequest

public void cancelGetRequest()
Cancels a pending 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.
Since:
JDE 4.3.0

finish

public boolean finish(Invocation invocation,
                      int status)
Finishes the Invocation and sets the status for the response. The 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.

Parameters:
invocation - the Invocation to finish
status - the new status of the Invocation; MUST be either OK, CANCELLED or INITIATED
Returns:
true if the application MUST voluntarily exit to allow pending responses or requests to be handled; false otherwise
Throws:
IllegalArgumentException - if the new status of the Invocation is not OK, CANCELLED, or INITIATED
IllegalStateException - if the current status of the Invocation is not ACTIVE or HOLD
NullPointerException - if the invocation is null
Since:
JDE 4.3.0

getAccessAllowed

public String getAccessAllowed(int index)
Gets the ID at the specified index of an application or content handler allowed access to this content handler. The ID returned for each index must be the equal to the ID at the same index in the accessAllowed array passed to Registry.register.
Parameters:
index - the index of the ID
Returns:
the ID at the specified index
Throws:
IndexOutOfBoundsException - if index is less than zero or greater than or equal to the value of the accessAllowedCount method.
Since:
JDE 4.3.0

getRequest

public Invocation getRequest(boolean wait)
Gets the next Invocation request pending for this ContentHandlerServer. The method can be unblocked with a call to cancelGetRequest. The application should process the Invocation as a request to perform the action on the content.
Parameters:
wait - true if the method must wait for an Invocation if one is not available; false if the method MUST NOT wait.
Returns:
the next pending Invocation or null if no Invocation is available; null if cancelled with cancelGetRequest
Since:
JDE 4.3.0
See Also:
Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation), finish(javax.microedition.content.Invocation, int)

isAccessAllowed

public boolean isAccessAllowed(String ID)
Determines if an ID MUST be allowed access by the content handler. Access MUST be allowed if the ID has a prefix that exactly matches any of the IDs returned by getAccessAllowed(int). The prefix comparison is equivalent to java.lang.String.startsWith.
Parameters:
ID - the ID for which to check access
Returns:
true if access MUST be allowed by the content handler; false otherwise
Throws:
NullPointerException - if ID is null
Since:
JDE 4.3.0

setListener

public void setListener(RequestListener listener)
Sets the listener to be notified when a new request is available for this content handler. The request is retrieved using getRequest. If the listener is non-null and a request is available, the listener MUST be notified.
Parameters:
listener - the listener to register; null to remove the listener.
Since:
JDE 4.3.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.