javax.microedition.content
Class Invocation

java.lang.Object
  javax.microedition.content.Invocation

public final class Invocation
extends Object

An Invocation contains the parameters that are passed from an invoking application to a content handler and the results that are returned to the application. The parameters are the type, URL, action, content handler ID, and responseRequired. The string and data arguments can be set using setArgs and setData methods. All of the parameters are provided to the content handler and are returned with the handlers response, if any. Invocation instances are not thread safe, the application must handle any synchronization necessary.

The values of content handler ID, type, URL, and action are used to identify the content handler when invoked by Registry.invoke. If an Invocation contains an ID then it is used to identify the content handler to be invoked. The other parameters are input to the content handler.

If a type is present, it is used to find handlers that support that type. The application should supply the type if it is known. If the type is not set, then calling the findType will find the type using the URL to the content.

Invocation Status

The status value indicates the next processing step of the invocation by the content handler. The status of an Invocation can be any of the following:

• Invocation.INIT—indicates the Invocation is still being initialized
• Invocation.WAITING—indicates that this Invocation is waiting to complete
• Invocation.ACTIVE—indicates the Invocation is currently being processed
• Invocation.HOLD—indicates the Invocation is currently waiting for a chained Invocation to complete
• Invocation.ERROR, Invocation.OK, Invocation.CANCELLED— indicate that the Invocation is complete
• Invocation.INITIATED— indicate that the Invocation has been initiated but the content handler cannot provide a response when it is finished.

All status transitions occur only during method calls that involve the Invocation instance. The transitions that occur are specified in the methods that make the change visible. For example, when an invoking application creates a new Invocation, the status is INIT. When the application calls Registry.invoke the status changes to WAITING. When the Registry.getResponse method is invoked, the status will be updated to the appropriate OK, CANCELLED, INITIATED, or ERROR status from the content handler.

A content handler calls ContentHandlerServer.getRequest to get the next request. The request always has the ACTIVE status. When the handler is finished acting on the content, the status is set to either OK, CANCELLED, or INITIATED by the ContentHandlerServer.finish method.

If the handler is chaining, then the new Invocation follows the status transitions of invoke as described above. The status of the previous invocation being chained from is set to HOLD by the Registry.invoke method. The status of the previous Invocation is restored to ACTIVE by the Registry.getResponse method that returns the status for the new Invocation.

If the content handler application causes faults because it does not properly dequeue and respond to invocations as described in the ContentHandler class, then the status is set to ERROR in the response queued back to the invoking application.

Access to Content

The implementation of the invocation mechanism may save or cache information about the request, the URL, the content type, or content during the invocation. The information may be utilized when the application accesses the content with the open method. The Invocation.getURL() method MUST return the original URL unmodified by any implementation specific information.

Since:

BlackBerry API 4.3.0

Field Summary
static int	ACTIVE This Invocation is a new request and is being handled by the content handler.
static int	CANCELLED The processing of the Invocation was cancelled by the ContentHandler.
static int	ERROR The content handler failed to correctly process the Invocation request.
static int	HOLD This Invocation is on hold until a chained Invocation is completed.
static int	INIT This Invocation was just constructed and is being initialized.
static int	INITIATED The processing of the Invocation has been initiated and will continue.
static int	OK The content handler successfully completed processing the Invocation.
static int	WAITING This Invocation has been invoked and is waiting to be complete.

Constructor Summary

Invocation()
Creates a new Invocation.

Invocation(String url)
Convenient alternative constructor with a URL.

Invocation(String url, String type)
Convenient alternative constructor with URL and type.

Invocation(String url, String type, String ID)
Convenient alternative constructor with URL, type, and ID.

Invocation(String url, String type, String ID, boolean responseRequired, String action)
Creates a new instance and initializes it from the specified parameters.

Method Summary
String	findType() Finds the type of the content in this Invocation.
String	getAction() Gets the action to be performed on the content.
String[]	getArgs() Gets the argument list as an array of Strings.
byte[]	getData() Gets the data for the Invocation.
String	getID() Gets the content handler ID for this Invocation.
String	getInvokingAppName() Get the user-friendly name of the application that invoked the content handler.
String	getInvokingAuthority() Gets the authority, if any, used to authenticate the application that invoked this request.
String	getInvokingID() Gets the ID of the application that invoked the content handler.
Invocation	getPrevious() Gets the previous Invocation saved in this Invocation by Registry.invoke or Registry.getResponse.
boolean	getResponseRequired() Gets the responseRequired mode for this Invocation.
int	getStatus() Gets the status of this Invocation, which can be INIT, WAITING, HOLD, ACTIVE, OK, CANCELLED, INITIATED, or ERROR.
String	getType() Gets the content type for the Invocation.
String	getURL() Gets the URL for the invocation.
Connection	open(boolean timeouts) Creates and opens a Connection to the content addressed by the URL in getURL.
void	setAction(String action) Sets the action to be performed on the content.
void	setArgs(String[] args) Sets the argument list to a new array of Strings.
void	setCredentials(String username, char[] password) Provide the credentials needed to access the content.
void	setData(byte[] data) Sets the data used for the Invocation.
void	setID(String ID) Sets the ID of the content handler for this Invocation.
void	setResponseRequired(boolean responseRequired) Sets the responseRequired mode for this Invocation.
void	setType(String type) Sets the type for the Invocation.
void	setURL(String url) Sets the URL for the invocation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INIT

public static final int INIT

This Invocation was just constructed and is being initialized.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTIVE

public static final int ACTIVE

This Invocation is a new request and is being handled by the content handler.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

WAITING

public static final int WAITING

This Invocation has been invoked and is waiting to be complete.

See Also:

Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation), Constant Field Values

Since:

BlackBerry API 4.3.0

HOLD

public static final int HOLD

This Invocation is on hold until a chained Invocation is completed.

See Also:

Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation), Constant Field Values

Since:

BlackBerry API 4.3.0

OK

public static final int OK

The content handler successfully completed processing the Invocation. Invocations queued with ContentHandlerServer.finish will have this status.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

CANCELLED

public static final int CANCELLED

The processing of the Invocation was cancelled by the ContentHandler. Invocations queued with ContentHandlerServer.finish will have this status.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ERROR

public static final int ERROR

The content handler failed to correctly process the Invocation request.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

INITIATED

public static final int INITIATED

The processing of the Invocation has been initiated and will continue. This status is only appropriate when the content handler can not provide a response when it is finished.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

Constructor Detail

Invocation

public Invocation()

Creates a new Invocation. The status of the new Invocation object is INIT. The URL, type, ID, action, arguments, and data are set to empty arrays, and initialized to require a response.

Since:

BlackBerry API 4.3.0

Invocation

public Invocation(String url,
                  String type,
                  String ID)

Convenient alternative constructor with URL, type, and ID. The behavior is identical to new Invocation(url, type, ID, true, null).

Parameters:

url - the URL of the content to be dispatched; may be null

type - the content type; may be null

ID - the ID of the content handler; may be null

Since:

BlackBerry API 4.3.0

Invocation

public Invocation(String url,
                  String type)

Convenient alternative constructor with URL and type. The behavior is identical to new Invocation(url, type, null, true, null).

Parameters:

url - the URL of the content to be dispatched; may be null

type - the content type; may be null

Since:

BlackBerry API 4.3.0

Invocation

public Invocation(String url)

Convenient alternative constructor with a URL. The behavior is identical to new Invocation(url, null, null, true, null).

Parameters:

url - the URL of the content to be dispatched; may be null

Since:

BlackBerry API 4.3.0

Invocation

public Invocation(String url,
                  String type,
                  String ID,
                  boolean responseRequired,
                  String action)

Creates a new instance and initializes it from the specified parameters. The status of the new Invocation is INIT. None of the values are checked until the Registry.invoke method is called. String arguments or data can be set with setArgs or setData.

Parameters:

url - the URL of the content to be dispatched; may be null

type - the content type; may be null

ID - the ID of the content handler; may be null

responseRequired - true if a response is required; false otherwise

action - the action that the content handler should perform on the content; may be null

Since:

BlackBerry API 4.3.0

Method Detail

setArgs

public void setArgs(String[] args)

Sets the argument list to a new array of Strings. The arguments are used by the application to communicate to the content handler and return results from the content handler. The values of the arguments are not checked when they are set. Instead, they are checked during Registry.invoke to check that none of the values are null.

Parameters:

args - the String array; may be null. A null argument is treated the same as a zero-length array

See Also:

Invocation.getArgs()

Since:

BlackBerry API 4.3.0

getArgs

public String[] getArgs()

Gets the argument list as an array of Strings. These values are passed to the content handler and are returned from the content handler. The array is not copied; modifications to array elements will be visible.

Returns:

the arguments array, which MUST NOT be null

See Also:

Invocation.setArgs(java.lang.String[])

Since:

BlackBerry API 4.3.0

setData

public void setData(byte[] data)

Sets the data used for the Invocation. The data is used by the application to communicate to the content handler and return data from the content handler. The array is not copied until the Invocation is invoked or finished; modifications to array elements will otherwise be visible.

Parameters:

data - the byte data array; may be null. A null is treated the same as a zero-length array

See Also:

Invocation.getData()

Since:

BlackBerry API 4.3.0

getData

public byte[] getData()

Gets the data for the Invocation. The data is passed to the content handler. The content handler may modify and return the data if it returns a response.

Returns:

the data array, which MUST NOT be null

See Also:

Invocation.setData(byte[])

Since:

BlackBerry API 4.3.0

getURL

public String getURL()

Gets the URL for the invocation. The URL must be equal to the value set with setURL.

Returns:

the URL or null if it has not been set

See Also:

Invocation.setURL(java.lang.String)

Since:

BlackBerry API 4.3.0

setURL

public void setURL(String url)

Sets the URL for the invocation.

Parameters:

url - the URL to be set; may be null

See Also:

Invocation.getURL()

Since:

BlackBerry API 4.3.0

getType

public String getType()

Gets the content type for the Invocation. The type for this Invocation may be set by the application using setType. The findType method can be used by an application to find the type by accessing the content via the URL. When found, findType sets the type returned by getType.

Returns:

the content type or null if it has not been set

See Also:

Invocation.setType(java.lang.String), Invocation.findType()

Since:

BlackBerry API 4.3.0

setType

public void setType(String type)

Sets the type for the Invocation.

Parameters:

type - the type to be set for the content; may be null

See Also:

Invocation.getType(), Invocation.findType()

Since:

BlackBerry API 4.3.0

getAction

public String getAction()

Gets the action to be performed on the content.

Returns:

the content action or null if it has not been set

See Also:

Invocation.setAction(java.lang.String)

Since:

BlackBerry API 4.3.0

setAction

public void setAction(String action)

Sets the action to be performed on the content.

Parameters:

action - the action to be performed on the content; may be null

See Also:

Invocation.getAction()

Since:

BlackBerry API 4.3.0

getResponseRequired

public boolean getResponseRequired()

Gets the responseRequired mode for this Invocation. If true, then the invoking application requires a response to the Invocation.

Returns:

the current value of the responseRequired mode. If true, then a response must be returned to the invoking application.

See Also:

Invocation.setResponseRequired(boolean)

Since:

BlackBerry API 4.3.0

setResponseRequired

public void setResponseRequired(boolean responseRequired)

Sets the responseRequired mode for this Invocation. If true, then the invoking application requires a response to the Invocation. The value in the request can be changed only if the status is INIT.

Parameters:

responseRequired - true to require a response, false otherwise

Throws:

IllegalStateException - is thrown if the status is not INIT

See Also:

Invocation.getResponseRequired()

Since:

BlackBerry API 4.3.0

getStatus

public int getStatus()

Gets the status of this Invocation, which can be INIT, WAITING, HOLD, ACTIVE, OK, CANCELLED, INITIATED, or ERROR.

Returns:

the status of this Invocation

See Also:

Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation), Registry.getResponse(boolean), ContentHandlerServer.getRequest(boolean), ContentHandlerServer.finish(javax.microedition.content.Invocation, int)

Since:

BlackBerry API 4.3.0

getID

public String getID()

Gets the content handler ID for this Invocation.

Returns:

the ID of the ContentHandler; may be null

See Also:

Registry.forID(java.lang.String, boolean), Invocation.setID(java.lang.String)

Since:

BlackBerry API 4.3.0

setID

public void setID(String ID)

Sets the ID of the content handler for this Invocation.

Parameters:

ID - of the content handler; may be null

See Also:

Invocation.getID()

Since:

BlackBerry API 4.3.0

getPrevious

public Invocation getPrevious()

Gets the previous Invocation saved in this Invocation by Registry.invoke or Registry.getResponse. Invocations returned by ContentHandlerServer.getRequest MUST return null.

Returns:

the previous Invocation, if any, saved when this Invocation was invoked or returned as a response; may be null

See Also:

Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation), Registry.getResponse(boolean)

Since:

BlackBerry API 4.3.0

getInvokingAuthority

public String getInvokingAuthority()

Gets the authority, if any, used to authenticate the application that invoked this request. This value MUST be null unless the device has been able to authenticate this application. If non-null, it is the string identifying the authority.

Returns:

the authority used to authenticate this application and if the status is either ACTIVE or HOLD; otherwise it is null, the application has not been authenticated

See Also:

ContentHandler.getAuthority()

Since:

BlackBerry API 4.3.0

getInvokingID

public String getInvokingID()

Gets the ID of the application that invoked the content handler. This information is available only if the status is ACTIVE or HOLD. This information has been authenticated only if getInvokingAuthority is non-null.

Returns:

the invoking application's ID if the Invocation status is ACTIVE or HOLD; null otherwise

See Also:

Registry.getID()

Since:

BlackBerry API 4.3.0

getInvokingAppName

public String getInvokingAppName()

Get the user-friendly name of the application that invoked the content handler. This information is available only if the status is ACTIVE or HOLD. This information has been authenticated only if getInvokingAuthority is non-null.

Returns:

the application's name if status is ACTIVE or HOLD; null otherwise

See Also:

ContentHandler.getID()

Since:

BlackBerry API 4.3.0

findType

public String findType()
                throws IOException,
                       ContentHandlerException,
                       SecurityException

Finds the type of the content in this Invocation. If the getType method return value is non-null, then the type is returned.

If the type is null and the URL is non-null, then the content type will be found by accessing the content through the URL. When found, the type is set as if the setType method was called; subsequent calls to getType and findType will return the type. If an exception is thrown, the getType method will return null.

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

Returns:

the non-null content type

Throws:

IOException - if access to the content fails

ContentHandlerException - is thrown with a reason of ContentHandlerException.TYPE_UNKNOWN if the type is null and cannot be found from the content either because the URL is null or the type is not available from the content

IllegalArgumentException - if the content is accessed via the URL and the URL is invalid

SecurityException - is thrown if access to the content is required and is not permitted by the device security policy

See Also:

Invocation.setType(java.lang.String), Invocation.getType()

Since:

BlackBerry API 4.3.0

open

public Connection open(boolean timeouts)
                throws IOException,
                       SecurityException

Creates and opens a Connection to the content addressed by the URL in getURL. If the connection has already been initialized, this method will simply return the cached Connection object. This method is similar to Connector.open(getURL(), READ, timeouts) but may deliver the content from a cache. The application should use this method to access the content of the URL so that any type or content information cached by the implementation can be utilized. The content is opened in read only mode. Regardless of whether or not the content is cached, the application or content handler must have permission to access the content via the URL.

Parameters:

timeouts - a flag to indicate that the caller wants timeout exceptions

Returns:

a Connection object

Throws:

ConnectionNotFoundException - is thrown if:

• the target URL can not be found, or
• the requested protocol type is not supported

NullPointerException - if the URL is null

IllegalArgumentException - if a parameter is invalid.

IOException - if some other kind of I/O error occurs

SecurityException - is thrown if access to the protocol handler is prohibited

Since:

BlackBerry API 4.3.0

setCredentials

public void setCredentials(String username,
                           char[] password)

Provide the credentials needed to access the content. Use of the credential is protocol specific.

Parameters:

username - the username; may be null

password - the password for the username; may be null

Since:

BlackBerry API 4.3.0