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 .
DependenciesThe 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 classThe 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 sessionTo 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.
For example, the following command logs in as the default administrator account:
public static void loginAs(String baseURL, String username, String password)
Clients.loginAs("http://ucrserver.example.com:8080/", "admin", "admin")
This variation is typically used for plug-ins.
public static void loginWithToken(String baseURL, String token)
Client modelsEach 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.
import static com.urbancode.release.rest.framework.Clients.*;
Basic operationsEach 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 operationsThe following methods operate on multiple elements simultaneously. They correspond to operations on the top-level URLs of the REST API, such as
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 operationsThe following methods operate on a single element. They correspond to the operations on single-value URLs of the REST API, such as
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
idproperty of the client model instance upon which the method is called.
public T post() public T get() public Response put() public Response delete()
save()method is provided for convenience. This method runs either a
post(), depending on whether the
idproperty 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 propertiesThe 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
Application myApp = new Application(); myApp.setName("My New Application"); myApp.setTeams(Team.SAMPLE_TEAM); myApp = myApp.save(); String savedName = myApp.getName();
Application myApp = application().name("My New Application"). teams(Team.SAMPLE_TEAM).save(); String savedName = myApp.name;
Key-value propertiesYou can use the public field
propertyValuesto 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 valuesAs 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 parametersTo 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
formatparameter. 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.
detailformat, use the following fluent request:
Release sampleRelease = release().id("00000000-0000-0000-0000-000000000036"). format("detail").when().get();
nameformats 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();
PaginationElement types that support pagination in the REST API also support pagination in the client library with following method:
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:
getPage(int start, int end)
Application firstTwoApps = application().getPage(0,1);
SortingTo specify the sort order of results for the getAll() and getPage() methods, use one of the following methods:
orderBy(String property, boolean asc)
Change sortedChanges = change().orderBy("release.name").when().getAll();
FilteringTo 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)
For example, to find all releases that were created after a specific timestamp, use the following query:
QueryParams.equals(String field, FilterClass filterClass, String match)
Release createdAfter = release() .filter("dateCreated", FilterClass.LONG, FilterType.GREATER_THAN, timestamp) .orderBy("dateCreated") .when().getAll();
Convenience methods and remote methodsIn 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
totalChangesproperty. This is a local operation.
The same Application class also provides the following remote operation to associate multiple changes with an application in one command:
public int getChangeCount(Status status, ChangeType type)
For more details about available remote operations, see REST commands.
public Response updateChanges(Change... changes)