publishQueue
publishQueue
The publish queue records the publish, unpublish, and delete activities on the entries and assets of a stack, along with Release deployments, with their time, user, environment, and status. Use this class to
- list the activities in the publish queue
- read one activity
- cancel a scheduled publish, unpublish, or Release deployment
stack.publishQueue() and stack.publishQueue("<JOB_UID>") return a PublishQueue. PublishQueue has no public constructor.
| Name | Type | Description |
|---|---|---|
| publishQueueUid | String | UID of one publish queue activity. Pass it to stack.publishQueue() for methods that act on one activity. |
addHeader
addHeader adds one request header to this publish queue object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header. |
| value (required) | String | Value of the header. |
Returns: PublishQueue. The same publish queue object, for chaining.
Validation
- There is no client-side validation. A null key or value does not throw here.
- execute() throws IllegalArgumentException for a null key or value, because Retrofit rejects null entries in a header map.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addHeader stores the header in the header map of this object and sends nothing.
- A later call with the same name replaces the value.
- The header goes on every request of this publish queue object: find, fetchActivity, and cancelScheduledAction, and stays there for every later request.
Example
Basic usage: send the api_version header
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class PublishQueueApiVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.publishQueue()
.addHeader("api_version", "3.2")
.find()
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeaders
addHeaders adds every entry of a map to the request headers of this publish queue object.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names mapped to their values. |
Returns: PublishQueue. The same publish queue object, for chaining.
Validation
- Throws NullPointerException if headers is null, because addHeaders copies every entry of the map.
- execute() throws IllegalArgumentException for a null key or value in the map, because Retrofit rejects null entries in a header map.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addHeaders copies the entries into the header map of this object and sends nothing.
- An entry replaces a header with the same name.
- The headers go on every request of this publish queue object: find, fetchActivity, and cancelScheduledAction, and stay there for every later request.
Example
Basic usage: read the publish queue of a branch
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class PublishQueueOnBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, String> headers = new HashMap<>();
headers.put("api_version", "3.2");
headers.put("branch", "<BRANCH>");
Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.publishQueue()
.addHeaders(headers)
.find()
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParam
addParam adds one query parameter to this publish queue object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | Object | Value of the query parameter, sent as its string form. |
Returns: PublishQueue. The same publish queue object, for chaining.
Validation
- There is no client-side validation. A null key or value does not throw here.
- execute() throws IllegalArgumentException for a null key or value, because Retrofit rejects null entries in a query map.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addParam stores the pair in the query parameter map of this object and sends nothing.
- A later call with the same key replaces the value.
- The parameter goes on every request of this publish queue object: find, fetchActivity, and cancelScheduledAction.
- The parameter stays on the object for every later request. Remove it with removeParam.
Example
Basic usage: include the branch in the publish queue response
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class PublishQueueWithBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.publishQueue()
.addHeader("api_version", "3.2")
.addParam("include_branch", true)
.find()
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParams
addParams adds every entry of a map to the query parameters of this publish queue object.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Query parameter names mapped to their values. |
Returns: PublishQueue. The same publish queue object, for chaining.
Validation
- Throws NullPointerException if params is null, because addParams copies every entry of the map.
- execute() throws IllegalArgumentException for a null key or value in the map, because Retrofit rejects null entries in a query map.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addParams copies the entries into the query parameter map of this object and sends nothing.
- An entry replaces a parameter with the same name.
- The parameters go on every request of this publish queue object: find, fetchActivity, and cancelScheduledAction.
- The parameters stay on the object for every later request. Remove one with removeParam.
Example
Basic usage: add query parameters from a map
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class PublishQueueWithParamMap {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, Object> params = new HashMap<>();
params.put("include_branch", true);
Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.publishQueue()
.addHeader("api_version", "3.2")
.addParams(params)
.find()
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}cancelScheduledAction
cancelScheduledAction builds the request that cancels a scheduled publish, a scheduled unpublish, or a scheduled Release deployment.
Returns: Call<ResponseBody>. The request that cancels the scheduled action, sent when you call execute().
Validation
- Throws IllegalAccessError if the object has no publish queue UID or an empty one, as on stack.publishQueue(), because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Cancel scheduled action request (GET /publish-queue/{publish_queue_uid}/unschedule) with the headers and query parameters of this object.
- The API reference marks both the authtoken and the authorization headers as required for this request, and api_version: 3.2. Log in with client.login() so the SDK adds the authtoken, and build the stack with the management token.
- Pass the UID of the scheduled activity, which find returns.
Example
Basic usage: cancel a scheduled publish
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class CancelScheduledPublish {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
// The API reference lists the authtoken as required for this request
client.login("<EMAIL>", "<PASSWORD>");
Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.publishQueue("<JOB_UID>")
.addHeader("api_version", "3.2")
.cancelScheduledAction()
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}fetchActivity
fetchActivity builds the request that reads one publish, unpublish, delete, or Release deployment activity by the UID you passed to stack.publishQueue().
Returns: Call<ResponseBody>. The request for the publish queue activity, sent when you call execute().
Validation
- Throws IllegalAccessError if the object has no publish queue UID or an empty one, as on stack.publishQueue(), because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get publish queue activity request (GET /publish-queue/{publish_queue_uid}) with the headers and query parameters of this object.
- The API reference marks the api_version header as required. Add it with addHeader.
- Read the activity UIDs from the response of find.
- The API returns activities from the last 30 days only.
Example
Basic usage: read one activity
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ReadPublishQueueActivity {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.publishQueue("<JOB_UID>")
.addHeader("api_version", "3.2")
.fetchActivity()
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Error handling: a publish queue object without a UID
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.PublishQueue;
public class ReadActivityWithoutUid {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
PublishQueue queue = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").publishQueue();
try {
queue.fetchActivity();
} catch (IllegalAccessError e) {
// Fires because publishQueue() holds no UID. IllegalAccessError is an Error, not an Exception.
System.out.println("Pass an activity UID to stack.publishQueue(): " + e.getMessage());
}
}
}find
find builds the request that lists the publish, unpublish, and delete activities of the stack, with the Release deployments.
Returns: Call<ResponseBody>. The request for the publish queue, sent when you call execute().
Validation
- There is no client-side validation. find works with or without a UID passed to stack.publishQueue(), and ignores the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get publish queue request (GET /publish-queue) with the headers and query parameters of this object.
- The API reference marks the api_version header as required. Add it with addHeader.
- The API reference lists include_branch as a query parameter. Add it with addParam.
- The API returns the activities of the last 90 days.
Example
Basic usage: read the publish queue
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ReadPublishQueue {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.publishQueue()
.addHeader("api_version", "3.2")
.find()
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All options: include the branch of each activity
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ReadPublishQueueWithBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.publishQueue()
.addHeader("api_version", "3.2")
.addParam("include_branch", true)
.find()
.execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}removeParam
removeParam removes one query parameter from this publish queue object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter to remove. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. A key that is not in the map, or null, changes nothing and does not throw.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- removeParam deletes the key from the query parameter map of this object and sends nothing.
- removeParam returns nothing, so it cannot sit in a chain. Call it as a separate statement.
- removeParam leaves the headers of the object unchanged.
Example
Basic usage: remove a parameter before the next request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.PublishQueue;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemovePublishQueueParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
PublishQueue queue = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").publishQueue();
queue.addHeader("api_version", "3.2");
queue.addParam("include_branch", true);
// The next request sends no query parameters
queue.removeParam("include_branch");
Response<ResponseBody> response = queue.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}