test

Sun GlassFish Mobility Platform 1.1 Developer's Guide for Client Applications

Chapter 5 JerseyMe API Documentation

The JerseyMe library is a client API to access RESTful web services using the Java ME platform. It is modelled on Jersey's client API for the Java SE platform. The minimum platform requirements are CLDC 1.1 and MIDP 2.0. This chapter summarizes the classes, interface, and methods contained in the com.sun.jerseyme.api.client package, the only package in the JerseyMe API.

The API documentation is included in the MEP client bundle. In the directory where you unzipped the client bundle (see the Sun GlassFish Mobility Platform 1.1 Installation Guide for details), it is in the directory sgmp-client-1_1_01-fcs-b02/doc/JerseyMe/api.

The Client Class

Table 5–1 lists the constructors and methods belonging to the Client class. This class provides the entry point to the JerseyME API. Although the class contains a constructor, use the create method to create an instance of this class.

Table 5–1 Class com.sun.jerseyme.api.client.Client

Method 

Description 

Client()

No-argument constructor. 

public void clearCache()

Clears the cache, removing all local resources. 

public static Client create()

Returns an instance of this class. 

public WebResource resource(java.lang.String uri)

Returns a web resource (an instance of the WebResource class) given a URI.

public void setCachePolicy(long elapsedTime)

Sets the elapsed time, in milliseconds, after which a resource must be refreshed in the cache. If the argument is zero, resources are refreshed every time. If a resource cannot be refreshed, it will be returned from the cache, even if stale. 

public static void setLogging(boolean b)

Enables or disables logging in the API. 

The UniformInterface Interface

Table 5–2 lists the methods in the UniformInterface interface, which is implemented by the WebResource class.

These methods throw a UniformInterfaceException (see The UniformInterfaceException Class).

Table 5–2 Interface com.sun.jerseyme.api.client.UniformInterface

Method 

Description 

UniformInterface accept(java.lang.String type)

Sets an Accept HTTP header. 

UniformInterface acceptLanguage(java.lang.String type)

Sets an Accept-Language HTTP header. 

UniformInterface cookie(java.lang.String type)

Sets a Cookie HTTP header. 

void delete()

Invokes the DELETE method with no request entity or response. May use X-HTTP-Method-Override if HTTP DELETE is not supported. 

java.lang.Object delete(java.lang.Class c)

Invokes the DELETE method with no request entity that returns a response. May use X-HTTP-Method-Override if HTTP DELETE is not supported. 

java.lang.Object delete(java.lang.Class c, java.lang.Object o)

Invokes the DELETE method with a request entity that returns a response. May use X-HTTP-Method-Override if HTTP DELETE is not supported. 

void delete(java.lang.Object o)

Invokes the DELETE method with a request entity and no response. May use X-HTTP-Method-Override if HTTP DELETE is not supported. 

java.lang.Object get(java.lang.Class c)

Invokes the GET method. 

java.lang.Object get(java.lang.Class c, boolean ignoreCache)

Invokes the GET method, possibly ignoring local cache. 

java.util.Hashtable head()

Invokes the HEAD method, returning a hash table with all the HTTP headers returned. 

void post()

Invokes the POST method with no request entity or response. 

java.lang.Object post(java.lang.Class c)

Invokes the POST method with no request entity that returns a response. 

java.lang.Object post(java.lang.Class c, java.lang.Object o)

Invokes the POST method with a request entity that returns a response. 

void post(java.lang.Object o)

Invokes the POST method with a request entity and no response. 

void put()

Invokes the PUT method with no request entity or response. May use X-HTTP-Method-Override if HTTP PUT is not supported. 

java.lang.Object put(java.lang.Class c)

Invokes the PUT method with no request entity that returns a response. May use X-HTTP-Method-Override if HTTP PUT is not supported. 

java.lang.Object put(java.lang.Class c, java.lang.Object o)

Invokes the PUT method with a request entity that returns a response. May use X-HTTP-Method-Override if HTTP PUT is not supported. 

void put(java.lang.Object o)

Invokes the PUT method with a request entity and no response. May use X-HTTP-Method-Override if HTTP PUT is not supported. 

UniformInterface type(java.lang.String type)

Sets a Content-Type HTTP header. 

The UniformInterfaceException Class

Table 5–3 lists the constructors in the UniformInterfaceException class. This class is a runtime exception that indicates an error in a UniformInterface method.

Table 5–3 Class com.sun.jerseyme.api.client.UniformInterfaceException

Method 

Description 

public UniformInterfaceException(java.lang.Exception e)

Constructor that takes an Exception argument.

public UniformInterfaceException(java.lang.String message)

Constructor that takes a String argument.

The WebResource Class

Table 5–4 lists the methods in the WebResource class, which implements a web resource on which the HTTP methods GET, PUT, POST, DELETE and HEAD can be called. To create an instance of this class, call the Client.resource(String) method. This class implements the UniformInterface interface. Only the lastGetCached method is specific to this class.

Table 5–4 Class com.sun.jerseyme.api.client.WebResource

Method 

Description 

public UniformInterface accept(java.lang.String type)

Adds an accept type to the list prepared for the next HTTP GET request. 

UniformInterface acceptLanguage(java.lang.String type)

Sets a value for the HTTP header Accept-Language. 

UniformInterface cookie(java.lang.String type)

Sets a value for the HTTP header Cookie. 

void delete()

Deletes an empty resource without returning any content. Uses X-HTTP-Method-Override to override POST operation. 

java.lang.Object delete(java.lang.Class c)

Deletes a resource without returning any content. The argument must be an instance of String, InputStream, or byte[]. If the argument is of type String, the platform's default character set is used for encoding. Uses X-HTTP-Method-Override to override POST operation.

java.lang.Object delete(java.lang.Class c, java.lang.Object o)

Deletes a resource. The first argument specifies the class of the instance returned and must be String, InputStream, or byte[]. The second argument must be an instance of String, InputStream, or byte[]. If the result or the argument is of type String, the platform's default character set is used for decoding. Uses X-HTTP-Method-Override to override POST operation.

void delete(java.lang.Object o)

Posts a resource without returning any content. The argument must be an instance of String, InputStream, or byte[]. If the argument is of type String, the platform's default character set is used for encoding.

java.lang.Object get(java.lang.Class c)

Gets a resource by first looking it up in the local cache. If the resource is available locally and it isn't stale, it is returned. If it is stale, it will be re-fetched. If it can't be re-fetched, its stale copy is returned. The argument specifies the class of the instance returned; it must be String, InputStream, or byte[].

java.lang.Object get(java.lang.Class c, boolean ignoreCache)

Same as get(Class) except that you can force the local cache to be ignored by setting the second parameter to true. The first argument specifies the class of the instance returned; it must be String, InputStream, or byte[]. The second argument is a flag that indicates whether or not the cache should be inspected.

java.util.Hashtable head()

Calls the HEAD operation on the resource, returning a hash table of headers. 

public boolean lastGetCached()

Returns a boolean value that indicates whether the last HTTP GET operation was resolved using the local cache. 

void post()

Posts an empty resource without returning any content. 

java.lang.Object post(java.lang.Class c)

Posts an empty resource. If the result is of type String, the platform's default character set is used for decoding. The argument specifies the class of the instance returned; it must be String, InputStream, or byte[].

java.lang.Object post(java.lang.Class c, java.lang.Object o)

Posts a resource. If the result or the parameter is of type String, the platform's default character set is used for decoding. The first argument specifies the class of the instance returned; it must be String, InputStream, or byte[]. The second argument must be an instance of String, InputStream, or byte[].

void post(java.lang.Object o)

Posts a resource without returning any content. If the parameter is of type String, the platform's default character set is used for encoding. The argument must be an instance of String, InputStream, or byte[].

void put()

Puts an empty resource without returning any content. Uses X-HTTP-Method-Override to override a POST operation. 

java.lang.Object put(java.lang.Class c)

Puts an empty resource. If the result is of type String, the platform's default character set is used for decoding. Uses X-HTTP-Method-Override to override a POST operation. The argument specifies the class of the instance returned; it must be String, InputStream, or byte[].

java.lang.Object put(java.lang.Class c, java.lang.Object o)

Puts a resource. If the result or the argument is of type String, the platform's default character set is used for decoding. Uses X-HTTP-Method-Override to override a POST operation. The first argument specifies the class of the instance returned; it must be String, InputStream, or byte[]. The second argument must be an instance of String, InputStream, or byte[].

void put(java.lang.Object o)

Puts a resource without returning any content. If the argument is of type String, the platform's default character set is used for encoding. Uses X-HTTP-Method-Override to override a POST operation. The argument must be an instance of String, InputStream, or byte[].

UniformInterface type(java.lang.String type)

Sets the value for HTTP header Content-Type.