Global Fields

A Global field is a reusable field, or group of fields, that you define once and reuse in any content type of a stack. The GlobalField class reads global fields through the Content Delivery API (CDA). Use this class to

read one global field by its UID
list every global field of the stack
add the schema or the branch of each global field to the response

fetch

fetch retrieves one global field by the UID you passed to stack.globalField.

Name	Type	Description
callback (required)	GlobalFieldsCallback	Receives the global field or the error. See Callbacks. Default: Not applicable

Returns: void. The result arrives in the callback.

Validation

Throws IllegalAccessException if the instance holds no UID, or an empty one, because fetch reads one global field by its UID. Java requires you to catch or declare it, because IllegalAccessException is a checked exception.
When callback is null, fetch sends no request and reports nothing.
fetch does not throw on an API rejection.
- The callback receives an Error and a null model.
- Check error first in every callback.

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

Behavior

fetch sends one request to Get a single global field (GET /global_fields/{global_field_uid}).
fetch sends the flags that includeBranch and includeGlobalFieldSchema stored on the instance. It sends no environment parameter.
On success, getResponse() of the GlobalFieldsModel is a JSONObject with the global field, and getResultArray() is empty. See The callback receives a GlobalFieldsModel on the Global Fields class page.

Example

Basic usage: read one global field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsCallback;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.Stack;
import org.json.JSONObject;

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

        globalField.fetch(new GlobalFieldsCallback() {
            @Override
            public void onCompletion(GlobalFieldsModel globalFieldsModel, 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 globalFieldJson = (JSONObject) globalFieldsModel.getResponse();
                System.out.println(globalFieldJson.optString("title"));
            }
        });
    }
}

Edge case: fetch on an instance without a UID throws

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalFieldsCallback;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.Stack;

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

        try {
            stack.globalField().fetch(new GlobalFieldsCallback() {
                @Override
                public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
                    if (error != null) { System.out.println(error.getErrorMessage()); return; }
                    System.out.println(globalFieldsModel.getResponse());
                }
            });
        } catch (IllegalAccessException e) {
            // Thrown when the instance holds no global field UID
            System.out.println("No global field UID: " + e.getMessage());
        }
    }
}

findAll

findAll retrieves every global field of the stack.

Name	Type	Description
callback (required)	GlobalFieldsCallback	Receives the global fields or the error. See Callbacks. Default: Not applicable

Returns: void. The result arrives in the callback.

Validation

There is no client-side validation. findAll declares no checked exception.
When callback is null, findAll sends no request and reports nothing.
findAll does not throw on an API rejection.
- The callback receives an Error and a null model.
- Check error first in every callback.

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

Behavior

findAll sends one request to Get all global fields (GET /global_fields).
findAll ignores any UID on the instance, so it lists every global field from stack.globalField() and from stack.globalField("<GLOBAL_FIELD_UID>") alike.
findAll sends the flags that includeBranch and includeGlobalFieldSchema stored on the instance. It sends no environment parameter.
On success, getResultArray() of the GlobalFieldsModel holds one JSONObject per global field. getResponse() returns the same list as a JSONArray.

Limitations

Does not page through the list. The class has no method that sends limit or skip.

Example

Basic usage: list every global field

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalFieldsCallback;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.Stack;
import org.json.JSONArray;
import org.json.JSONObject;

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

        stack.globalField().findAll(new GlobalFieldsCallback() {
            @Override
            public void onCompletion(GlobalFieldsModel globalFieldsModel, 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 globalFields = globalFieldsModel.getResultArray();
                for (int i = 0; i < globalFields.length(); i++) {
                    JSONObject globalField = globalFields.getJSONObject(i);
                    System.out.println(globalField.optString("uid") + " " + globalField.optString("title"));
                }
            }
        });
    }
}

includeBranch

includeBranch asks the API to add the _branch key, which names the branch of the global field, to the response.

Returns: GlobalField. The same global field, for chaining.

Validation

There is no client-side validation.
An invalid value surfaces as an Error in the callback when fetch or findAll sends the request.

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

Behavior

Client-side only. includeBranch stores include_branch=true on the instance and sends no request.
fetch and findAll send the parameter, which both Get a single global field and Get all global fields accept.
The API reference describes _branch as a top-level key. GlobalFieldsModel keeps only the global_field or global_fields value of the response body, so a _branch key outside that value does not reach the callback.
The flag stays on the instance for every later request. No method removes it.
Set the branch header with setHeader to read the global fields of a branch other than the default one.

Example

Basic usage: list global fields with their branch

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalFieldsCallback;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.Stack;
import org.json.JSONArray;
import org.json.JSONObject;

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

        stack.globalField().includeBranch().findAll(new GlobalFieldsCallback() {
            @Override
            public void onCompletion(GlobalFieldsModel globalFieldsModel, 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 globalFields = globalFieldsModel.getResultArray();
                for (int i = 0; i < globalFields.length(); i++) {
                    JSONObject globalField = globalFields.getJSONObject(i);
                    // Print each global field to see which keys the API returned
                    System.out.println(globalField.toString(2));
                }
            }
        });
    }
}

includeGlobalFieldSchema

includeGlobalFieldSchema asks the API to include the schema of each global field in the response.

Returns: GlobalField. The same global field, for chaining.

Validation

There is no client-side validation.
An invalid value surfaces as an Error in the callback when fetch or findAll sends the request.

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

Behavior

Client-side only. includeGlobalFieldSchema stores include_global_field_schema=true on the instance and sends no request.
fetch and findAll send the parameter, which both Get a single global field and Get all global fields accept.
The flag stays on the instance for every later request. No method removes it.

Example

Basic usage: read one global field with its schema

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalFieldsCallback;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.Stack;
import org.json.JSONArray;
import org.json.JSONObject;

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

        stack.globalField("<GLOBAL_FIELD_UID>").includeGlobalFieldSchema().fetch(new GlobalFieldsCallback() {
            @Override
            public void onCompletion(GlobalFieldsModel globalFieldsModel, 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 globalField = (JSONObject) globalFieldsModel.getResponse();
                JSONArray schema = globalField.optJSONArray("schema");
                System.out.println(schema == null ? "No schema" : schema.length() + " fields");
            }
        });
    }
}

Edge case: combine both flags on one instance

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsCallback;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.Stack;

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

            // Both flags stay on this instance for every later request.
            GlobalField globalField = stack.globalField().includeGlobalFieldSchema().includeBranch();
            globalField.findAll(new GlobalFieldsCallback() {
                @Override
                public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
                    if (error != null) { System.out.println(error.getErrorMessage()); return; }
                    System.out.println(globalFieldsModel.getResultArray().length() + " global fields");
                }
            });
        } catch (IllegalAccessException e) {
            System.out.println("Stack setup failed: " + e.getMessage());
        }
    }
}

removeHeader

removeHeader removes one request header from the stack that created this global field.

Name	Type	Description
headerKey (required)	String	Name of the header to remove. Default: Not applicable

Returns: void. This method returns nothing.

Validation

Throws NullPointerException if headerKey is null, because removeHeader checks it for emptiness first.
When headerKey is an empty string, or names a header that the stack does not hold, removeHeader does nothing and raises no error.

Behavior

Client-side only. removeHeader sends no request.
IMPORTANT: removeHeader removes the header from the header map of the stack, not from a copy. Every later request from the stack, and from the objects it creates, goes out without it. This includes the api_key, access_token and environment headers that every request needs, so remove only headers that you set yourself.
Use the setHeader method to add a header again.

Example

Basic usage: stop sending a branch header

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsCallback;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.Stack;

public class RemoveGlobalFieldHeader {
    public static void main(String[] args) throws IllegalAccessException {
        Stack stack = Contentstack.stack("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        GlobalField globalField = stack.globalField();
        globalField.setHeader("branch", "<BRANCH>");

        // Later requests from this stack go out without the branch header.
        globalField.removeHeader("branch");

        globalField.findAll(new GlobalFieldsCallback() {
            @Override
            public void onCompletion(GlobalFieldsModel globalFieldsModel, 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(globalFieldsModel.getResultArray().length() + " global fields");
            }
        });
    }
}

setHeader

setHeader adds a request header, or replaces the value of an existing one, on the stack that created this global field.

Name	Type	Description
headerKey (required)	String	Name of the header to set. Default: Not applicable
headerValue (required)	String	Value to send for that header. Default: Not applicable

Returns: void. This method returns nothing.

Validation

Throws NullPointerException if headerKey or headerValue is null, because setHeader checks each one for emptiness before it stores the pair.
When headerKey or headerValue is an empty string, setHeader ignores the call without an error.

Behavior

Client-side only. setHeader sends no request. Later requests carry the header.
IMPORTANT: setHeader writes to the header map of the stack, not to a copy. The header then travels on every later request from the stack and from the objects it creates, for example content types, entries and other global fields. Nothing in your code shows the wider effect at the point of the call.
Setting an existing name, such as branch, replaces its value.
Use the removeHeader method to remove the header again.

Example

Basic usage: list the global fields of a branch

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsCallback;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.Stack;

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

        // Every later request from this stack now carries the branch header.
        globalField.setHeader("branch", "<BRANCH>");

        globalField.findAll(new GlobalFieldsCallback() {
            @Override
            public void onCompletion(GlobalFieldsModel globalFieldsModel, 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(globalFieldsModel.getResultArray().length() + " global fields");
            }
        });
    }
}