SyncStack

View as Markdown

SyncStack

SyncStack contains one page of a sync response. The SDK creates it and passes it to the onCompletion method of your SyncResultCallBack. Use this class to

  • read the entries and assets in a sync page
  • tell whether more pages follow
  • read the sync token for the next sync

Every sync method on Stack delivers SyncStack objects, for example sync, syncToken, and syncPaginationToken. A SyncStack you create with new SyncStack() holds no data, because only the SDK can load a response into it.

getCount

getCount returns the total_count value of a sync response.

Returns: int. The total_count value of the sync response.

Validation

  • There is no client-side validation. getCount returns a value the SDK read when it parsed the response.

Behavior

  • Client-side only. getCount makes no request.
  • getCount returns 0 when the response has no total_count key.
  • The value comes from the response of this page. Use the getItems method to count the items the page holds.

Example

Basic usage: read the total count of a sync

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.SyncResultCallBack;
import com.contentstack.sdk.SyncStack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    stack.sync(new SyncResultCallBack() {
        @Override
        public void onCompletion(SyncStack syncStack, Error error) {
            if (error == null) {
                Log.d("Contentstack", "Total count: " + syncStack.getCount());
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getItems

getItems returns the entries and assets in one page of a sync response.

Returns: ArrayList<JSONObject>. The items of the current sync page.

Validation

  • There is no client-side validation. getItems returns a list the SDK built when it parsed the response.

Behavior

  • Client-side only. getItems makes no request.
  • Each element is one JSONObject from the items array of the response, in response order. The SDK does not convert items to Entry or Asset objects.
  • getItems returns null when the response has no items key. Check for null before you read the list.
  • The list holds the items of this page only. Collect the items of each page in your callback to build the full sync result.
  • Use the getJSONResponse method to read the whole response body.

Example

Basic usage: collect the items of every page

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.SyncResultCallBack;
import com.contentstack.sdk.SyncStack;

import org.json.JSONObject;

import java.util.ArrayList;
import java.util.List;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    List<JSONObject> syncedItems = new ArrayList<>();
    stack.sync(new SyncResultCallBack() {
        @Override
        public void onCompletion(SyncStack syncStack, Error error) {
            if (error == null) {
                if (syncStack.getItems() != null) {
                    syncedItems.addAll(syncStack.getItems());
                }
                if (syncStack.getSyncToken() != null) {
                    // Last page: every item has arrived
                    Log.d("Contentstack", "Synced items: " + syncedItems.size());
                }
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getJSONResponse

getJSONResponse returns the full body of a sync response as a JSONObject.

Returns: JSONObject. The full sync response body.

Validation

  • There is no client-side validation. getJSONResponse returns the object the SDK received.

Behavior

  • Client-side only. getJSONResponse makes no request.
  • The object is the response body as the SDK received it, with every key, including keys no other getter covers.
  • getJSONResponse returns null on a SyncStack that the SDK did not load from a response, such as one you create with new SyncStack().
  • The other getters read their values from this object. For example, getItems reads the items array.

Example

Basic usage: log the raw response of each page

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.SyncResultCallBack;
import com.contentstack.sdk.SyncStack;

import org.json.JSONObject;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    stack.sync(new SyncResultCallBack() {
        @Override
        public void onCompletion(SyncStack syncStack, Error error) {
            if (error == null) {
                JSONObject response = syncStack.getJSONResponse();
                Log.d("Contentstack", response.toString());
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getLimit

getLimit returns the limit value of a sync response.

Returns: int. The limit value of the sync response.

Validation

  • There is no client-side validation. getLimit returns a value the SDK read when it parsed the response.

Behavior

  • Client-side only. getLimit makes no request.
  • getLimit returns 0 when the response has no limit key.
  • No sync method takes a limit argument, so you cannot change the page size. The value is for reading only.
  • Use the getSkip method to read the skip value of the same response.

Example

Basic usage: read the limit value of a page

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.SyncResultCallBack;
import com.contentstack.sdk.SyncStack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    stack.sync(new SyncResultCallBack() {
        @Override
        public void onCompletion(SyncStack syncStack, Error error) {
            if (error == null) {
                Log.d("Contentstack", "limit " + syncStack.getLimit());
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getPaginationToken

getPaginationToken returns the pagination token of a sync page, which points to the next page.

Returns: String. The token for the next page of the sync, or null on the last page.

Validation

  • There is no client-side validation. getPaginationToken returns a value the SDK read when it parsed the response.

Behavior

  • Client-side only. getPaginationToken makes no request.
  • getPaginationToken returns the pagination_token value of the response, or null when the response has no pagination_token key.
  • The API returns a pagination token when the sync holds more than 100 records. See Sync using pagination token.
  • By the time your callback reads the token, the SDK has already requested the next page with it. You do not pass it on yourself.
  • Keep the latest token while a sync runs. If a page fails, pass it to the syncPaginationToken method of Stack to resume.

Example

Basic usage: keep the latest token to resume a failed sync

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.SyncResultCallBack;
import com.contentstack.sdk.SyncStack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    stack.sync(new SyncResultCallBack() {
        @Override
        public void onCompletion(SyncStack syncStack, Error error) {
            if (error == null) {
                String paginationToken = syncStack.getPaginationToken();
                if (paginationToken != null) {
                    // Store it. If a later page fails, resume with syncPaginationToken()
                    Log.d("Contentstack", "Latest pagination token: " + paginationToken);
                }
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getSkip

getSkip returns the skip value of a sync response.

Returns: int. The skip value of the sync response.

Validation

  • There is no client-side validation. getSkip returns a value the SDK read when it parsed the response.

Behavior

  • Client-side only. getSkip makes no request.
  • getSkip returns 0 when the response has no skip key.
  • No sync method takes a skip argument. The value is for reading only.
  • Use the getLimit method to read the limit value of the same response.

Example

Basic usage: log the skip and limit values of each page

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.SyncResultCallBack;
import com.contentstack.sdk.SyncStack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    stack.sync(new SyncResultCallBack() {
        @Override
        public void onCompletion(SyncStack syncStack, Error error) {
            if (error == null) {
                Log.d("Contentstack", "skip " + syncStack.getSkip() + ", limit " + syncStack.getLimit());
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getSyncToken

getSyncToken returns the sync token from the last page of a sync, which you store and pass to the next subsequent sync.

Returns: String. The token for the next subsequent sync, or null before the last page.

Validation

  • There is no client-side validation. getSyncToken returns a value the SDK read when it parsed the response.

Behavior

  • Client-side only. getSyncToken makes no request.
  • getSyncToken returns the sync_token value of the response. It returns null when the response has no sync_token key, which is the case on every page except the last.
  • A non-null value therefore marks the last page of the sync.
  • Store the token, for example in SharedPreferences. On the next run, pass it to the syncToken method of Stack to receive only the changes since this sync.

Example

Basic usage: keep the sync token from the last page

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.SyncResultCallBack;
import com.contentstack.sdk.SyncStack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    stack.sync(new SyncResultCallBack() {
        @Override
        public void onCompletion(SyncStack syncStack, Error error) {
            if (error == null) {
                String syncToken = syncStack.getSyncToken();
                if (syncToken != null) {
                    // Last page: store the token for the next syncToken() call
                    Log.d("Contentstack", "Sync token: " + syncToken);
                }
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getURL

getURL returns an empty string on every sync page, because the SDK does not record the request URL.

Returns: String. An empty string.

Validation

  • There is no client-side validation. getURL returns a fixed value.

Behavior

  • Client-side only. getURL makes no request.
  • getURL returns an empty string on every SyncStack the SDK delivers to your callback, and null on one you create with new SyncStack().
  • Do not use the value to build or repeat a request. Use the token getters instead: getPaginationToken to resume a sync, and getSyncToken for the next subsequent sync.

Example

Basic usage: read the URL value

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.SyncResultCallBack;
import com.contentstack.sdk.SyncStack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    stack.sync(new SyncResultCallBack() {
        @Override
        public void onCompletion(SyncStack syncStack, Error error) {
            if (error == null) {
                // Always an empty string
                Log.d("Contentstack", "URL: \"" + syncStack.getURL() + "\"");
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}