REST API:BaseClient

REST API:BaseClient

From LongJump Support Wiki

REST API:BaseClient
Jump to: navigation, search

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.

File:thumbsup.gif

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

Contents

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.

File:notepad.png

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, and logs out. In between those operations is where you'll utilize other resources:
  public static void main(String args[])
  {
    BaseClient client = new BaseClient();
    String sessionId = client.login();
    // Do something here
    client.logout();
  }
The actual main method in the login method illustrates the basic pattern by retrieving the current user's information:
  public static void main(String args[])
  {
    BaseClient client = new BaseClient();
    String cookieString = client.login();                      
    System.out.println("Session cookie:\n  " + cookieString);
    try {    
       // Utilize a resource
       String resourceUrl = baseUrl + "/user/info";  // Current user info
       Resource resource = client.getResource(resourceUrl);
       resource.header("Cookie", cookieString);
       resource.accept("application/xml");              // or application/json
       ClientResponse response = resource.get();        // Fetch data
       // ClientResponse response = resource.post(xml); // Add data
       // ClientResponse response = resource.put(xml);  // Update data

       // Inspect the response
       String responseXml = response.getEntity(String.class);
       echoResponse(responseXml);        
    }    
    catch (ClientWebException webException)
    {
        echoResponse(webException);
    }
    catch (Exception e)
    {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
    finally
    {
        client.logout();
    }
  }

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.
Personal tools