javax.microedition.content
Class Invocation

java.lang.Object
  extended by 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:

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





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.