Oracle Application Server Wireless J2ME SDK API Reference

J2ME SDK Overview

See:
Description

Packages

oracle.wireless.me.core
oracle.wireless.me.drm

J2ME SDK Overview

Client

Use the ServiceFactory class to create Service objects which represent services registered with the J2ME Proxy Server. For convenient access, store the URL to the J2ME Proxy Server as a property of your MIDlet suite. For example, to create a Service object for the TestWebService class in the default namespace, and assuming that the J2ME proxy server URL is stored in a MIDlet suite property called "j2me_proxy_url", do:

// Get the URL of the J2ME proxy server.
String servURL = getAppProperty("j2me_proxy_url");

if (servURL == null) {
servURL = "http://localhost:7777/mcs/wsproxy/proxy";
System.out.println("Unable to get j2me_proxy app property, using default: " + servURL);
}

ServiceFactory serviceFactory = ServiceFactory.getInstance();
Service service = serviceFactory.createService(servURL, Service.DEFAULT_NAMESPACE, "TestWebService");

The first parameter to createService is the URL of the J2ME Proxy Server, the second is the namespace, and the third is the name of the registered service.

Once you have an object of class Service, you can create Call objects. Each Call object represents an operation of the remote web service. For example, to create a Call objects for an operation called hello, do the following:

// Set cache timeout to 1 hour.
Call call = service.createCall("hello", 60);

The first parameter to createCall is the name of the operation of the web service. The second parameter is the number of minutes to cache the response in the wireless device. Use 0 to disable response caching, and –1 to cache forever.

Once you have a Call object, you can invoke the web service operation that it represents. Build a Java Vector to hold the parameters, and then call the Call object's invoke method. Assuming the hello operation takes a single String parameter, invoke hello as follows:

// Put the parameters in a Vector.
Vector params = new Vector();
params.addElement( new String("World") );

Response response = call.invoke(params, false);

The first parameter to the Call object’s invoke method is the Vector of parameters for the web service operation. The second parameter may be set to true if you want to bypass the local cache. In other words, true ignores any valid cached response and forces a network call to the remote web service.

The invoke method returns a Response object. Always check the Response object’s return code. If it is 0, the call succeeded, and you can use the Response object’s methods to access the information returned from the remote operation. If the return code is not 0, use the Response object’s getErrorMsg method to get the error message. Assuming operation hello returns a String, do:

// Check if the response is valid (0 = OK).
int retCode = response.getReturnCode();

String retVal;
if (retCode == 0) {
retVal = response.getString();
}
else { // return code not 0
retVal = "Call unsuccessful: " + response.getErrorMsg();
}

The ServiceManager class provides methods for more advanced functions, like queueing and cache management. It is VERY IMPORTANT for a MIDlet to call the close() method of ServiceManager when it exits. This closes the RMS RecordStore used for queueing and caching. For example:

protected void destroyApp(boolean unconditional)
throws MIDletStateChangeException
{
exitMIDlet();
}

public void commandAction(Command c, Displayable d)
{
if (c == exitCommand) {
exitMIDlet();
}
// possibly other command handling code here
}

private void exitMIDlet()
{
try {
ServiceManager.getInstance().close();
}
catch (Exception e) {
}

notifyDestroyed();
}

It is recommended that you also call ServiceManager.getInstance() in the MIDlet's startApp method:

protected void startApp() throws MIDletStateChangeException
{
ServiceManager.getInstance();

// other initialization code here
}

Important Notes

Sun's J2ME Wireless Toolkit versions 1.0.3 and 1.0.4 contain a bug that prevents requests over 2K from reaching the server, even if you use the MAX_REQUEST_SIZE property of the Service object. To send requests over 2K using the emulator, set the MULTIPLE_HTTP property of Service to "true". Remember to set it back to "false" before deploying to a real phone. The client has been tested on phones over the IDEN network and requests over 2K can successfully be sent with appropriate use of the MAX_REQUEST_SIZE property, even if MULTIPLE_HTTP is set to "false".

Remember to call "ServiceManager.getInstance().close();" EVERY TIME your MIDlet exits. Not calling this method leaves the RMS RecordStore open and may corrupt it. The closing of the RecordStore would normally be done in the finalize method of the ServiceManager class, but MIDP/CLDC don't support the finalize method.