public final class Invocation
extends java.lang.Object
setArguments
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.
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:
INIT
indicates the Invocation is still being
initializedWAITING
indicates that this Invocation is waiting
to complete ACTIVE
indicates the Invocation is currently
being processed HOLD
indicates the Invocation is currently
waiting for a chained Invocation to complete ERROR
, OK
, CANCELLED
indicate that the Invocation is completeINITIATED
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.
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 getURL()
method MUST return the original URL unmodified
by any implementation specific information.
Modifier and Type | Field and Description |
---|---|
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 canceled 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 and Description |
---|
Invocation()
Creates a new Invocation.
|
Invocation(java.lang.String url)
Convenient alternative constructor with a URL.
|
Invocation(java.lang.String url,
java.lang.String type)
Convenient alternative constructor with URL and type.
|
Invocation(java.lang.String url,
java.lang.String type,
java.lang.String ID)
Convenient alternative constructor with URL, type, and ID.
|
Invocation(java.lang.String url,
java.lang.String type,
java.lang.String ID,
boolean responseRequired,
java.lang.String action)
Creates a new instance and initializes it from the
specified parameters.
|
Modifier and Type | Method and Description |
---|---|
java.lang.String |
findType()
Finds the type of the content in this Invocation.
|
java.lang.String |
getAction()
Gets the action to be performed on the content.
|
java.lang.String[] |
getArgs()
Gets the argument list as an array of Strings.
|
byte[] |
getData()
Gets the data for the Invocation.
|
java.lang.String |
getID()
Gets the content handler ID for this Invocation.
|
java.lang.String |
getInvokingAppName()
Get the user-friendly name of the application that invoked
the content handler.
|
java.lang.String |
getInvokingAuthority()
Gets the authority, if any, used to authenticate the
application that invoked this request.
|
java.lang.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 . |
java.lang.String |
getType()
Gets the content type for the Invocation.
|
java.lang.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(java.lang.String action)
Sets the action to be performed on the content.
|
void |
setArgs(java.lang.String[] args)
Sets the argument list to a new array of Strings.
|
void |
setCredentials(java.lang.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(java.lang.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(java.lang.String type)
Sets the type for the Invocation.
|
void |
setURL(java.lang.String url)
Sets the URL for the invocation.
|
public static final int INIT
public static final int ACTIVE
public static final int WAITING
public static final int HOLD
public static final int OK
ContentHandlerServer.finish
will have this status.public static final int CANCELLED
ContentHandlerServer.finish
will have this status.public static final int ERROR
public static final int INITIATED
public Invocation()
INIT
.
The URL, type, ID, action, arguments, and data are set to
empty arrays, and initialized to require a response.public Invocation(java.lang.String url, java.lang.String type, java.lang.String ID)
new Invocation(url, type, ID, true, null)
.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
public Invocation(java.lang.String url, java.lang.String type)
new Invocation(url, type, null, true, null)
.url
- the URL of the content to be dispatched;
may be null
type
- the content type; may be null
public Invocation(java.lang.String url)
new Invocation(url, null, null, true, null)
.url
- the URL of the content to be dispatched;
may be null
public Invocation(java.lang.String url, java.lang.String type, java.lang.String ID, boolean responseRequired, java.lang.String action)
INIT
.
None of the values are checked until the
Registry.invoke
method is called.
String arguments or data can be set with
setArguments
or setData
.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
otherwiseaction
- the action that the content handler should perform on the
content; may be null
public void setArgs(java.lang.String[] args)
Registry.invoke
to
check that none of the values are null
.args
- the String array; may be null
.
A null
argument is treated the same as a zero-length arraygetArgs()
public java.lang.String[] getArgs()
null
setArgs(java.lang.String[])
public void setData(byte[] data)
invoked
or finish
ed;
modifications to array elements will otherwise be visible.data
- the byte data array; may be null
.
A null
is treated the same as a zero-length arraygetData()
public byte[] getData()
null
setData(byte[])
public java.lang.String getURL()
setURL
.null
if it has not been setsetURL(java.lang.String)
public void setURL(java.lang.String url)
url
- the URL to be set; may be null
getURL()
public java.lang.String getType()
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
.null
if it has not been setsetType(java.lang.String)
,
findType()
public void setType(java.lang.String type)
type
- the type to be set for the content; may be null
getType()
,
findType()
public java.lang.String getAction()
null
if it has not been setsetAction(java.lang.String)
public void setAction(java.lang.String action)
action
- the action to be performed on the content;
may be null
getAction()
public boolean getResponseRequired()
responseRequired
mode for
this Invocation.
If true
, then the invoking application requires a
response to the Invocation.responseRequired
mode. If
true
, then a response must be returned to the
invoking application.setResponseRequired(boolean)
public void setResponseRequired(boolean responseRequired)
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
.responseRequired
- true
to require a response,
false
otherwisejava.lang.IllegalStateException
- is thrown if the status is not
INIT
getResponseRequired()
public int getStatus()
INIT
, WAITING
, HOLD
,
ACTIVE
, OK
,
CANCELLED
,
INITIATED
, or ERROR
.public java.lang.String getID()
null
Registry.forID(java.lang.String, boolean)
,
setID(java.lang.String)
public void setID(java.lang.String ID)
ID
- of the content handler; may be null
getID()
public Invocation getPrevious()
Registry.invoke
or
Registry.getResponse
.
Invocations returned by
ContentHandlerServer.getRequest
MUST return null
.null
Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation)
,
Registry.getResponse(boolean)
public java.lang.String getInvokingAuthority()
null
unless the device has been
able to authenticate this application.
If non-null
, it is the string identifying the
authority.ACTIVE
or HOLD
;
otherwise it is null
,
the application has not been authenticatedContentHandler.getAuthority()
public java.lang.String getInvokingID()
ACTIVE
or HOLD
.
This information has been authenticated only if
getInvokingAuthority
is non-null.ACTIVE
or HOLD
; null
otherwiseRegistry.getID()
public java.lang.String getInvokingAppName()
ACTIVE
or HOLD
.
This information has been authenticated only if
getInvokingAuthority
is non-null.ACTIVE
or HOLD
; null
otherwiseContentHandler.getID()
public java.lang.String findType() throws java.io.IOException, ContentHandlerException, java.lang.SecurityException
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.
non-null
content typejava.io.IOException
- if access to the content failsContentHandlerException
- 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 contentjava.lang.IllegalArgumentException
- if the content is accessed via
the URL and the URL is invalidjava.lang.SecurityException
- is thrown if access to the content
is required and is not permittedsetType(java.lang.String)
,
getType()
public Connection open(boolean timeouts) throws java.io.IOException, java.lang.SecurityException
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.timeouts
- a flag to indicate that the caller
wants timeout exceptionsConnectionNotFoundException
- is thrown if:
java.lang.NullPointerException
- if the URL is nulljava.lang.IllegalArgumentException
- if a parameter is invalid.java.io.IOException
- if some other kind of I/O error occursjava.lang.SecurityException
- is thrown if access to the
protocol handler is prohibitedpublic void setCredentials(java.lang.String username, char[] password)
username
- the username; may be null
password
- the password for the username;
may be null
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.