REST API:BaseClient

The BaseClient demo program logs into the platform, echoes the sessionId, and logs out. It's a superclass for other programs that will utilize other REST resources before logging out. (In BaseClient.java, the main() method is a test that lets you know the login succeeded.) This page summarizes the methods it contains.

Tip: The REST_samples.zip file contains BaseClient, the utility class it uses, and extensions to it that demonstrate REST operations.

Setting Up the Development Enviroment

The sample programs use the following JARs:

JAR / Version	Contains...	Used by ...
Apache Wink Client wink-1.0-incubating.jar	RestClient	BaseClient PackageDownloadClient PackageSubscribeClient
Apache Commons HTTP Client commons-httpclient-3.1.jar	HttpClient	BulkUploadClient StaticResourceUploadClient
Xerces XML Parser xerces.jar	XML pretty-print classes DocumentBuilder	BaseUtil BulkUploadClient
JAX-RS (Java API for RESTful Web Services) jsr311-api-1.0.jar	Media type constants	BulkUploadClient PackageDownloadClient PackageSubscribeClient StaticResourceUploadClient
	MultivaluedMap	PackageDownloadClient

Notes

• The jar files can be found in the REST samples zipfile.
• The Wink REST client makes for simpler coding of standard REST requests. But so far, at least, it does not appear to work for client-side multipart requests. So programs that need to do that use the Apache HTTP client.
• The BulkUploadClient is an exception, in that it does not extend BaseClient. Instead, it does minimal error handling, while duplicating some of the code. The result is less well-factored and perhaps somewhat less robust, but possibly more easily read and understood.

Configuring the BaseClient

Edit the BaseClient code to change the values for the following variables:

baseUrl

The URL that takes you to the platform REST APIs, without a final slash.
For example: http://yourPlatform.com/networking/rest

username

Your username, or the name of the user you'll be logging in as.

password

The password you need to log in.

Note: The plan is to read those values from a file, one fine day.

Primary Methods

login()

Logs into the platform. Returns a String containing the session ID. Learn more: REST API:login Resource

logout()

Logs out of the platform. Learn more: REST API:logout Resource

main()

Calls the login method, echoes the session ID, and logs out. It's worth showing in it's entirety, because it's small.

<syntaxhighlight lang="java" enclose="div">

 public static void main(String args[])
 {
   BaseClient client = new BaseClient();
   String sessionId = client.login();
   System.out.println("SessionId is: " + sessionId);  
   client.logout();
 }

</syntaxhighlight>

In practice, the main() method for a subclass will tend to look something like this:

<syntaxhighlight lang="java" enclose="div">

 public static void main(String args[])
 {
   SubclassClient client = new SubclassClient();
   String sessionId = client.login();
   System.out.println("SessionId is: " + sessionId);

   try {
      // Access a resource
      Resource resource = getResource(downloadPackageUrl);
      resource.header("Cookie", "JSESSIONID=" + sessionId);
       
      // Make calls on the resource
       ...
   }    
   catch (ClientWebException webException)
   {
       echoResponse(webException);
   }
   catch (Exception e)
   {
       System.out.println(e.getMessage());
       e.printStackTrace();
   }
   finally
   {
       client.logout();
   }
 }

</syntaxhighlight>

Utility Methods

These methods are generally used by subclasses. Many of them delegate the actual work to methods in the BaseUtil class.

getValue(String xpath_expr, String xml)

Delegates to the BaseUtil xpath_result method to get a value from an XML string. Generally used to get the /platform/message/status from a response.

getResource(String uri)

Returns the Resource object for a URI or URL, using the RestClient object created by logging in.

echoResponse(InputStream xml_in)

Delegates to the BaseUtil prettyPrint method to display response XML in nicely-formatted form.

echoResponse(String xml)

Version that pretty prints an XML string.

echoResponse(ClientWebException e)

Version that pretty prints the response contained in an Apache ClientWebException object. (Fixes a problem in the HTML returned by Apache Tomcat. Does not fix other errors.)

echoStatus(int status, String xml)

Displays the Http status code that accompanies a response, as well as the platform message code and associated description contained in the response.

statusMessage(int status)

Used by the echoStatus method to provide the useful interpretations of Http status codes. Returns a descriptive string for a status code that is somewhat customized for the platform.