File	Doc	Category	Size	Date	Package
Invocation.java	API Doc	phoneME MR2 API (J2ME)	23803	Wed May 02 18:00:44 BST 2007	javax.microedition.content

Invocation

• java.lang.Object

Fields Summary
private com.sun.midp.content.InvocationImpl	invocImpl The InvocationImpl to delegate to.
public static final int	INIT This Invocation was just constructed and is being initialized.
public static final int	ACTIVE This Invocation is a new request and is being handled by the content handler.
public static final int	WAITING This Invocation has been invoked and is waiting to be complete.
public static final int	HOLD This Invocation is on hold until a chained Invocation is completed.
public static final int	OK The content handler successfully completed processing the Invocation. Invocations queued with {@link ContentHandlerServer#finish ContentHandlerServer.finish} will have this status.
public static final int	CANCELLED The processing of the Invocation was cancelled by the ContentHandler. Invocations queued with {@link ContentHandlerServer#finish ContentHandlerServer.finish} will have this status.
public static final int	ERROR The content handler failed to correctly process the Invocation request.
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.

Constructors Summary
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. invocImpl = new InvocationImpl(this);
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). param url the URL of the content to be dispatched; may be null param type the content type; may be null param ID the ID of the content handler; may be null this(url, type, ID, true, null);
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). param url the URL of the content to be dispatched; may be null param type the content type; may be null this(url, type, null, true, null);
public Invocation(String url) Convenient alternative constructor with a URL. The behavior is identical to new Invocation(url, null, null, true, null). param url the URL of the content to be dispatched; may be null this(url, null, null, true, null);
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 {@link Registry#invoke Registry.invoke} method is called. String arguments or data can be set with {@link #setArgs setArgs} or {@link #setData setData}. param url the URL of the content to be dispatched; may be null param type the content type; may be null param ID the ID of the content handler; may be null param responseRequired true if a response is required; false otherwise param action the action that the content handler should perform on the content; may be null this(); invocImpl.setURL(url); invocImpl.setType(type); invocImpl.setID(ID); invocImpl.setResponseRequired(responseRequired); invocImpl.setAction(action);
Invocation(com.sun.midp.content.InvocationImpl impl) Creates a new Invocation to refer to an InvocationImpl. And makes the InvocationImpl refer to the new Invocation. param impl and InvocationImpl to be associated with this Invocation invocImpl = impl; if (impl != null) { impl.invocation = this; }

Methods Summary
public java.lang.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. 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 {@link #getType getType} and {@link #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. return the non-null content type exception IOException if access to the content fails exception ContentHandlerException is thrown with a reason of {@link 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 exception IllegalArgumentException if the content is accessed via the URL and the URL is invalid exception SecurityException is thrown if access to the content is required and is not permitted see Invocation#setType see Invocation#getType // Delegated to the implementation class return invocImpl.findType();
public java.lang.String	getAction() Gets the action to be performed on the content. return the content action or null if it has not been set see #setAction return invocImpl.getAction();
public java.lang.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. return the arguments array, which MUST NOT be null see #setArgs return invocImpl.getArgs();
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. return the data array, which MUST NOT be null see #setData return invocImpl.getData();
public java.lang.String	getID() Gets the content handler ID for this Invocation. return the ID of the ContentHandler; may be null see Registry#forID see #setID // Delegated to the implementation class return invocImpl.getID();
com.sun.midp.content.InvocationImpl	getInvocImpl() Gets the InvocationImpl for this Invocation. return the InvocationImpl delgate. return invocImpl;
public java.lang.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. return the application's name if status is ACTIVE or HOLD; null otherwise see ContentHandler#getID // Delegated to the implementation class return invocImpl.getInvokingAppName();
public java.lang.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. return 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 ContentHandler#getAuthority // Delegated to the implementation class return invocImpl.getInvokingAuthority();
public java.lang.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. return the invoking application's ID if the Invocation status is ACTIVE or HOLD; null otherwise see Registry#getID // Delegated to the implementation class return invocImpl.getInvokingID();
public javax.microedition.content.Invocation	getPrevious() Gets the previous Invocation saved in this Invocation by {@link Registry#invoke Registry.invoke} or {@link Registry#getResponse Registry.getResponse}. Invocations returned by {@link ContentHandlerServer#getRequest ContentHandlerServer.getRequest} MUST return null. return the previous Invocation, if any, saved when this Invocation was invoked or returned as a response; may be null see Registry#invoke see Registry#getResponse InvocationImpl prev = invocImpl.getPrevious(); if (prev != null) { if (prev.invocation == null) { /* * An InvocationImpl created by the implementation needs * a Invocation to return to the application. */ prev.invocation = new Invocation(prev); } return prev.invocation; } else { return null; }
public boolean	getResponseRequired() Gets the responseRequired mode for this Invocation. If true, then the invoking application requires a response to the Invocation. return the current value of the responseRequired mode. If true, then a response must be returned to the invoking application. see #setResponseRequired return invocImpl.getResponseRequired();
public int	getStatus() Gets the status of this Invocation, which can be INIT, WAITING, HOLD, ACTIVE, OK, CANCELLED, INITIATED, or ERROR. return the status of this Invocation see Registry#invoke see Registry#getResponse see ContentHandlerServer#getRequest see ContentHandlerServer#finish // Delegated to the implementation class return invocImpl.getStatus();
public java.lang.String	getType() Gets the content type for the Invocation. The type for this Invocation may be set by the application using {@link #setType setType}. The {@link #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. return the content type or null if it has not been set see #setType see #findType return invocImpl.getType();
public java.lang.String	getURL() Gets the URL for the invocation. The URL must be equal to the value set with {@link #setURL setURL}. return the URL or null if it has not been set see #setURL return invocImpl.getURL();
public javax.microedition.io.Connection	open(boolean timeouts) Creates and opens a Connection to the content addressed by the URL in {@link #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. param timeouts a flag to indicate that the caller wants timeout exceptions return 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 the protocol handler is prohibited String url = getURL(); url.length(); // Throw NPE if null Connection conn = Connector.open(url, Connector.READ, timeouts); return conn;
public void	setAction(java.lang.String action) Sets the action to be performed on the content. param action the action to be performed on the content; may be null see #getAction invocImpl.setAction(action);
public void	setArgs(java.lang.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 {@link Registry#invoke Registry.invoke} to check that none of the values are null. param args the String array; may be null. A null argument is treated the same as a zero-length array see #getArgs invocImpl.setArgs(args);
public void	setCredentials(java.lang.String username, char[] password) Provide the credentials needed to access the content. Use of the credential is protocol specific. param username the username; may be null param password the password for the username; may be null invocImpl.setCredentials(username, password);
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. param data the byte data array; may be null. A null is treated the same as a zero-length array see #getData invocImpl.setData(data);
public void	setID(java.lang.String ID) Sets the ID of the content handler for this Invocation. param ID of the content handler; may be null see #getID // Delegated to the implementation class invocImpl.setID(ID);
void	setInvocImpl(com.sun.midp.content.InvocationImpl invocImpl) Sets the InvocationImpl for this Invocation. param invocImpl the InvocationImpl delgate. this.invocImpl = invocImpl;
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. param responseRequired true to require a response, false otherwise exception IllegalStateException is thrown if the status is not INIT see #getResponseRequired invocImpl.setResponseRequired(responseRequired);
public void	setType(java.lang.String type) Sets the type for the Invocation. param type the type to be set for the content; may be null see #getType see #findType invocImpl.setType(type);
public void	setURL(java.lang.String url) Sets the URL for the invocation. param url the URL to be set; may be null see #getURL invocImpl.setURL(url);