The Java API is thoroughly documented in the JavaDocs that are included in the client download. Usage of the Java API requires that hqapi1.jar as well as all libraries in the lib directory be included within the classpath.
The entry point to the Java API is the HQApi class. The constructor for this class takes a series of arguments that describes the connection to be made to HQ. From the HQApi object, APIs to all HQ's subsystems may be accessed.
All APIs return response Objects that extend the Response class. This class provides the caller information on the success or failure of the API call via the getStatus() method. This can return one of ResponseStatus.SUCCESS or ResponseStatus.FAILURE. On the case of failure, additional information on the reason for the failure may be obtained through getError(). See the JavaDocs on the Response class for more information.
In general API calls will return 1 of 3 different types of responses:
|StatusResponse||Think of this as a void method signature. The StatusResponse simply carries with it the base Response information on the success or failure of the API call.|
|Single Object Response||These methods return an object similar to the StatusResponse, but it also contains a single entity. Examples of this include UserResponse and ResourceResponse.|
|Multiple Object Response||Again, this is similar to the single object response, but instead of a single object, a List of objects is returned. Examples of this include UsersResponse and ResourcesResponse.|
There are no formal code samples included in the client download, however the test suite and tools packages provide many examples of API usage.