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