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 .
Dependencies
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 com.urbancode.release.rest.framework.Clients.
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("http://ucrserver.example.com:8080/", "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
com.urbancode.release.rest.framework.ClientEntity.
For example, the class
com.urbancode.release.rest.models.Application 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
Clients.application()
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 com.urbancode.release.rest.framework.Clients.*;
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.
- JavaBeans
Application myApp = new Application();
myApp.setName("My New Application");
myApp.setTeams(Team.SAMPLE_TEAM);
myApp = myApp.save();
String savedName = myApp.getName();
- Fluent
Application myApp = application().name("My New Application").
teams(Team.SAMPLE_TEAM).save();
String savedName = myApp.name;
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
com.urbancode.release.rest.framework.QueryParams.
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 =
release().id("00000000-0000-0000-0000-000000000036").
format("detail").when().get();
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().id("00000000-0000-0000-0000-000000000036")
.listFormat().when().get();
Release detailFormatRelease =
release().id("00000000-0000-0000-0000-000000000036").
detailFormat().when().get();
Release nameFormatRelease =
release().id("00000000-0000-0000-0000-000000000036").
nameFormat().when().get();
Pagination
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);
Sorting
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("release.name").when().getAll();
Filtering
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)
QueryParams.like(String 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)
.orderBy("dateCreated")
.when().getAll();
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.