Java client library

The Java™ client library provides access to the REST API from Java compatible programming languages and runtimes.

The client library provides a fluent API for common tasks and a JavaBeans™ compatible representation of the IBM® UrbanCode™ Release object model. The client library relies on the REST API. For more information about the supported operations, see REST API conventions.

The Java client library is packaged in a Java archive file. This file is available on the server at the location server_installation/plugins/util/ucr-plugin-util.jar. You can also download the file from the server by clicking Help > Tools.


The Java client library requires the Groovy language run time and was tested with Groovy version 2.1.9. Client programs must ensure that the Groovy runtime lib directory is available on the Java class path.

Clients factory class

The starting point for interactions with the Java client library is the class This class includes static methods that establish an HTTP session with the server and create elements.

Establishing a session

To begin interactions with the REST API with the Java client library, establish an HTTP session. There are two methods on the Clients class that can be used for this purpose.
The first variation uses a user name and password combination to log in to the server:
public static void loginAs(String baseURL, 
  String username, 
  String password)
For example, the following command logs in as the default administrator account:
Clients.loginAs("", "admin", "admin")
The second variation uses an authentication token:
public static void loginWithToken(String baseURL, String token)
This variation is typically used for plug-ins.

Client models

Each element type has a corresponding client model class in the client library. These classes extend the class For example, the class represents applications. Operations that are related to each element type have corresponding instance methods on the client model class.
The Clients class contains a static factory method that creates instances of each client model type. For example, to create an instance of the Application client model class, call the following method
Note: In most cases, for Java client programs, use a static import of all methods of the Clients class. The following examples assume that the following static import is at the top of the Java program file.
import static*;

Basic operations

Each of the basic create, read, update, and delete operations has a corresponding instance method of ClientEntity. In the method signatures below, the type parameter T represents the specific ClientEntity subclass being used, such as the Application class.

The Java client library is based on the open source REST-assured library, and the Response class that appears as the return type in some of the method signatures is the class com.jayway.restassured.response.Response.

Bulk operations

The following methods operate on multiple elements simultaneously. They correspond to operations on the top-level URLs of the REST API, such as http://base_url/releases/.
public T[] post(T... toCreate) 
public T[] post(List<T> toCreate) 
public T[] getAll() 
public T[] getPage(int start, int end) 
public Response put(T... toUpdate) 
public Response put(List<T> toUpdate) 
public Response delete(T... toDelete) 
public Response delete(List<T> toDelete)

Single-element operations

The following methods operate on a single element. They correspond to the operations on single-value URLs of the REST API, such as http://base_url/releases/00000000-0000-0000-0000-000000000036/. (The post() operation is an exception, since it operates on a single element but corresponds to a request to a top-level URL.) These methods have no parameters. The full single-value URL to which requests are made is constructed with the id property of the client model instance upon which the method is called.
public T post()
public T get()
public Response put()
public Response delete()
An additional save() method is provided for convenience. This method runs either a put() or a post(), depending on whether the id property of the client model is set to a non-null value. In this way, you can use the same method to request either a new element or an update to an existing element, depending on whether the element already exists.
public T save()

Client model properties

The JSON request or response body for REST API operations is automatically converted into instances of the appropriate client model class and vice versa. In most cases, properties of the JSON representation of an element are matched with bean properties with matching names. There are a few exceptions, such as the Java property Application.applicationEnvironments, which corresponds to the JSON property targets.
The Java client library provides two alternative API styles for working with properties: one following JavaBeans conventions and another following a non-standard fluent style. Both styles provide equivalent functionality and can be used together in the same program. The following example shows how to interact with the application client model with each style.
Application myApp = new Application();
myApp.setName("My New Application");
myApp =;

String savedName = myApp.getName();
Application myApp = application().name("My New Application").

String savedName =;

Key-value properties

You can use the public field propertyValues to access and modify element types that support dynamic key-value properties. You can also use the following methods in fluent style or JavaBeans style:
public T property(String key, String value)

public T setProperty(String key, String value)
public String getProperty(String key)

Null values

As described in REST API conventions, properties that are omitted from JSON input are not changed. To clear an existing value, you must specify a JSON null value. The client models work in a similar way: If you do not call the setter for a property, or if a null value is set directly on the public field, the property is omitted from JSON output. To clear an existing value for a property, specify a Java null value for that property by using a setter method.

Query parameters

To control the query parameters for the HTTP requests generated by the client library, each client model instance has an associated instance of This class provides instance methods to add arbitrary query parameters to HTTP requests that are created by the corresponding client model instance. The library also includes convenience methods that control common parameters, such as the format parameter. Use the QueryParams.when() method to access the corresponding client model. Use the ClientEntity.newQuery() method to remove all query parameters. In addition, ClientEntity provides forwarding methods for each method of the QueryParams class, to further reduce the number of method calls in the fluent style API.
For example, to retrieve the sample release using the detail format, use the following fluent request:
Release sampleRelease = 
Because the list, detail, and name formats are commonly used, convenience methods are provided. The following code retrieves three copies of the sample release, using each of the common formats:
Release listFormatRelease = 

Release detailFormatRelease = 

Release nameFormatRelease = 


Element types that support pagination in the REST API also support pagination in the client library with following method:
getPage(int start, int end)
The start and end parameters are zero-based and inclusive. For example, if at least two applications exist, the following request retrieves the first two applications in the default sort order:
Application[] firstTwoApps = application().getPage(0,1);


To specify the sort order of results for the getAll() and getPage() methods, use one of the following methods:
  • QueryParams.orderBy(String property)
  • orderBy(String property, boolean asc)
The single-parameter form sorts by a specified property in ascending order, as in the following example:
Change[] sortedChanges = change().orderBy("").when().getAll();


To filter the results of the getAll() or getPage() methods, use one of the following methods:
QueryParams.filter(String field, FilterClass filterClass, 
  FilterType type, Object... values) field, String like)
QueryParams.equals(String field, FilterClass filterClass, String match)
For example, to find all releases that were created after a specific timestamp, use the following query:
Release[] createdAfter = release()
  .filter("dateCreated", FilterClass.LONG, FilterType.GREATER_THAN, timestamp)

Convenience methods and remote methods

In addition to the basic operations, specific client model classes provide additional methods to make interacting with the elements more convenient. Some of these operations require only local data manipulation, and others produce additional HTTP requests. For example, the Application client model class provides the following method to interact with the totalChanges property. This is a local operation.
public int getChangeCount(Status status, ChangeType type)
The same Application class also provides the following remote operation to associate multiple changes with an application in one command:
public Response updateChanges(Change... changes)
For more details about available remote operations, see REST commands.