| java.lang.Object
 javax.microedition.content.Invocation
| Invocation | | final public class Invocation (Code) | | 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
Invocation.setArgs setArgs and
Invocation.setData 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 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
Invocation.findType 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
Invocation.INIT INIT .
When the application calls
Registry.invoke Registry.invoke the status changes to
Invocation.WAITING WAITING .
When the Registry.getResponse method is invoked, the
status will be updated to the appropriate
Invocation.OK OK ,
Invocation.CANCELLED CANCELLED ,
Invocation.INITIATED INITIATED , or
Invocation.ERROR ERROR status from
the content handler.
A content handler calls
ContentHandlerServer.getRequest ContentHandlerServer.getRequest to get the next request.
The request always has the
Invocation.ACTIVE ACTIVE status.
When the handler is finished acting on the content, the status
is set to either
Invocation.OK OK ,
Invocation.CANCELLED CANCELLED , or
Invocation.INITIATED INITIATED by
the
ContentHandlerServer.finish 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
Invocation.HOLD HOLD by the Registry.invoke method. The status of the previous
Invocation is restored to
Invocation.ACTIVE ACTIVE by the
Registry.getResponse 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
Invocation.ERROR 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
Invocation.open open method.
The
Invocation.getURL method MUST return the original URL unmodified
by any implementation specific information.
|
| Field Summary | |
| final public static int | ACTIVE
This Invocation is a new request and is being handled
by the content handler. | | final public static int | CANCELLED
The processing of the Invocation was cancelled by
the ContentHandler. | | final public static int | ERROR
The content handler failed to correctly process the Invocation
request. | | final public static int | HOLD
This Invocation is on hold until a chained
Invocation is completed. | | final public static int | INIT
This Invocation was just constructed and is being initialized. | | final public static int | INITIATED
The processing of the Invocation has been initiated and will
continue. | | final public static int | OK
The content handler successfully completed processing
the Invocation. | | final public static int | WAITING
This Invocation has been invoked and is waiting to be
complete. |
| Method Summary | |
| public String | findType()
Finds the type of the content in this Invocation.
If the getType method return value is
non-null, then the type is returned. | | public String | getAction()
Gets the action to be performed on the content. | | public String[] | getArgs()
Gets the argument list as an array of Strings. | | public byte[] | getData()
Gets the data for the Invocation. | | public String | getID()
Gets the content handler ID for this Invocation. | | InvocationImpl | getInvocImpl()
Gets the InvocationImpl for this Invocation. | | public String | getInvokingAppName()
Get the user-friendly name of the application that invoked
the content handler. | | public String | getInvokingAuthority()
Gets the authority, if any, used to authenticate the
application that invoked this request. | | public String | getInvokingID()
Gets the ID of the application that invoked the content
handler. | | public Invocation | getPrevious()
Gets the previous Invocation saved in this
Invocation by
Registry.invoke Registry.invoke or
Registry.getResponse Registry.getResponse . | | public boolean | getResponseRequired()
Gets the responseRequired mode for
this Invocation.
If true, then the invoking application requires a
response to the Invocation.
the current value of the responseRequiredmode. | | public int | getStatus()
Gets the status of this Invocation, which can be
INIT, WAITING, HOLD,
ACTIVE, OK,
CANCELLED,
INITIATED, or ERROR. | | public String | getType()
Gets the content type for the Invocation. | | public String | getURL()
Gets the URL for the invocation. | | public Connection | open(boolean timeouts)
Creates and opens a Connection to the content addressed by
the URL in
Invocation.getURL getURL . | | public void | setAction(String action)
Sets the action to be performed on the content. | | public void | setArgs(String[] args)
Sets the argument list to a new array of Strings. | | public void | setCredentials(String username, char[] password)
Provide the credentials needed to access the content. | | public void | setData(byte[] data)
Sets the data used for the Invocation. | | public void | setID(String ID)
Sets the ID of the content handler for this Invocation. | | void | setInvocImpl(InvocationImpl invocImpl)
Sets the InvocationImpl for this Invocation. | | public void | setResponseRequired(boolean responseRequired)
Sets the responseRequired mode for
this Invocation. | | public void | setType(String type)
Sets the type for the Invocation. | | public void | setURL(String url)
Sets the URL for the invocation. |
| ACTIVE | | final public static int ACTIVE(Code) | | This Invocation is a new request and is being handled
by the content handler.
|
| CANCELLED | | final public static int CANCELLED(Code) | | The processing of the Invocation was cancelled by
the ContentHandler.
Invocations queued with
ContentHandlerServer.finish ContentHandlerServer.finish will have this status.
|
| ERROR | | final public static int ERROR(Code) | | The content handler failed to correctly process the Invocation
request.
|
| HOLD | | final public static int HOLD(Code) | | This Invocation is on hold until a chained
Invocation is completed.
See Also: Registry.invoke |
| INIT | | final public static int INIT(Code) | | This Invocation was just constructed and is being initialized.
|
| INITIATED | | final public static int INITIATED(Code) | | 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.
|
| OK | | final public static int OK(Code) | | The content handler successfully completed processing
the Invocation.
Invocations queued with
ContentHandlerServer.finish ContentHandlerServer.finish will have this status.
|
| WAITING | | final public static int WAITING(Code) | | This Invocation has been invoked and is waiting to be
complete.
See Also: Registry.invoke |
| Invocation | | public Invocation()(Code) | | 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.
|
| Invocation | | public Invocation(String url, String type, String ID)(Code) | | 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
Parameters:
type - the content type; may be null
Parameters:
ID - the ID of the content handler; may be null |
| Invocation | | public Invocation(String url, String type)(Code) | | 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
Parameters:
type - the content type; may be null |
| Invocation | | public Invocation(String url)(Code) | | 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 |
| Invocation | | public Invocation(String url, String type, String ID, boolean responseRequired, String action)(Code) | | 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 Registry.invoke method is called.
String arguments or data can be set with
Invocation.setArgs setArgs or
Invocation.setData setData .
Parameters:
url - the URL of the content to be dispatched;may be null
Parameters:
type - the content type; may be null
Parameters:
ID - the ID of the content handler; may be null
Parameters:
responseRequired - true if a response isrequired; false otherwise
Parameters:
action - the action that the content handler should perform on thecontent; may be null |
| Invocation | | Invocation(InvocationImpl impl)(Code) | | Creates a new Invocation to refer to an InvocationImpl.
And makes the InvocationImpl refer to the new Invocation.
Parameters:
impl - and InvocationImpl to be associated with this Invocation |
| findType | | public String findType() throws IOException, ContentHandlerException, SecurityException(Code) | | 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
Invocation.getType getType and
Invocation.findType 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.
the non-null content type
exception:
IOException - if access to the content fails
exception:
ContentHandlerException - is thrown with a reason ofContentHandlerException.TYPE_UNKNOWNif the type is null and cannot be found from thecontent either because the URL is null or the type isnot available from the content
exception:
IllegalArgumentException - if the content is accessed viathe URL and the URL is invalid
exception:
SecurityException - is thrown if access to the contentis required and is not permitted
See Also: Invocation.setType
See Also: Invocation.getType |
| getAction | | public String getAction()(Code) | | Gets the action to be performed on the content.
the content action or null if it has not been set
See Also: Invocation.setAction |
| getArgs | | public String[] getArgs()(Code) | | 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.
the arguments array, which MUST NOT be null
See Also: Invocation.setArgs |
| getData | | public byte[] getData()(Code) | | 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.
the data array, which MUST NOT be null
See Also: Invocation.setData |
| getInvocImpl | | InvocationImpl getInvocImpl()(Code) | | Gets the InvocationImpl for this Invocation.
the InvocationImpl delgate. |
| getInvokingAppName | | public String getInvokingAppName()(Code) | | 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.
the application's name if status is ACTIVEor HOLD; null otherwise
See Also: ContentHandler.getID |
| getInvokingAuthority | | public String getInvokingAuthority()(Code) | | 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.
the authority used to authenticate this applicationand if the status is either ACTIVE or HOLD;otherwise it is null,the application has not been authenticated
See Also: ContentHandler.getAuthority |
| getInvokingID | | public String getInvokingID()(Code) | | 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.
the invoking application's ID if the Invocation statusis ACTIVEor HOLD; null otherwise
See Also: Registry.getID |
| getResponseRequired | | public boolean getResponseRequired()(Code) | | Gets the responseRequired mode for
this Invocation.
If true, then the invoking application requires a
response to the Invocation.
the current value of the responseRequiredmode. Iftrue, then a response must be returned to theinvoking application.
See Also: Invocation.setResponseRequired |
| getType | | public String getType()(Code) | | Gets the content type for the Invocation.
The type for this Invocation may be set by the application using
Invocation.setType setType .
The
Invocation.findType 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.
the content type or null if it has not been set
See Also: Invocation.setType
See Also: Invocation.findType |
| open | | public Connection open(boolean timeouts) throws IOException, SecurityException(Code) | | Creates and opens a Connection to the content addressed by
the URL in
Invocation.getURL 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 callerwants timeout exceptions a Connection object
exception:
ConnectionNotFoundException - is thrown if:- the target URL can not be found, or
- the requested protocol type is not supported
exception:
NullPointerException - if the URL is null
exception:
IllegalArgumentException - if a parameter is invalid.
exception:
IOException - if some other kind of I/O error occurs
exception:
SecurityException - is thrown if access to theprotocol handler is prohibited |
| setAction | | public void setAction(String action)(Code) | | 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 |
| setArgs | | public void setArgs(String[] args)(Code) | | 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 Registry.invoke to
check that none of the values are null.
Parameters:
args - the String array; may be null.A nullargument is treated the same as a zero-length array
See Also: Invocation.getArgs |
| setCredentials | | public void setCredentials(String username, char[] password)(Code) | | Provide the credentials needed to access the content.
Use of the credential is protocol specific.
Parameters:
username - the username; may be null
Parameters:
password - the password for the username;may be null |
| setData | | public void setData(byte[] data)(Code) | | 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 |
| setID | | public void setID(String ID)(Code) | | Sets the ID of the content handler for this Invocation.
Parameters:
ID - of the content handler; may be null
See Also: Invocation.getID |
| setInvocImpl | | void setInvocImpl(InvocationImpl invocImpl)(Code) | | Sets the InvocationImpl for this Invocation.
Parameters:
invocImpl - the InvocationImpl delgate. |
| setResponseRequired | | public void setResponseRequired(boolean responseRequired)(Code) | | 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
exception:
IllegalStateException - is thrown if the status is notINIT
See Also: Invocation.getResponseRequired |
| setURL | | public void setURL(String url)(Code) | | Sets the URL for the invocation.
Parameters:
url - the URL to be set; may be null
See Also: Invocation.getURL |
|
|