Java client library
The Java™ client library provides access to the REST API from Java compatible programming languages and runtimes.
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 ashttp://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 ashttp://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 propertyApplication.applicationEnvironments
,
which corresponds to the JSON property targets
.- 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 fieldpropertyValues
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 theformat
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)
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 thetotalChanges
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.