publishQueue

View as Markdown

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.

NameTypeDescription
publishQueueUidStringUID 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.

NameTypeDescription
key (required)String

Name of the header.

Default: Not applicable
value (required)String

Value of the header.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap<String, String>

Header names mapped to their values.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)Object

Value of the query parameter, sent as its string form.

Default: Not applicable

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.

NameTypeDescription
params (required)HashMap<String, Object>

Query parameter names mapped to their values.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

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