Java 用戶端檔案庫

Java™ 用戶端檔案庫提供從與 Java 相容的程式設計語言及執行時期對 REST API 的存取。

用戶端檔案庫為一般作業提供了流暢 API 以及與 JavaBeans 相容的 IBM® UrbanCode Release 物件模型表示法。用戶端檔案庫依賴於 REST API。如需受支援之作業的相關資訊，請參閱 REST API 使用慣例。

Java 用戶端檔案庫包裝在 Java 保存檔中。此檔案位於伺服器上的 server_installation/plugins/util/ucr-plugin-util.jar 位置。您還可以透過按一下說明 > 工具，從伺服器下載該檔案。

相依關係

Java 用戶端檔案庫需要 Groovy 語言執行時期，並且已針對 Groovy 2.1.9 版進行測試。用戶端程式必須確保在 Java 類別路徑上提供了 Groovy 執行時期 lib 目錄。

用戶端 Factory 類別

與 Java 用戶端檔案庫進行互動的起始點是類別 com.urbancode.release.rest.framework.Clients。此類別包括 static 方法，該方法用於與伺服器建立 HTTP 階段作業和建立元素。

建立階段作業

如果要使用 REST API 開始與 Java 用戶端檔案庫進行互動，請建立 HTTP 階段作業。Clients 類別上有兩種方法可用於此目的。

第一個變異使用使用者名稱及密碼組合來登入伺服器：

public static void loginAs(String baseURL, 
  String username, 
  String password)

例如，下列指令將以預設管理者帳戶身分登入：

Clients.loginAs("http://ucrserver.example.com:8080/", "admin", "admin")

第二個變異使用鑑別記號：

public static void loginWithToken(String baseURL, String token)

此變異通常用於外掛程式。

用戶端模型

每一種元素類型在用戶端檔案庫中都具有對應的用戶端模型類別。這些類別會延伸類別 com.urbancode.release.rest.framework.ClientEntity。例如，類別 com.urbancode.release.rest.models.Application 代表應用程式。與每一種元素類型相關的作業都在用戶端模型類別上具有對應的實例方法。

Clients 類別包含用於建立每一種用戶端模型類別實例的靜態 Factory 方法。例如，如果要建立 Application 用戶端模型類別的實例，請呼叫下列方法：

Clients.application()

註：在大多數情況下，對於 Java 用戶端程式，請使用 Clients 類別之所有方法的靜態匯入。下列範例假定下列靜態匯入位於 Java 程式檔的頂端。

import static com.urbancode.release.rest.framework.Clients.*;

基本作業

每一個基本的建立、讀取、更新及刪除作業都具有 ClientEntity 的對應實例方法。在下面的方法簽章中，類型參數 T 代表所使用的特定 ClientEntity 子類別，例如 Application 類別。

Java 用戶端檔案庫基於開放程式碼 REST 保證的檔案庫，並且作為部分方法簽章中之傳回類型而出現的 Response 類別是類別 com.jayway.restassured.response.Response。

大量作業

下列方法同時對多個元素執行作業。它們對應於對 REST API 的最上層 URL（例如 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)

單一元素作業

下列方法對單一元素執行作業。它們對應於對 REST API 的單一值 URL（例如 http://base_url/releases/00000000-0000-0000-0000-000000000036/）執行的作業。（post() 作業是一個例外，因為它對單一元素執行作業，但卻對應於對最上層 URL 的要求。）這些方法沒有參數。將使用用戶端模型實例（根據其來呼叫方法）的 id 內容，來建構向其傳送要求的完整單一值 URL。

public T post()
public T get()
public Response put()
public Response delete()

為了方便起見，額外提供了一種 save() 方法。此方法會執行 put() 或 post()，視是否將用戶端模型的 id 內容設為非空值而定。這樣，您可以使用相同的方法來要求新元素或對現有元素進行更新，視該元素是否已經存在而定。

public T save()

用戶端模型內容

REST API 作業的 JSON 要求或回應內文會自動轉換為適當用戶端模型類別的實例，反之亦然。在大多數情況下，會讓元素之 JSON 表示法的內容符合具有相符名稱的 Bean 內容。有幾個例外，例如 Java 內容 Application.applicationEnvironments，該內容對應於 JSON 內容 targets。

Java 用戶端檔案庫提供了兩種替代 API 樣式，以使用內容：其中一個遵循 JavaBeans 使用慣例，另一個遵循非標準流暢樣式。這兩種樣式都提供了對等功能，並且可在相同的程式中一起使用。下列範例顯示如何透過每一種樣式與應用程式用戶端模型進行互動。

JavaBeans

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;

鍵值內容

您可以使用公用欄位 propertyValues 來存取和修改支援動態鍵值內容的元素類型。您還可以在流暢樣式或 JavaBeans 樣式中使用下列方法：

public T property(String key, String value)

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

空值

如 REST API 使用慣例中所述，從 JSON 輸入中省略的內容不會變更。如果要清除現有值，則必須指定 JSON 空值。用戶端模型透過類似的方式進行工作：如果不呼叫某個內容的 setter，或者如果直接在公用欄位上設定了空值，則將從 JSON 輸出中省略該內容。如果要清除某個內容的現有值，請使用 setter 方法為該內容指定一個 Java 空值。

查詢參數

為了控制用戶端檔案庫所產生之 HTTP 要求的查詢參數，每一個用戶端模型實例都具有 com.urbancode.release.rest.framework.QueryParams 的相關聯實例。此類別提供了實例方法，以將任意查詢參數新增至對應用戶端模型實例所建立的 HTTP 要求。該檔案庫還包括用於控制一般參數（例如 format 參數）的便捷方法。使用 QueryParams.when() 方法來存取對應的用戶端模型。使用 ClientEntity.newQuery() 方法來移除所有查詢參數。此外，ClientEntity 為 QueryParams 類別的每一種方法提供了轉遞方法，以進一步減少流暢樣式 API 中的方法呼叫次數。

例如，如果要使用 detail 格式來擷取版本範例，請使用下列流暢要求：

Release sampleRelease = 
  release().id("00000000-0000-0000-0000-000000000036").
  format("detail").when().get();

因為 list、detail 和 name 格式是常用格式，所以提供了便捷方法。下列程式碼將使用每一種常用格式來擷取版本範例的 3 份副本：

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();

分頁

支援在 REST API 中分頁的元素類型，也支援使用下列方法在用戶端檔案庫中進行分頁：

getPage(int start, int end)

start 和 end 參數從 0 開始的參數，並且是內含式參數。例如，如果至少存在兩個應用程式，則下列要求將依照預設排序來擷取前兩個應用程式：

Application[] firstTwoApps = application().getPage(0,1);

排序

如果要指定 getAll() 及 getPage() 方法之結果的排序，請使用下列其中一種方法：

QueryParams.orderBy(String property)
orderBy(String property, boolean asc)

單一參數表單按指定的內容以升序順序進行排序，如下列範例中所示：

Change[] sortedChanges = change().orderBy("release.name").when().getAll();

過濾

如果要過濾 getAll() 或 getPage() 方法的結果，請使用下列其中一種方法：

QueryParams.filter(String field, FilterClass filterClass, 
  FilterType type, Object... values)

QueryParams.like(String field, String like)

QueryParams.equals(String field, FilterClass filterClass, String match)

例如，要尋找特定時間戳記後建立的所有版本，請使用下列查詢：

Release[] createdAfter = release()
  .filter("dateCreated", FilterClass.LONG, FilterType.GREATER_THAN, timestamp)
  .orderBy("dateCreated")
  .when().getAll();

便捷方法及遠端方法

除了基本作業外，特定的用戶端模型類別還提供了其他方法，以讓與元素的互動變得更便捷。這些作業中的部分作業只需要本端資料操作，其他作業會產生額外的 HTTP 要求。例如，Application 用戶端模型類別提供下列方法，以與 totalChanges 內容進行互動。這是本端作業。

public int getChangeCount(Status status, ChangeType type)

同一 Application 類別還提供了下列遠端作業，以在一個指令中將多個變更與一個應用程式建立關聯：

public Response updateChanges(Change... changes)

如需可用遠端作業的更多詳細資料，請參閱 REST 指令。

意見