|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--javax.microedition.content.Invocation
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.
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:
INITindicates the Invocation is still being
initializedWAITINGindicates that this Invocation is waiting
to complete ACTIVEindicates the Invocation is currently
being processed HOLDindicates 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.
| 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 |
public static final int ACTIVE
public static final int CANCELLED
ContentHandlerServer.finish
will have this status.public static final int ERROR
public static final int HOLD
Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation)public static final int INIT
public static final int INITIATED
public static final int OK
ContentHandlerServer.finish
will have this status.public static final int WAITING
Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation)| Constructor Detail |
public Invocation()
INIT.
The URL, type, ID, action, arguments, and data are set to
empty arrays, and initialized to require a response.public Invocation(String url)
new Invocation(url, null, null, true, null).url - the URL of the content to be dispatched;
may be nullpublic Invocation(String url, String type)
new Invocation(url, type, null, true, null).url - the URL of the content to be dispatched;
may be nulltype - the content type; may be nullpublic Invocation(String url, String type, String ID)
new Invocation(url, type, ID, true, null).url - the URL of the content to be dispatched;
may be nulltype - the content type; may be nullID - the ID of the content handler; may be nullpublic Invocation(String url, String type, String ID, boolean responseRequired, String action)
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.url - the URL of the content to be dispatched;
may be nulltype - the content type; may be nullID - the ID of the content handler; may be nullresponseRequired - true if a response is
required; false otherwiseaction - the action that the content handler should perform on the
content; may be null| Method Detail |
public String findType() throws IOException, ContentHandlerException, 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 typeIOException - 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 contentIllegalArgumentException - if the content is accessed via
the URL and the URL is invalidSecurityException - is thrown if access to the content
is required and is not permittedsetType(java.lang.String),
getType()public String getAction()
null if it has not been setsetAction(java.lang.String)public String[] getArgs()
nullsetArgs(java.lang.String[])public byte[] getData()
nullsetData(byte[])public String getID()
nullRegistry.forID(java.lang.String, boolean),
setID(java.lang.String)public String getInvokingAppName()
ACTIVE or HOLD.
This information has been authenticated only if
getInvokingAuthority is non-null.ACTIVE
or HOLD; null otherwiseContentHandler.getID()public 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 String getInvokingID()
ACTIVE or HOLD.
This information has been authenticated only if
getInvokingAuthority is non-null.ACTIVE
or HOLD; null otherwiseRegistry.getID()public Invocation getPrevious()
Registry.invoke or
Registry.getResponse.
Invocations returned by
ContentHandlerServer.getRequest
MUST return null.nullRegistry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation),
Registry.getResponse(boolean)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 int getStatus()
INIT, WAITING, HOLD,
ACTIVE, OK,
CANCELLED,
INITIATED, or ERROR.Registry.invoke(javax.microedition.content.Invocation, javax.microedition.content.Invocation),
Registry.getResponse(boolean),
ContentHandlerServer.getRequest(boolean),
ContentHandlerServer.finish(javax.microedition.content.Invocation, int)public 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 String getURL()
setURL.null if it has not been setsetURL(java.lang.String)public Connection open(boolean timeouts) throws IOException, 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:
NullPointerException - if the URL is nullIllegalArgumentException - if a parameter is invalid.IOException - if some other kind of I/O error occursSecurityException - is thrown if access to the
protocol handler is prohibitedpublic void setAction(String action)
action - the action to be performed on the content;
may be nullgetAction()public void setArgs(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 void setCredentials(String username, char[] password)
username - the username; may be nullpassword - the password for the username;
may be nullpublic void setData(byte[] data)
invoked
or finished;
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 void setID(String ID)
ID - of the content handler; may be nullgetID()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 otherwiseIllegalStateException - is thrown if the status is not
INITgetResponseRequired()public void setType(String type)
type - the type to be set for the content; may be nullgetType(),
findType()public void setURL(String url)
url - the URL to be set; may be nullgetURL()
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2007 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.