Config
Config
Config holds the settings that Contentstack.stack applies when it creates a stack. Use this class to
- send requests to a region other than North America, or to a custom host
- read content from a branch
- send early access headers
- route Taxonomy requests through a proxy and tune their connection pool
Create a Config with new Config(), call its setters, then pass it as the last argument of the five-argument Contentstack.stack overload.
connectionPool
connectionPool sets the maximum number of idle connections that the Taxonomy HTTP client keeps open, and their keep-alive time.
| Name | Type | Description |
|---|---|---|
| maxIdleConnections (required) | int | Maximum number of idle connections to keep. |
| keepAliveDuration (required) | long | Time an idle connection stays open. |
| timeUnit (required) | TimeUnit | Unit of keepAliveDuration, such as TimeUnit.MINUTES. |
Returns: ConnectionPool. The new connection pool.
Validation
- Throws IllegalArgumentException if keepAliveDuration is 0 or less, because OkHttp, the HTTP library that builds the pool, requires a positive keep-alive time.
- There is no other client-side validation.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- connectionPool creates a new okhttp3.ConnectionPool and stores it in place of the earlier one.
- The pool applies only to requests from Taxonomy. Entry, query, asset, content type, global field, and sync requests use a different HTTP client and ignore it.
- Call connectionPool before Contentstack.stack. The SDK builds the Taxonomy HTTP client when it creates the stack, so a later call does not change it.
- The return type is okhttp3.ConnectionPool, and the SDK declares OkHttp as a runtime dependency only. Add OkHttp to your app's own dependencies to refer to the returned pool in your code.
Example
Basic usage: keep up to ten idle connections for two minutes
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 org.json.JSONObject;
import java.util.concurrent.TimeUnit;
new Thread(() -> {
try {
Config config = new Config();
config.connectionPool(10, 2, TimeUnit.MINUTES);
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
// Taxonomy.find runs on the calling thread, so it stays inside this background thread
stack.taxonomy().exists("taxonomies.<TAXONOMY_UID>", true).find((JSONObject response, Error error) -> {
if (error == null) {
Log.d("Contentstack", response.toString());
} else {
// The API rejected the request
Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null, and find throws on a network failure
Log.e("Contentstack", "Request failed: " + e.getMessage());
}
}).start();earlyAccess
earlyAccess sends the names of early access features in the x-header-ea header of every request from the stack.
| Name | Type | Description |
|---|---|---|
| earlyAccess (required) | String[] | Early access feature names to send. |
Returns: Config. The same config, for chaining.
Validation
- There is no client-side validation. earlyAccess stores the array as given.
- earlyAccess accepts null and an empty array. Either one removes the values of an earlier call, and the SDK then sends no x-header-ea header.
- The SDK does not check the names against the API.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Contentstack.stack joins the names with commas, removes any double quotes, and sends the result as the x-header-ea header of every request from the stack.
- Call earlyAccess before Contentstack.stack. A call afterwards does not change the stack.
- The SDK keeps a reference to your array, not a copy. Fill the array before you create the stack.
- Use the getEarlyAccess method to read the names back.
Example
Basic usage: send two early access features
import android.util.Log;
import com.contentstack.sdk.Config;
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;
try {
// The SDK sends these as x-header-ea: taxonomy,teams
Config config = new Config().earlyAccess(new String[] {"taxonomy", "teams"});
config.setHost("cdn.contentstack.io"); // your region's host, see setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
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) {
Log.d("Contentstack", entry.getTitle());
} 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());
}getEarlyAccess
getEarlyAccess returns the early access feature names stored on the Config.
Returns: String[]. The early access names set on the config, or null.
Validation
- There is no client-side validation. getEarlyAccess reads a stored value and does not throw.
Behavior
- getEarlyAccess returns null until you call earlyAccess, and the array you passed after that.
- The method returns the same array object that you passed, not a copy. A change to that array also changes what getEarlyAccess returns.
- Check for null before you read the array.
Example
Basic usage: read the early access names
import android.util.Log;
import com.contentstack.sdk.Config;
import java.util.Arrays;
Config config = new Config().earlyAccess(new String[] {"taxonomy", "teams"});
String[] names = config.getEarlyAccess();
if (names != null) {
Log.d("Contentstack", "Early access: " + Arrays.toString(names));
}getEnvironment
getEnvironment returns the publishing environment that Contentstack.stack stored on the Config.
Returns: String. The environment of the stack, or null before the stack exists.
Validation
- There is no client-side validation. getEnvironment reads a stored value and does not throw.
Behavior
- Config has no public method that sets the environment. Contentstack.stack writes its environment argument into the Config you pass.
- Before that call, getEnvironment returns null.
- When the environment argument is an empty string, Contentstack.stack leaves the stored value unchanged.
Example
Basic usage: read the environment after creating the stack
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Log.d("Contentstack", "Environment: " + config.getEnvironment());
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}getHost
getHost returns the host name stored on the Config, without a scheme.
Returns: String. The host name of the Content Delivery API.
Validation
- There is no client-side validation. getHost reads a stored value and does not throw.
Behavior
- Before you create the stack, getHost returns the value from setHost, or cdn.contentstack.io when you did not call it. A region from setRegion does not change this value yet.
- Contentstack.stack writes the host it chose back into the Config. After that call, getHost returns the host the stack uses, for example eu-cdn.contentstack.com for the EU region.
- The value has no https:// prefix and no version path.
Example
Basic usage: read the host before and after creating the stack
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Stack;
new Thread(() -> {
try {
Config config = new Config();
config.setRegion(Config.ContentstackRegion.AU);
Log.d("Contentstack", "Before: " + config.getHost());
// Off the main thread, the SDK can download its region list
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Log.d("Contentstack", "After: " + config.getHost());
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}
}).start();getProxy
getProxy returns the proxy stored on the Config.
Returns: Proxy. The proxy set on the config, or null.
Validation
- There is no client-side validation. getProxy reads a stored value and does not throw.
Behavior
- getProxy returns null until you call setProxy, and the java.net.Proxy you passed after that.
- Only Taxonomy requests and the region list download use the proxy. Entry, query, asset, content type, global field, and sync requests ignore it. See the setProxy method for details.
Example
Basic usage: read the proxy
import android.util.Log;
import com.contentstack.sdk.Config;
import java.net.InetSocketAddress;
import java.net.Proxy;
Config config = new Config();
config.setProxy(new Proxy(Proxy.Type.HTTP, InetSocketAddress.createUnresolved("proxy.example.com", 8080)));
Proxy proxy = config.getProxy();
if (proxy != null) {
Log.d("Contentstack", "Proxy: " + proxy.type() + " " + proxy.address());
}getRegion
getRegion returns the region stored on the Config.
Returns: ContentstackRegion. The region set on the config.
Validation
- There is no client-side validation. getRegion reads a stored value and does not throw.
Behavior
- getRegion returns ContentstackRegion.US until you call setRegion, and the value you passed after that.
- The region shows what you configured, not the host the stack uses. A host set with setHost wins over the region. Use the getHost method to read the host.
- The seven ContentstackRegion values are US, EU, AU, AZURE_NA, AZURE_EU, GCP_NA and GCP_EU. See the setRegion method for the Content Delivery host of each.
Example
Basic usage: read the region
import android.util.Log;
import com.contentstack.sdk.Config;
Config config = new Config();
Log.d("Contentstack", "Default region: " + config.getRegion());
config.setRegion(Config.ContentstackRegion.GCP_EU);
Log.d("Contentstack", "Region: " + config.getRegion());getVersion
getVersion returns the Content Delivery API version that the SDK puts in every request path.
Returns: String. The API version in request paths.
Validation
- There is no client-side validation. getVersion reads a stored value and does not throw.
Behavior
- getVersion always returns v3. The SDK has no public method that changes the version.
- The SDK builds each request URL as https:// plus the host plus /v3/ and the request path, for example /v3/content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID> for the Get a single entry request.
Example
Basic usage: read the API version
import android.util.Log;
import com.contentstack.sdk.Config;
Config config = new Config();
Log.d("Contentstack", "API version: " + config.getVersion());setBranch
setBranch makes the stack read content from one branch of the stack.
| Name | Type | Description |
|---|---|---|
| branch (required) | String | UID of the branch to read content from. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. setBranch stores the value as given.
- setBranch accepts null and an empty string, and the SDK then sends no branch header.
- A branch that does not exist surfaces as an Error in the callback of the first request, for example fetch on an entry.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Contentstack.stack adds the value as the branch header of every request from the stack. The Get a single entry request and the other Content Delivery API requests take the branch UID in this header.
- Call setBranch before Contentstack.stack. A call afterwards does not change the stack.
- The Config class has no public method that reads the branch back.
Example
Basic usage: read an entry from a branch
import android.util.Log;
import com.contentstack.sdk.Config;
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;
try {
Config config = new Config();
config.setBranch("<BRANCH>");
config.setHost("cdn.contentstack.io"); // your region's host, see setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
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) {
Log.d("Contentstack", entry.getTitle());
} 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());
}setHost
setHost sets the host name that every request from the stack goes to, in place of the region's host.
| Name | Type | Description |
|---|---|---|
| hostName (required) | String | Host name without a scheme, such as eu-cdn.contentstack.com. |
Returns: void. This method returns nothing.
Validation
- setHost ignores null and an empty string. The Config keeps its earlier host and still looks up the region's host.
- There is no other client-side validation. A host that does not serve the Content Delivery API surfaces as an Error in the callback of the first request, for example fetch on an entry.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- The SDK builds each request URL as https:// plus the host plus /v3/ and the request path. Pass the host name only. A value that starts with https:// produces a URL with two schemes.
- A host set with setHost always wins over the region, and Contentstack.stack then skips the region lookup. This avoids the region list download that the setRegion method describes in its Known issue.
- The SDK uses the host for every request from the stack, including Taxonomy requests.
- Use the Endpoint.getContentstackEndpoint method with omitHttps set to true to get the host of a region in this form.
- Use the getHost method to read the value back.
Example
Basic usage: send requests to the EU host
import android.util.Log;
import com.contentstack.sdk.Config;
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;
try {
Config config = new Config();
config.setHost("eu-cdn.contentstack.com");
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
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) {
Log.d("Contentstack", entry.getTitle());
} 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());
}setProxy
setProxy routes Taxonomy requests and the region list download through a proxy server.
| Name | Type | Description |
|---|---|---|
| proxy (required) | Proxy | java.net.Proxy with the proxy type and address. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. setProxy stores the Proxy as given.
- setProxy accepts null, which clears a proxy that an earlier call set.
- A proxy that cannot reach Contentstack makes the next Taxonomy request fail. The Taxonomy class page describes the form that failure takes.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- The proxy applies only to the traffic in the list below:
- requests from Taxonomy
- the download of the region list when Contentstack.stack looks up the region's host
- Entry, query, asset, content type, global field, and sync requests ignore the proxy.
- Call setProxy before Contentstack.stack. The SDK builds the Taxonomy HTTP client when it creates the stack, so a later call does not change it.
- Use the getProxy method to read the value back.
Example
Basic usage: route Taxonomy requests through an HTTP proxy
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 org.json.JSONObject;
import java.net.InetSocketAddress;
import java.net.Proxy;
new Thread(() -> {
try {
Config config = new Config();
config.setProxy(new Proxy(Proxy.Type.HTTP, InetSocketAddress.createUnresolved("proxy.example.com", 8080)));
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
// Taxonomy.find runs on the calling thread, so it stays inside this background thread
stack.taxonomy().exists("taxonomies.<TAXONOMY_UID>", true).find((JSONObject response, Error error) -> {
if (error == null) {
Log.d("Contentstack", response.toString());
} else {
// The API rejected the request
Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " " + error.getErrorMessage());
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null, and find throws on a network failure
Log.e("Contentstack", "Request failed: " + e.getMessage());
}
}).start();setRegion
setRegion sets the Contentstack region whose Content Delivery host the stack sends requests to.
| Name | Type | Description |
|---|---|---|
| region (required) | Config.ContentstackRegion | Region that hosts your stack. |
Returns: ContentstackRegion. The region you passed.
Validation
- There is no client-side validation in setRegion.
- Passing null makes Contentstack.stack throw NullPointerException, because the SDK reads the region name when it creates the stack.
- A region that does not match your stack surfaces as an Error in the callback of the first request, for example fetch on an entry.
Known issue In 4.4.0, the SDK package does not include its region list, so Contentstack.stack downloads the list on the calling thread to find the region's host. On the main thread Android blocks the download, and Contentstack.stack throws IllegalStateException, then throws it again on every later call in the process. Also call setHost with the host from the table below, or create the stack on a background thread.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Config.ContentstackRegion is an enum nested in Config. It has these seven values, each with the Content Delivery host that Contentstack.stack looks up:
| Value | Region | Content Delivery host |
|---|---|---|
| US (default) | AWS North America | cdn.contentstack.io |
| EU | AWS Europe | eu-cdn.contentstack.com |
| AU | AWS Australia | au-cdn.contentstack.com |
| AZURE_NA | Azure North America | azure-na-cdn.contentstack.com |
| AZURE_EU | Azure Europe | azure-eu-cdn.contentstack.com |
| GCP_NA | GCP North America | gcp-na-cdn.contentstack.com |
| GCP_EU | GCP Europe | gcp-eu-cdn.contentstack.com |
- setRegion only stores the value. Contentstack.stack reads it and looks up the host through the region list that the Endpoint class page describes.
- A host set with setHost wins over the region. With a custom host, the region has no effect.
- setRegion returns the region, not the Config, so you cannot chain another Config call after it.
- Use the getRegion method to read the value back.
Example
Basic usage: send requests to the EU region
import android.util.Log;
import com.contentstack.sdk.Config;
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;
new Thread(() -> {
try {
Config config = new Config();
config.setRegion(Config.ContentstackRegion.EU);
// Off the main thread, the SDK can download its region list
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
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) {
Log.d("Contentstack", entry.getTitle());
} 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 or the region lookup fails
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}
}).start();Edge case: set the region and its host to skip the lookup
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setRegion(Config.ContentstackRegion.AZURE_NA);
// A custom host wins over the region and skips the region lookup
config.setHost("azure-na-cdn.contentstack.com");
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
Log.d("Contentstack", config.getRegion() + " " + config.getHost());
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}