Is AI recommending you? Ask Contentstack Canoe for free
CS-log-dark.svg

Entry

View as Markdown

Entry

An entry is one piece of content created from a content type. Use this class to

  • read one published entry by its UID
  • choose the locale, variants, fields, and references that the response carries
  • read the fields of the entry as Java types
  • reach the groups, assets, and referenced entries inside the entry

stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>") returns an Entry for a request. The two calls take one argument each:

NameTypeDescription
contentTypeUidStringUID of the content type. Pass it to stack.contentType().
entryUidStringUID of the entry. Pass it to entry().

Entry has no public constructor. A Query result also hands you Entry objects that already hold their data, and so does the getAllEntries method.

addParam

addParam adds a query parameter that the SDK has no method for to the entry request.

NameTypeDescription
key (required)String

Query parameter name.

Default: Not applicable
value (required)String

Query parameter value.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • Throws NullPointerException if key is null.
  • A null value deletes a parameter that an earlier call set under the same key.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. addParam records the parameter and makes no request. fetch sends it to Get a single entry.
  • fetch adds the key and value to the URL without URL-encoding them, so an & or = in the value splits it into separate parameters.
  • A second call with the same key replaces the value. It also replaces a value that another method set under that key, such as locale from setLocale.
  • The parameter stays on the entry for every later fetch.

Example

Basic usage: resolve the taxonomy terms of the entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryWithParam {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.addParam("include_taxonomy_terms", "true");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getJSONArray("taxonomies"));
            }
        });
    }
}

assetFields

assetFields asks the API for extra field groups on the assets in the entry.

NameTypeDescription
fields (required)String...

Asset field groups to add, such as visual_markups.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • A call with no arguments or with null changes nothing.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. assetFields records each value under the asset_fields[] query parameter and makes no request. fetch sends one parameter per value, as Get a single entry describes.
  • A second call replaces the earlier list.
  • The list stays on the entry for every later fetch.

Example

Basic usage: return the visual markups of each asset

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import org.json.JSONObject;

public class FetchEntryAssetFields {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.assetFields("visual_markups");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                JSONObject image = entry.getJSONObject("main_image");
                if (image != null) {
                    System.out.println(image.optJSONArray("visual_markups"));
                }
            }
        });
    }
}

configure

configure fills the entry from a JSON object you already hold, so the getters read it without a request.

NameTypeDescription
jsonObject (required)JSONObject

Entry JSON, or a response body with an entry key.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation of the JSON content.
  • Throws NullPointerException if jsonObject is null, because configure reads keys from it.

Behavior

  • Client-side only. configure makes no request.
  • When the object has an entry key, configure reads the object under that key. Otherwise it reads the object itself. You can pass a whole Get a single entry response body or the entry alone.
  • configure stores the object as the entry JSON, which toJSON returns and every field getter reads. It keeps a reference, not a copy, so a later change to your JSONObject shows in the getters.
  • It sets the values of getUid, getTitle, getURL, and getLocale from the uid, title, url, and locale keys. A key that the object lacks makes that getter return null.
  • IMPORTANT: configure replaces the entry UID with the uid value of the JSON. JSON without a uid key leaves the entry with no UID, and a later fetch then throws NullPointerException.

Example

Basic usage: read JSON you already hold through the getters

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Stack;

import org.json.JSONObject;

public class ConfigureEntry {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        // JSON you already hold, for example from a cache
        JSONObject json = new JSONObject();
        json.put("uid", "<ENTRY_UID>");
        json.put("title", "Leather Wallet");
        json.put("price", 49.5);

        entry.configure(json);
        System.out.println(entry.getTitle() + " costs " + entry.getDouble("price"));
    }
}

Response body: pass a body that wraps the entry in an entry key

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Stack;

import org.json.JSONObject;

public class ConfigureFromResponseBody {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

        String body = "{\"entry\": {\"uid\": \"<ENTRY_UID>\", \"title\": \"Leather Wallet\", \"locale\": \"<LOCALE>\"}}";
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>").configure(new JSONObject(body));

        // configure reads the object under the entry key
        System.out.println(entry.getUid() + " " + entry.getLocale());
    }
}

except

except leaves the listed top-level fields out of the entry that fetch returns.

NameTypeDescription
fieldUid (required)String[]

Field UIDs to leave out.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • An empty array changes nothing.
  • Throws NullPointerException if fieldUid is null.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. except records each UID under the except[BASE][] query parameter and makes no request. fetch sends one parameter per field, as the Exclude operator describes.
  • A second call adds to the list.
  • The list applies to the next fetch only. fetch clears it after it builds the request, so call except again before each fetch.
  • Write a field inside a Group field as a dotted path, such as details.material.
  • To leave out fields of a referenced entry, use the exceptWithReferenceUid method.

Example

Basic usage: leave two fields out of the response

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryExcept {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.except(new String[]{"gallery", "description"});

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.toJSON().has("gallery"));
            }
        });
    }
}

Group field: leave out one field inside a group

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryExceptGroupField {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.except(new String[]{"details.material"});

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println(entry.getTitle());
            }
        });
    }
}

exceptWithReferenceUid

exceptWithReferenceUid includes the entries of a reference field and leaves the listed fields out of each.

NameTypeDescription
fieldUid (required)List<String>

Fields to leave out of each referenced entry.

Default: Not applicable
referenceFieldUid (required)String

Reference field UID to include.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • Throws NullPointerException if fieldUid or referenceFieldUid is null.
  • An empty fieldUid list includes the referenced entries with all their fields.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. exceptWithReferenceUid records each field under the except[<referenceFieldUid>][] query parameter, and calls includeReference for referenceFieldUid. It makes no request. The Exclude operator describes the parameter.
  • You do not need a separate includeReference call for the same field. Adding one sends the include[] value twice.
  • A second call for the same reference field replaces its list. A call for another reference field adds that field.
  • The except lists apply to the next fetch only, and fetch clears them. The include[] value stays on the entry for later fetches.
  • Combine it with the except method to leave out fields of the entry itself.

Example

Basic usage: leave two fields out of each referenced entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.util.Arrays;

public class FetchReferenceExcept {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.exceptWithReferenceUid(Arrays.asList("gallery", "description"), "related_products");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry product : entry.getAllEntries("related_products", "<CONTENT_TYPE_UID>")) {
                    System.out.println(product.getString("title"));
                }
            }
        });
    }
}

fetch

fetch reads one published entry by its UID and fills this Entry with the result.

NameTypeDescription
callback (required)EntryResultCallBack

Receives the result. See Callbacks.

Default: Not applicable

Returns: void. The result arrives in the callback.

Validation

  • Throws NullPointerException if the entry has no UID, as after entry(null), because fetch builds the request URL from the UID.
  • An empty UID does not throw. fetch logs the problem and sends the request anyway, and the callback receives an Error.
  • fetch does not throw for an API rejection or a network failure. It calls onCompletion with an Error:
    • getErrorCode() holds the error_code of the API, not the HTTP status.
    • getErrorMessage() holds the message of the API.
    • A timeout or network failure gives the code 0.
  • When your own onCompletion code throws org.json.JSONException, the SDK catches it and calls onCompletion a second time with an Error that reports an invalid JSON response. Other exceptions from your code leave fetch and reach your caller.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • One call sends one Get a single entry request (GET /content_types/{content_type_uid}/entries/{entry_uid}). It also sends the environment of the stack as a query parameter, and every option that you chained.
  • On success, fetch fills this object and calls onCompletion with a null error. Read the entry through its getters, such as getTitle and getString.
  • fetch keeps only the entry object of the response body. Keys that the API returns beside it do not reach your code.
  • On failure, the entry keeps the data it held before the call.
  • The lists from only, except, onlyWithReferenceUid, and exceptWithReferenceUid apply to this request only. Every other option stays on the entry for later fetches.
  • Live preview can replace the request. When the livePreviewQuery method of Stack loaded a preview entry with this UID and content type, fetch fills the entry from that preview data and sends no request.

Limitations

  • Does not read an earlier version of the entry. The Delivery API returns the latest published version, as Get a single entry states. Use the Content Management API for versions.
  • Does not read several entries. Use the Query class instead.

Example

Basic usage: read one entry by UID

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntry {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle());
            }
        });
    }
}

All options: read a localized entry with references and fewer fields

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryWithOptions {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>")
                .setLocale("<LOCALE>")
                .includeFallback()
                .includeReference("related_products")
                .except(new String[]{"gallery"});

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println(entry.getTitle() + " (" + entry.getLocale() + ")");
                for (Entry product : entry.getAllEntries("related_products", "<CONTENT_TYPE_UID>")) {
                    System.out.println(product.getString("title"));
                }
            }
        });
    }
}

Error handling: react to the error code

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryErrorCode {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null && error.getErrorCode() == 0) {
                    // Code 0: the API sent no error code, as with a timeout or a network failure
                    System.out.println("Request did not complete: " + error.getErrorMessage());
                    return;
                }
                if (error != null) {
                    System.out.println("API error " + error.getErrorCode() + ": " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle());
            }
        });
    }
}

get

get returns the value of one field of the entry, in the type the SDK parsed it into.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: Object. The field value.

Validation

  • get does not throw for a missing key. It returns null.
  • A null key returns null.

Behavior

  • Client-side only. get reads the top-level key of the entry JSON that the last successful fetch or configure call stored.
  • The value keeps its parsed type: String, Boolean, Integer, Long, Double, JSONObject, or JSONArray.
  • It returns null for a missing key and for a field whose value is JSON null.
  • It does not resolve a dotted path such as details.material. Read the group with the getGroup method, then read its field.
  • Use the typed getters, such as getString, to skip the cast.

Example

Basic usage: read a field and check its type

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryField {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                Object price = entry.get("price");
                if (price instanceof Number) {
                    System.out.println("Price: " + price);
                } else {
                    System.out.println("The entry has no numeric price");
                }
            }
        });
    }
}

getAllEntries

getAllEntries returns the entries in a reference field of the entry as a list of Entry objects.

NameTypeDescription
refKey (required)String

Reference field UID to read.

Default: Not applicable
refContentType (required)String

Content type UID to give each returned entry.

Default: Not applicable

Returns: List<Entry>. The entries in the reference field.

Validation

  • getAllEntries returns an empty list when the entry holds no data, when refKey is missing, or when its value is not an array.
  • Throws ClassCastException if an array item is not an object.
  • The SDK does not check refContentType. It uses the value only as the content type UID of each returned entry.

Behavior

  • Client-side only. getAllEntries builds one Entry for each object in the reference array, and makes no request. Each entry holds the object as its JSON, and its UID.
  • Without includeReference on the request, the API returns only the UIDs of the referenced entries, as Include Reference describes. Chain includeReference(refKey) before fetch to read their fields.
  • getContentType on each returned entry returns refContentType. The SDK does not compare it with the referenced content type.
  • Each returned entry carries its UID and content type UID, so you can call fetch on it to read that entry in full.

Example

Basic usage: read the referenced entries

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.util.List;

public class ReadReferencedEntries {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>").includeReference("related_products");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                // related_products refers to entries of the same content type
                List<Entry> related = entry.getAllEntries("related_products", "<CONTENT_TYPE_UID>");
                for (Entry product : related) {
                    // getTitle returns null on these entries, so read the field
                    System.out.println(product.getUid() + " " + product.getString("title"));
                }
            }
        });
    }
}

getAsset

getAsset returns the asset in a single file field of the entry as an Asset.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: Asset. The asset in the file field.

Validation

  • getAsset does not throw for a missing key or a value that is not an object. It returns an Asset whose getters all return null, not null itself.

Behavior

  • Client-side only. getAsset builds an Asset from the JSON object under the key, and makes no request.
  • Read the asset with the Asset getters, such as getUrl, getFileName, and getAssetUid.
  • Check asset.getAssetUid() for null to find out whether the field held an asset.
  • For a file field marked multiple, use the getAssets method.

Example

Basic usage: read a file field

import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryAsset {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                Asset image = entry.getAsset("main_image");
                if (image.getAssetUid() == null) {
                    System.out.println("No main image");
                    return;
                }
                System.out.println(image.getFileName() + " " + image.getUrl());
            }
        });
    }
}

getAssets

getAssets returns the assets in a file field marked multiple as a list of Asset objects.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: List<Asset>. The assets in the file field.

Validation

  • Throws NullPointerException when the key is missing or its value is not an array, because getAssets iterates the array without a check.

Behavior

  • Client-side only. getAssets builds one Asset for each JSON object in the array, and makes no request.
  • It skips array items that are not objects.
  • An empty array returns an empty list.
  • For a single file field, use the getAsset method.

Example

Basic usage: read a multiple file field

import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.util.List;

public class ReadEntryAssets {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                // getAssets throws for a missing field, so check the array first
                if (entry.getJSONArray("gallery") == null) {
                    System.out.println("No gallery");
                    return;
                }
                List<Asset> gallery = entry.getAssets("gallery");
                for (Asset image : gallery) {
                    System.out.println(image.getUrl());
                }
            }
        });
    }
}

getBoolean

getBoolean returns the value of a boolean field of the entry.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: Boolean. The field value as a Boolean.

Validation

  • getBoolean does not throw for a missing key or a value of another type. It returns false for both, never null.

Behavior

  • Client-side only. getBoolean reads the top-level key of the entry JSON.
  • It returns the value only when the stored value is a Boolean. The string "true" returns false.
  • A missing field and a false field return the same value. Check entry.get(key) instanceof Boolean when the difference matters.

Example

Basic usage: read a boolean field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryBoolean {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                if (entry.getBoolean("in_stock")) {
                    System.out.println("In stock");
                }
            }
        });
    }
}

Edge case: tell a missing field from false

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class CheckBooleanPresent {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                if (!(entry.get("in_stock") instanceof Boolean)) {
                    System.out.println("The entry has no in_stock value");
                    return;
                }
                System.out.println("in_stock: " + entry.getBoolean("in_stock"));
            }
        });
    }
}

getContentType

getContentType returns the UID of the content type that the entry belongs to.

Returns: String. The entry's content type UID.

Validation

  • There is no client-side validation. getContentType cannot fail.

Behavior

  • Client-side only. getContentType returns the content type UID that you passed to stack.contentType() when you built the entry. It holds a value before any fetch, and a fetch does not change it.
  • Entries from getAllEntries return the refContentType argument of that call.
  • It returns a UID string, not a ContentType object. Pass the UID to the contentType method of Stack to get the object.

Example

Basic usage: read the content type UID without a request

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Stack;

public class PrintEntryContentType {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        System.out.println("Content type: " + entry.getContentType());
    }
}

getCreateAt

getCreateAt returns the created_at value of the entry, its creation time, as a Calendar.

Returns: Calendar. The entry's creation time.

Validation

  • getCreateAt does not throw. It returns null when the entry JSON has no created_at value, or when the value is not an ISO 8601 date-time.
  • Each failed parse writes a SEVERE record to the java.util.logging logger of the SDK.

Behavior

  • Client-side only. getCreateAt reads the created_at key of the entry JSON that the last successful fetch or configure call stored.
  • It returns null before the entry holds data.

Example

Basic usage: read the creation time

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.time.OffsetDateTime;
import java.util.Calendar;

public class ReadEntryCreatedAt {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                Calendar value = entry.getCreateAt();
                if (value == null) {
                    System.out.println("No created_at value");
                    return;
                }
                // The Calendar is one month ahead, so parse the string for the exact time
                System.out.println(OffsetDateTime.parse(entry.getString("created_at")));
            }
        });
    }
}

getCreatedBy

getCreatedBy returns the UID of the user who created the entry.

Returns: String. The UID of the user who created the entry.

Validation

  • getCreatedBy does not throw for a missing value. It returns null.

Behavior

  • Client-side only. getCreatedBy returns the created_by value of the entry JSON through getString.
  • It returns null when the entry JSON has no created_by key.

Example

Basic usage: read who created the entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryCreatedBy {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("created_by: " + entry.getCreatedBy());
            }
        });
    }
}

getDate

getDate returns the value of a date field of the entry as a Calendar.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: Calendar. The field value as a Calendar.

Validation

  • getDate does not throw. It returns null for a missing key, a value that is not a string, and a string that is not an ISO 8601 date-time.
  • Each failed parse writes a SEVERE record to the java.util.logging logger of the SDK, including a call for a missing field.

Behavior

  • Client-side only. getDate reads the string value of the top-level key and parses it as an ISO 8601 date-time, such as 2024-05-01T10:30:00.000Z.
  • A date with no time part, such as 2024-05-01, returns null.
  • The Calendar uses the default time zone of the JVM, and its milliseconds come from the current time, not from the string.

Example

Basic usage: read a date field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.util.Calendar;

public class ReadEntryDate {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                Calendar launchDate = entry.getDate("launch_date");
                if (launchDate != null) {
                    System.out.println("Launch: " + launchDate.getTime());
                }
            }
        });
    }
}

Workaround: parse the date with java.time

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.time.OffsetDateTime;

public class ParseEntryDate {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                String value = entry.getString("launch_date");
                if (value == null) {
                    System.out.println("No launch date");
                    return;
                }
                OffsetDateTime launchDate = OffsetDateTime.parse(value);
                System.out.println(launchDate.getYear() + "-" + launchDate.getMonthValue() + "-" + launchDate.getDayOfMonth());
            }
        });
    }
}

getDeleteAt

getDeleteAt returns the deleted_at value of the entry, its deletion time, as a Calendar.

Returns: Calendar. The entry's deletion time.

Validation

  • getDeleteAt does not throw. It returns null when the entry JSON has no deleted_at value, or when the value is not an ISO 8601 date-time.
  • Each failed parse writes a SEVERE record to the java.util.logging logger of the SDK.

Behavior

  • Client-side only. getDeleteAt reads the deleted_at key of the entry JSON that the last successful fetch or configure call stored.
  • It returns null before the entry holds data.

Example

Basic usage: read the deletion time

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.time.OffsetDateTime;
import java.util.Calendar;

public class ReadEntryDeletedAt {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                Calendar value = entry.getDeleteAt();
                if (value == null) {
                    System.out.println("No deleted_at value");
                    return;
                }
                // The Calendar is one month ahead, so parse the string for the exact time
                System.out.println(OffsetDateTime.parse(entry.getString("deleted_at")));
            }
        });
    }
}

getDeletedBy

getDeletedBy returns the UID of the user who deleted the entry.

Returns: String. The UID of the user who deleted the entry.

Validation

  • getDeletedBy does not throw for a missing value. It returns null.

Behavior

  • Client-side only. getDeletedBy returns the deleted_by value of the entry JSON through getString.
  • It returns null when the entry JSON has no deleted_by key.

Example

Basic usage: read who deleted the entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryDeletedBy {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("deleted_by: " + entry.getDeletedBy());
            }
        });
    }
}

getDouble

getDouble returns the value of a number field of the entry as a double.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: double. The field value as a double.

Validation

  • getDouble does not throw for a missing key or a value of another type. It returns 0 for both.

Behavior

  • Client-side only. getDouble reads the top-level key of the entry JSON.
  • It converts any stored Number, whole or decimal, with doubleValue().
  • A number stored as text returns 0.
  • Use getNumber to tell a missing field from 0.

Example

Basic usage: read a decimal field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryDouble {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                double price = entry.getDouble("price");
                System.out.println("Price: " + price);
            }
        });
    }
}

getFloat

getFloat is meant to return the value of a decimal field of the entry as a float.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: float. The field value as a float.

Validation

  • getFloat does not throw for a missing key or a value of another type. It returns 0 for both.

Behavior

  • Client-side only. getFloat reads the top-level key of the entry JSON.
  • It returns the value only when the stored value is a Float. The SDK parses every decimal in a response into a Double. It parses every whole number into an Integer or a Long. A fetched entry never holds a Float.
  • An entry that you fill with configure returns a float only for values you stored as Float.

Example

Workaround: read a decimal field as a float

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryFloat {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                // getFloat returns 0 for fetched data, so convert the double instead
                float price = (float) entry.getDouble("price");
                System.out.println("Price: " + price);
            }
        });
    }
}

getGroup

getGroup returns a Group field of the entry as a Group.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: Group. The group in the field.

Validation

  • getGroup returns null when the key is missing or empty, or when its value is not an object.
  • Throws NullPointerException if key is null.

Behavior

  • Client-side only. getGroup wraps the JSON object under the key in a Group, and makes no request.
  • The Group getters read the fields of the group. They throw for a missing key, unlike the Entry getters. See the Group class page.
  • For a Group field marked multiple, use the getGroups method.

Example

Basic usage: read a field inside a Group field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Group;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryGroup {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                Group details = entry.getGroup("details");
                if (details == null) {
                    System.out.println("No details group");
                    return;
                }
                System.out.println("Material: " + details.getString("material"));
            }
        });
    }
}

getGroups

getGroups returns a Group field marked multiple as a list of Group objects.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: List<Group>. The groups in the field.

Validation

  • getGroups returns an empty list when the key is missing or empty, or when its value is not an array.
  • Throws NullPointerException if key is null.
  • Throws ClassCastException if an array item is not an object, as in a text field marked multiple.

Behavior

  • Client-side only. getGroups wraps each JSON object of the array in a Group, and makes no request.
  • The list keeps the order of the array.
  • For a single Group field, use the getGroup method.

Example

Basic usage: read each item of a multiple Group field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Group;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.util.List;

public class ReadEntryGroups {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                List<Group> faqs = entry.getGroups("faqs");
                for (Group faq : faqs) {
                    System.out.println(faq.getString("question"));
                }
            }
        });
    }
}

getHeaders

getHeaders returns the header map, a LinkedHashMap<String, Object>, that the entry shares with its Stack.

Returns: LinkedHashMap. The headers the stack sends with each request.

Validation

  • There is no client-side validation. getHeaders cannot fail.

Behavior

  • Client-side only. getHeaders makes no request.
  • It returns the live map, not a copy. A change you make to the map changes the headers of every later request through the same Stack.
  • The map holds api_key, access_token, and environment from Contentstack.stack. It also holds the headers that Config added when you created the stack. It includes any header that setHeader or variants added.
  • After the first request, the map also holds the X-User-Agent, User-Agent, and Content-Type headers that the SDK adds when it sends a request.
  • The map holds your delivery token under access_token. Print single keys rather than the whole map.

Example

Basic usage: check which headers the next request sends

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Stack;

import java.util.LinkedHashMap;

public class ReadEntryHeaders {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>").variants("<VARIANT_UID>");

        LinkedHashMap<String, Object> headers = entry.getHeaders();

        // Print single keys. The map also holds the delivery token.
        System.out.println("environment: " + headers.get("environment"));
        System.out.println("variant: " + headers.get("x-cs-variant-uid"));
    }
}

getInt

getInt returns the value of a whole-number field of the entry as an int.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: int. The field value as an int.

Validation

  • getInt does not throw for a missing key or a value of another type. It returns 0 for both.

Behavior

  • Client-side only. getInt reads the top-level key of the entry JSON.
  • It returns the value only when the stored value is an Integer. It does not convert other numbers:
    • A decimal, such as 4.5, returns 0.
    • A whole number outside the int range arrives as a Long and returns 0.
  • Use getLong, getDouble, or getNumber(key).intValue() when the field can hold other numbers.

Example

Basic usage: read a whole-number field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryInt {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                int stockCount = entry.getInt("stock_count");
                System.out.println("Stock: " + stockCount);
            }
        });
    }
}

Edge case: a decimal returns 0

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadDecimalAsInt {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                // price holds 49.5, so getInt returns 0
                System.out.println(entry.getInt("price"));
                System.out.println(entry.getNumber("price").intValue());
            }
        });
    }
}

getJSONArray

getJSONArray returns the value of a multiple field, a reference field, or the tags of the entry as an array.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: JSONArray. The field value as a JSONArray.

Validation

  • getJSONArray does not throw for a missing key or a value of another type. It returns null for both.

Behavior

  • Client-side only. getJSONArray reads the top-level key of the entry JSON.
  • It returns the value only when the stored value is a JSONArray, as a field marked multiple, a reference field, or the tags key is. A single-value field returns null.
  • Use getAssets, getGroups, or getAllEntries to read the array as SDK objects.

Example

Basic usage: read a multiple text field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import org.json.JSONArray;

public class ReadEntryArray {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                JSONArray keywords = entry.getJSONArray("keywords");
                if (keywords == null) {
                    System.out.println("No keywords");
                    return;
                }
                for (int i = 0; i < keywords.length(); i++) {
                    System.out.println(keywords.optString(i));
                }
            }
        });
    }
}

getJSONObject

getJSONObject returns the value of a Group, file, or JSON Rich Text Editor field of the entry as an object.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: JSONObject. The field value as a JSONObject.

Validation

  • getJSONObject does not throw for a missing key or a value of another type. It returns null for both.

Behavior

  • Client-side only. getJSONObject reads the top-level key of the entry JSON.
  • It returns the value only when the stored value is a JSONObject. A field marked multiple holds an array, so it returns null.
  • Use getGroup or getAsset to read the object as an SDK object with typed getters.

Example

Basic usage: read a Group field as JSON

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import org.json.JSONObject;

public class ReadEntryObject {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                JSONObject details = entry.getJSONObject("details");
                if (details != null) {
                    System.out.println("Material: " + details.optString("material"));
                }
            }
        });
    }
}

getLocale

getLocale returns the locale code of the entry that the API returned.

Returns: String. The entry's locale code.

Validation

  • There is no client-side validation. getLocale cannot fail.

Behavior

  • Client-side only. getLocale returns the locale value that the last successful fetch or configure call stored.
  • It returns null before the entry holds data. It does not return the value you passed to setLocale.
  • Entries from getAllEntries also return null. Call getString("locale") on those.

Example

Basic usage: print the locale of the returned entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class PrintEntryLocale {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>").setLocale("<LOCALE>").includeFallback();

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("Locale: " + entry.getLocale());
            }
        });
    }
}

getLong

getLong returns the value of a number field of the entry as a long.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: long. The field value as a long.

Validation

  • getLong does not throw for a missing key or a value of another type. It returns 0 for both.

Behavior

  • Client-side only. getLong reads the top-level key of the entry JSON.
  • It converts any stored Number with longValue(), so a decimal loses its fraction. For example, 4.9 returns 4.
  • A number stored as text returns 0.
  • Use getNumber to tell a missing field from 0.

Example

Basic usage: read a large whole number

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryLong {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                long viewCount = entry.getLong("view_count");
                System.out.println("Views: " + viewCount);
            }
        });
    }
}

getNumber

getNumber returns the value of a number field of the entry.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: Number. The field value as a Number.

Validation

  • getNumber does not throw for a missing key or a value of another type. It returns null for both.

Behavior

  • Client-side only. getNumber reads the top-level key of the entry JSON.
  • It returns the value when the stored value is any Number. A whole number arrives as an Integer, or as a Long when it exceeds the int range. A decimal arrives as a Double.
  • A number stored as text, such as "42", returns null. The SDK does not parse strings.
  • Use getNumber when you need to tell a missing field from 0. The primitive getters, such as getInt, return 0 for both.

Example

Basic usage: read a number field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryNumber {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                Number price = entry.getNumber("price");
                if (price == null) {
                    System.out.println("No price");
                    return;
                }
                System.out.println("Price: " + price.doubleValue());
            }
        });
    }
}

getShort

getShort returns the value of a number field of the entry as a short.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: short. The field value as a short.

Validation

  • getShort does not throw for a missing key or a value of another type. It returns 0 for both.

Behavior

  • Client-side only. getShort reads the top-level key of the entry JSON.
  • It converts any stored Number with shortValue(). A decimal loses its fraction, and a value outside the short range of -32,768 to 32,767 wraps around, as Java narrowing conversion does.
  • A number stored as text returns 0.
  • Use getInt or getLong when the value can exceed the short range.

Example

Basic usage: read a small whole number

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryShort {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                short stockCount = entry.getShort("stock_count");
                System.out.println("Stock: " + stockCount);
            }
        });
    }
}

getString

getString returns the value of a text field of the entry.

NameTypeDescription
key (required)String

Field UID to read.

Default: Not applicable

Returns: String. The field value as a String.

Validation

  • getString does not throw for a missing key or a value of another type. It returns null for both.

Behavior

  • Client-side only. getString reads the top-level key of the entry JSON.
  • It returns the value only when the stored value is a String. A number, a boolean, or an object returns null, not its text.
  • Call get and String.valueOf to turn a value of another type into text.

Example

Basic usage: read a text field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryString {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                String description = entry.getString("description");
                System.out.println(description != null ? description : "No description");
            }
        });
    }
}

Edge case: a number field returns null

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadNumberAsString {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                // price holds a number, so getString returns null
                System.out.println(entry.getString("price"));
                System.out.println(String.valueOf(entry.get("price")));
            }
        });
    }
}

getTags

getTags is meant to return the tags of the entry.

Returns: String[]. The entry's tags.

Validation

  • There is no client-side validation. getTags cannot fail.

Behavior

  • Client-side only. getTags makes no request.
  • The SDK never fills the tags value when it reads a response or JSON, so getTags returns null.
  • The tags arrive in the entry JSON under the tags key as an array, which the getJSONArray method reads.

Example

Workaround: read the tags from the entry JSON

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import org.json.JSONArray;

public class PrintEntryTags {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                JSONArray tags = entry.getJSONArray("tags");
                if (tags == null) {
                    System.out.println("No tags");
                    return;
                }
                for (int i = 0; i < tags.length(); i++) {
                    System.out.println(tags.optString(i));
                }
            }
        });
    }
}

getTitle

getTitle returns the title field of the entry.

Returns: String. The entry's title.

Validation

  • There is no client-side validation. getTitle cannot fail.

Behavior

  • Client-side only. getTitle returns the title value that the last successful fetch or configure call stored.
  • It returns null before the entry holds data, and when the entry JSON has no title key.
  • Entries in a Query result carry the title too. Entries from getAllEntries do not, so call getString("title") on those.

Example

Basic usage: print the title of a fetched entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class PrintEntryTitle {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("Title: " + entry.getTitle());
            }
        });
    }
}

getURL

getURL returns the url field of the entry.

Returns: String. The entry's URL.

Validation

  • There is no client-side validation. getURL cannot fail.

Behavior

  • Client-side only. getURL returns the url value that the last successful fetch or configure call stored.
  • It returns null before the entry holds data, and when the content type has no url field.
  • Entries in a Query result carry the URL too. Entries from getAllEntries do not, so call getString("url") on those.

Example

Basic usage: print the URL of a fetched entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class PrintEntryUrl {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("URL: " + entry.getURL());
            }
        });
    }
}

getUid

getUid returns the UID of the entry.

Returns: String. The entry's UID.

Validation

  • There is no client-side validation. getUid cannot fail.

Behavior

  • Client-side only. getUid returns the UID that you passed to entry(), so it holds a value before any fetch.
  • A successful fetch sets it to the uid value of the response, and configure sets it to the uid value of the JSON.
  • Entries in a Query result and from getAllEntries carry the UID of each entry.

Example

Basic usage: read the UID without a request

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.Stack;

public class PrintEntryUid {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        System.out.println("Entry UID: " + entry.getUid());
    }
}

getUpdateAt

getUpdateAt returns the updated_at value of the entry, its last update time, as a Calendar.

Returns: Calendar. The entry's last update time.

Validation

  • getUpdateAt does not throw. It returns null when the entry JSON has no updated_at value, or when the value is not an ISO 8601 date-time.
  • Each failed parse writes a SEVERE record to the java.util.logging logger of the SDK.

Behavior

  • Client-side only. getUpdateAt reads the updated_at key of the entry JSON that the last successful fetch or configure call stored.
  • It returns null before the entry holds data.

Example

Basic usage: read the last update time

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.time.OffsetDateTime;
import java.util.Calendar;

public class ReadEntryUpdatedAt {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                Calendar value = entry.getUpdateAt();
                if (value == null) {
                    System.out.println("No updated_at value");
                    return;
                }
                // The Calendar is one month ahead, so parse the string for the exact time
                System.out.println(OffsetDateTime.parse(entry.getString("updated_at")));
            }
        });
    }
}

getUpdatedBy

getUpdatedBy returns the UID of the user who last updated the entry.

Returns: String. The UID of the user who last updated the entry.

Validation

  • getUpdatedBy does not throw for a missing value. It returns null.

Behavior

  • Client-side only. getUpdatedBy returns the updated_by value of the entry JSON through getString.
  • It returns null when the entry JSON has no updated_by key.

Example

Basic usage: read who last updated the entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ReadEntryUpdatedBy {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println("updated_by: " + entry.getUpdatedBy());
            }
        });
    }
}

includeBranch

includeBranch asks the API to add the _branch key to the response.

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. includeBranch cannot fail.
  • An API rejection reaches the callback as an Error when fetch sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. includeBranch records include_branch=true and makes no request. fetch sends it.
  • The API reference describes _branch as a top-level key of the response that holds the UID of the branch. The include_branch parameter of Get a single entry states this.
  • fetch keeps only the entry object of the response body. Keys that the API returns beside it do not reach your code.
  • A second call changes nothing. The flag stays on the entry for every later fetch.

Example

Basic usage: send the branch flag with the request

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryWithBranch {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.includeBranch();

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.toJSON().opt("_branch"));
            }
        });
    }
}

includeContentType

includeContentType asks the API to return the content type of the entry with the response.

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. includeContentType cannot fail.
  • An API rejection reaches the callback as an Error when fetch sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. includeContentType records include_content_type=true and include_global_field_schema=true and makes no request. fetch sends it.
  • include_global_field_schema asks for the schema of each Global field that the content type uses, as the Get a single content type request describes.
  • includeContentType also deletes an include_schema parameter that an earlier addParam call set.
  • A second call changes nothing. The flag stays on the entry for every later fetch.
  • fetch keeps only the entry object of the response body. Keys that the API returns beside it do not reach your code.

Limitations

  • Does not return a ContentType object or its schema. Use the fetch method of ContentType to read the schema.

Example

Basic usage: send the content type flags with the request

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryWithContentType {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.includeContentType();

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle());
            }
        });
    }
}

includeEmbeddedItems

includeEmbeddedItems returns the entries and assets embedded in the Rich Text Editor fields of the entry.

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. includeEmbeddedItems cannot fail.
  • An API rejection reaches the callback as an Error when fetch sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. includeEmbeddedItems records include_embedded_items[]=BASE and makes no request. fetch sends it.
  • The API then returns the first level of embedded entries and assets under the _embedded_items key, as Get information on embedded RTE objects describes.
  • The SDK sends BASE only. To include items nested inside embedded items, call addParam("include_embedded_items[]", "RECURSIVE") instead. That call replaces BASE, because both use the same key.
  • A second call changes nothing. The flag stays on the entry for every later fetch.

Example

Basic usage: return the embedded items

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryEmbeddedItems {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.includeEmbeddedItems();

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getJSONObject("_embedded_items"));
            }
        });
    }
}

includeFallback

includeFallback returns the entry from the fallback locale when it has no published version in the requested locale.

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. includeFallback cannot fail.
  • An API rejection reaches the callback as an Error when fetch sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. includeFallback records include_fallback=true and makes no request. fetch sends it.
  • The API then returns the published content of the fallback locale when the locale from setLocale holds no published content. The include_fallback parameter of Get a single entry describes this behavior.
  • getLocale returns the locale of the content that the API returned.
  • A second call changes nothing. The flag stays on the entry for every later fetch.

Example

Basic usage: read a locale, or its fallback

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryWithFallback {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>").setLocale("<LOCALE>").includeFallback();

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle() + " (" + entry.getLocale() + ")");
            }
        });
    }
}

includeMetadata

includeMetadata adds the metadata of the entry to the response.

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. includeMetadata cannot fail.
  • An API rejection reaches the callback as an Error when fetch sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. includeMetadata records include_metadata=true and makes no request. fetch sends it.
  • The API then returns the entry metadata under the _metadata key, as Get a single entry describes.
  • Read it with getJSONObject("_metadata").
  • A second call changes nothing. The flag stays on the entry for every later fetch.

Example

Basic usage: read the entry metadata

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryMetadata {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.includeMetadata();

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getJSONObject("_metadata"));
            }
        });
    }
}

includeReference

includeReference returns the full content of the entries in a reference field, instead of their UIDs only.

NameTypeDescription
referenceField (required)String

Reference field UID to include.

Default: Not applicable
referenceFields (required)String[]

Reference field UIDs to include.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Overloads

  • includeReference(String referenceField)
  • includeReference(String[] referenceFields)

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • An empty string or an empty array changes nothing.
  • Throws NullPointerException if the argument is null.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. includeReference records each UID under the include[] query parameter and makes no request. fetch sends one parameter per field, as Include Reference describes.
  • Without it, a reference field returns only the UIDs of the referenced entries.
  • Calls to both overloads add to one list. A UID that you add twice goes out twice.
  • The list stays on the entry for every later fetch.
  • Write a reference field inside a Group or Modular Blocks field as a dotted path, such as details.related_products.
  • Read the referenced entries with the getAllEntries method.
  • onlyWithReferenceUid and exceptWithReferenceUid call includeReference for their reference field.

Example

Basic usage: include one reference field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryWithReference {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.includeReference("related_products");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry product : entry.getAllEntries("related_products", "<CONTENT_TYPE_UID>")) {
                    System.out.println(product.getString("title"));
                }
            }
        });
    }
}

Several fields: include two reference fields in one call

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Group;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryWithReferences {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.includeReference(new String[]{"related_products", "details.related_products"});

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println(entry.getJSONArray("related_products"));
                Group details = entry.getGroup("details");
                if (details != null) {
                    System.out.println(details.toJSON().opt("related_products"));
                }
            }
        });
    }
}

includeReferenceContentTypeUID

includeReferenceContentTypeUID asks the API to add the content type UID to each referenced entry in the response.

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. includeReferenceContentTypeUID cannot fail.
  • An API rejection reaches the callback as an Error when fetch sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. includeReferenceContentTypeUID records include_reference_content_type_uid=true and makes no request. fetch sends it.
  • A second call changes nothing. The flag stays on the entry for every later fetch.
  • Chain the includeReference method too when you need the referenced entries in full.

Example

Basic usage: return the content type UID of each referenced entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import org.json.JSONArray;

public class FetchReferenceContentTypes {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.includeReference("related_products").includeReferenceContentTypeUID();

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                JSONArray related = entry.getJSONArray("related_products");
                System.out.println(related);
            }
        });
    }
}

only

only keeps the listed top-level fields in the entry that fetch returns and leaves out the rest.

NameTypeDescription
fieldUid (required)String[]

Field UIDs to keep.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • A null or empty array changes nothing.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. only records each UID under the only[BASE][] query parameter and makes no request. fetch sends one parameter per field, as the Only operator describes.
  • A second call adds to the list.
  • The list applies to the next fetch only. fetch clears it after it builds the request, so call only again before each fetch.
  • Write a field inside a Group field as a dotted path, such as details.material.
  • To keep fields of a referenced entry, use the onlyWithReferenceUid method.

Example

Basic usage: keep two fields

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryOnly {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.only(new String[]{"title", "price"});

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle() + " " + entry.getDouble("price"));
            }
        });
    }
}

onlyWithReferenceUid

onlyWithReferenceUid includes the entries of a reference field and keeps only the listed fields of each.

NameTypeDescription
fieldUid (required)List<String>

Fields to keep in each referenced entry.

Default: Not applicable
referenceFieldUid (required)String

Reference field UID to include.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • Throws NullPointerException if fieldUid or referenceFieldUid is null.
  • An empty fieldUid list includes the referenced entries with all their fields.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. onlyWithReferenceUid records each field under the only[<referenceFieldUid>][] query parameter, and calls includeReference for referenceFieldUid. It makes no request. The Only operator describes the parameter.
  • You do not need a separate includeReference call for the same field. Adding one sends the include[] value twice.
  • A second call for the same reference field replaces its list. A call for another reference field adds that field.
  • The only lists apply to the next fetch only, and fetch clears them. The include[] value stays on the entry for later fetches.
  • Combine it with the only method to limit the fields of the entry itself.

Example

Basic usage: keep two fields of each referenced entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.util.Arrays;

public class FetchReferenceOnly {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.onlyWithReferenceUid(Arrays.asList("title", "price"), "related_products");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                for (Entry product : entry.getAllEntries("related_products", "<CONTENT_TYPE_UID>")) {
                    System.out.println(product.getString("title") + " " + product.getDouble("price"));
                }
            }
        });
    }
}

removeHeader

removeHeader deletes a header from the header map that the entry shares with its Stack.

NameTypeDescription
key (required)String

Header name to delete.

Default: Not applicable

Returns: void. This method returns nothing.

Validation

  • removeHeader ignores an empty key, and a key that the map does not hold, without an error.
  • Throws NullPointerException if key is null.

Behavior

  • Client-side only. removeHeader makes no request.
  • The map belongs to the Stack, so the header leaves every later request through that Stack, not only this entry's fetch.
  • Deleting a header that Contentstack.stack set, such as api_key, access_token, or environment, removes it from every later request of the Stack.
  • Use removeHeader after a fetch to clear a header that setHeader or variants added for that one request.

Example

Basic usage: clear the variant header after a variant request

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class RemoveEntryHeader {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>").variants("<VARIANT_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle());
            }
        });

        // Later requests through this stack no longer ask for the variant
        entry.removeHeader("x-cs-variant-uid");
    }
}

setHeader

setHeader adds a header to the header map that the entry shares with its Stack.

NameTypeDescription
key (required)String

Header name.

Default: Not applicable
value (required)String

Header value.

Default: Not applicable

Returns: void. This method returns nothing.

Validation

  • setHeader ignores the call when key or value is an empty string, and reports no error.
  • Throws NullPointerException if key is null, or if value is null while key is not empty.

Behavior

  • Client-side only. setHeader makes no request. The next request sends the header.
  • The entry shares one header map with the Stack that created it and with every object that Stack creates. setHeader writes to that map, so the header goes out on every later request through that Stack, not only on this entry's fetch.
  • A second call with the same key replaces the value.
  • Delete the header with the removeHeader method. Read the map with the getHeaders method.

Example

Basic usage: read the entry from a branch

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class SetEntryHeader {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.setHeader("branch", "<BRANCH>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle());
            }
        });
    }
}

Edge case: keep the header off later requests

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class ScopeEntryHeader {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.setHeader("branch", "<BRANCH>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println(entry.getTitle());
            }
        });

        // The header map belongs to the stack, so remove the header after the request
        entry.removeHeader("branch");
    }
}

setLocale

setLocale sets the locale in which fetch reads the entry.

NameTypeDescription
locale (required)String

Locale code to read, such as fr-fr.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • Passing null deletes a locale that an earlier setLocale call set, because the org.json JSONObject.put method deletes a key whose value is null.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. setLocale records the locale query parameter and makes no request. fetch sends it to Get a single entry.
  • Without setLocale, the SDK sends no locale and the API applies its own default.
  • Chain the includeFallback method to read the fallback locale when the entry has no published version in this locale.
  • A second call replaces the first value. The locale stays on the entry for every later fetch.
  • getLocale returns the locale of the response, not this value.

Example

Basic usage: read the entry in one locale

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryInLocale {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>").setLocale("<LOCALE>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle() + " (" + entry.getLocale() + ")");
            }
        });
    }
}

toJSON

toJSON returns the JSON of the entry that the getters read.

Returns: JSONObject. The entry's fields as JSON.

Validation

  • There is no client-side validation. toJSON cannot fail.

Behavior

  • Client-side only. toJSON returns the object that the last successful fetch or configure call stored, or null before the entry holds data.
  • It returns the stored object, not a copy. A change you make to it changes what the getters return.
  • The object holds the entry object of the response only. A Group or file field is a JSONObject. A multiple field or reference field is a JSONArray. A whole number is an Integer or a Long. A decimal is a Double.
  • A field whose value is JSON null is absent from the object, because the SDK drops null values when it parses the response.

Example

Basic usage: print the entry JSON

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import org.json.JSONObject;

public class PrintEntryJson {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                JSONObject json = entry.toJSON();
                System.out.println(json.toString(2));
            }
        });
    }
}

Field list: print the field UIDs the entry carries

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class PrintEntryFieldUids {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                for (String fieldUid : entry.toJSON().keySet()) {
                    System.out.println(fieldUid);
                }
            }
        });
    }
}

variants

variants reads the entry with the content of one or more entry variants applied.

NameTypeDescription
variants (required)String

Variant UID or alias.

Default: Not applicable
branch (required)String

Branch UID to read the entry from.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Overloads

  • variants(String variants)
  • variants(String[] variants)
  • variants(String variants, String branch)
  • variants(String[] variants, String branch)

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an Error in the callback when fetch sends the request.
  • variants ignores a null, empty, or blank value without an error. In an array, it skips each null or blank item.
  • The overloads with branch ignore a null or blank branch in the same way.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. variants writes the x-cs-variant-uid header and makes no request. fetch sends it to Get single entry variant.
  • It trims each UID. The array overloads join the UIDs with commas, in the order you pass them.
  • The API applies up to five variant UIDs or aliases by default, and the first one takes priority over the base entry fields.
  • The overloads with branch also write the branch header, trimmed.
  • A second call replaces the earlier header value.
  • The headers go into the header map that the entry shares with its Stack. See the setHeader method.

Example

Basic usage: read one variant of the entry

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryVariant {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>").variants("<VARIANT_UID>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) {
                    // The API rejected the request, or it did not complete
                    System.out.println("Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
                    return;
                }
                System.out.println(entry.getTitle());
            }
        });

        // Keep the variant off later requests through this stack
        entry.removeHeader("x-cs-variant-uid");
    }
}

Several variants: apply two variants, highest priority first

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryVariants {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.variants(new String[]{"<VARIANT_UID>", "<VARIANT_UID>"});

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println(entry.getTitle());
            }
        });

        entry.removeHeader("x-cs-variant-uid");
    }
}

Branch: read a variant from one branch

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryVariantOnBranch {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.variants("<VARIANT_UID>", "<BRANCH>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println(entry.getTitle());
            }
        });

        entry.removeHeader("x-cs-variant-uid");
        entry.removeHeader("branch");
    }
}

Branch and several variants: combine both

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

public class FetchEntryVariantsOnBranch {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
        entry.variants(new String[]{"<VARIANT_UID>", "<VARIANT_UID>"}, "<BRANCH>");

        entry.fetch(new EntryResultCallBack() {
            @Override
            public void onCompletion(ResponseType responseType, Error error) {
                if (error != null) { System.out.println(error.getErrorMessage()); return; }
                System.out.println(entry.getTitle());
            }
        });

        entry.removeHeader("x-cs-variant-uid");
        entry.removeHeader("branch");
    }
}