Asset
Asset
An asset is a file, for example an image, video, PDF or audio file, that a stack stores in its repository. The Asset class reads one published asset. Use this class to
- fetch one published asset by its UID
- read a file field from an entry you already fetched, with no extra request
- read the file name, URL, size, MIME type, tags and timestamps of an asset
stack.asset("<ASSET_UID>") returns the object. See the asset method.
addParam
addParam adds one query parameter that fetch sends with the request.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | String | Value of the query parameter. |
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation of the parameter name or value.
- addParam ignores the call when key or value is null.
- An invalid value surfaces as an Error in the callback when fetch sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. addParam stores the pair and makes no request. fetch sends it as key=value in the query string.
- A second call with the same key replaces the value.
- fetch writes the stack's environment after your parameters, so an environment key that you store here does not reach the request when the stack has an environment.
- Use addParam for a parameter that has no dedicated method, for example include_metadata from the Get a single asset request. The API returns the metadata under the _metadata key, which you read from toJSON.
- The SDK does not URL-encode value. Encode a value that contains & or # with java.net.URLEncoder before you pass it. See Query parameters on the Asset class page.
Example
Basic usage: request the asset metadata
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.addParam("include_metadata", "true");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "Metadata: " + asset.toJSON().optJSONObject("_metadata"));
} 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());
}configure
configure fills the asset from the JSON of one asset, for example the value of a file field in an entry, without a request.
| Name | Type | Description |
|---|---|---|
| jsonObject (required) | JSONObject | JSON of one asset, such as a file field value. |
Returns: Asset. The same asset, holding the given file data.
Validation
- Throws NullPointerException if jsonObject is null, because configure reads the asset fields from it without a null check.
- There is no other client-side validation. A JSON object without asset keys leaves the getters returning null.
Behavior
- Client-side only. configure makes no request.
- configure reads six keys from the object: uid, content_type, file_size, filename, url and tags.
- The asset keeps the whole object for toJSON and for the time and user getters.
- The values replace every value the asset held, including the UID you passed to stack.asset.
- Pass the asset object itself, not a response that wraps it in an asset key.
- The getAsset and getAssets methods on Entry call configure for a file field and return the filled assets.
Example
Basic usage: read a file field from a fetched entry
import android.util.Log;
import com.contentstack.sdk.Asset;
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;
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);
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) {
// "banner_image" is the UID of a file field in the content type
JSONObject file = entry.getJSONObject("banner_image");
if (file == null) {
Log.d("Contentstack", "The entry has no banner image");
return;
}
Asset asset = stack.asset(file.optString("uid")).configure(file);
Log.d("Contentstack", "Banner: " + asset.getFileName() + " at " + asset.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());
}fetch
fetch retrieves one published asset by its UID and fills the asset with its data.
| Name | Type | Description |
|---|---|---|
| callback (required) | FetchResultCallback | Receives the result when the request ends. |
Returns: void. The result arrives in the callback.
Validation
- There is no client-side validation of the asset UID. The SDK places the UID you passed to stack.asset in the request path as given.
- fetch does not throw when the API rejects the request or the network fails.
- onCompletion receives a non-null Error instead.
- Check error inside the callback before you read the asset, even when the call sits inside a try block.
- With a null callback, fetch sends no network request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- fetch sends GET /assets/{asset_uid}, the Get a single asset request.
- The request carries every query parameter that addParam, includeDimension, includeFallback, includeBranch and setLocale stored, plus the stack's environment as the environment query parameter.
- onCompletion(ResponseType responseType, Error error) fires when the request ends.
- On success error is null, and the getters return the fetched values. responseType is NETWORK for a network result.
- On failure error holds the status, code and message.
- The fetched values replace every value the asset held, including the UID.
- The cache policy decides whether fetch sends a request. The default IGNORE_CACHE always sends one. See the setCachePolicy method.
Example
Basic usage: fetch an asset and log its details
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "File: " + asset.getFileName() + " at " + asset.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());
}Request options: fetch a localized asset with dimensions and branch details
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.setLocale("<LOCALE>")
.includeFallback()
.includeDimension()
.includeBranch();
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error != null) {
Log.e("Contentstack", error.getErrorMessage());
return;
}
Log.d("Contentstack", "Asset JSON: " + asset.toJSON());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}getAssetUid
getAssetUid returns the UID of the asset.
Returns: String. The asset's UID.
Validation
- There is no client-side validation. getAssetUid reads a value the asset already holds and makes no request.
Behavior
- Before the asset holds data, getAssetUid returns the UID you passed to stack.asset.
- After fetch or configure, it returns the uid value from the asset JSON.
Example
Basic usage: read the asset UID after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "UID: " + asset.getAssetUid());
} 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());
}getCreateAt
getCreateAt returns the creation time of the asset, as a Calendar.
Returns: Calendar. The asset's creation time.
Validation
- There is no client-side validation. getCreateAt reads a value the asset already holds and makes no request.
Behavior
- getCreateAt parses the created_at value after fetch or configure fills the asset.
- It returns null when the asset does not hold data yet, when the JSON has no created_at value, or when the SDK cannot parse the value.
Known issue The Calendar holds the UTC date and time from the response but carries the device's time zone, so getTimeInMillis() is off by the device's UTC offset. To get the exact instant, parse toJSON().optString("created_at") yourself with a SimpleDateFormat set to the UTC time zone.
Example
Basic usage: read the creation time after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.Calendar;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Calendar value = asset.getCreateAt();
if (value != null) {
Log.d("Contentstack", "created_at: " + value.getTime());
}
} 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());
}getCreatedBy
getCreatedBy returns the UID of the user who created the asset.
Returns: String. The UID of the user who created the asset.
Validation
- There is no client-side validation. getCreatedBy makes no request.
- Throws NullPointerException if the asset does not hold data yet, because getCreatedBy reads the asset JSON without a null check. Call it inside the onCompletion callback of fetch, or after configure.
Behavior
- getCreatedBy returns the created_by value after fetch or configure fills the asset.
- It returns an empty string when the JSON has no created_by value.
Example
Basic usage: read the creator UID after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "created_by: " + asset.getCreatedBy());
} 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());
}getDeleteAt
getDeleteAt returns the deleted_at time of the asset, as a Calendar.
Returns: Calendar. The asset's deletion time.
Validation
- There is no client-side validation. getDeleteAt reads a value the asset already holds and makes no request.
Behavior
- getDeleteAt parses the deleted_at value after fetch or configure fills the asset.
- It returns null when the asset does not hold data yet, when the JSON has no deleted_at value, or when the SDK cannot parse the value.
Known issue The Calendar holds the UTC date and time from the response but carries the device's time zone, so getTimeInMillis() is off by the device's UTC offset. To get the exact instant, parse toJSON().optString("deleted_at") yourself with a SimpleDateFormat set to the UTC time zone.
Example
Basic usage: read the deletion time after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.Calendar;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Calendar value = asset.getDeleteAt();
if (value != null) {
Log.d("Contentstack", "deleted_at: " + value.getTime());
}
} 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());
}getDeletedBy
getDeletedBy returns the deleted_by value of the asset.
Returns: String. The UID of the user who deleted the asset.
Validation
- There is no client-side validation. getDeletedBy makes no request.
- Throws NullPointerException if the asset does not hold data yet, because getDeletedBy reads the asset JSON without a null check. Call it inside the onCompletion callback of fetch, or after configure.
Behavior
- getDeletedBy returns the deleted_by value after fetch or configure fills the asset.
- It returns an empty string when the JSON has no deleted_by value.
Example
Basic usage: read the deleter UID after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "deleted_by: " + asset.getDeletedBy());
} 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());
}getFileName
getFileName returns the file name of the asset.
Returns: String. The asset's file name.
Validation
- There is no client-side validation. getFileName reads a value the asset already holds and makes no request.
Behavior
- getFileName returns the filename value after fetch or configure fills the asset.
- It returns null before the asset holds data.
Example
Basic usage: read the file name after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "File name: " + asset.getFileName());
} 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());
}getFileSize
getFileSize returns the size of the file in bytes.
Returns: String. The asset's file size in bytes, as a string.
Validation
- There is no client-side validation. getFileSize reads a value the asset already holds and makes no request.
Behavior
- getFileSize returns the file_size value after fetch or configure fills the asset.
- The value is a String. Convert it with Long.parseLong to compare sizes.
- It returns null before the asset holds data.
Example
Basic usage: read the file size after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "Size in bytes: " + asset.getFileSize());
} 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());
}getFileType
getFileType returns the MIME type of the file, for example image/jpeg.
Returns: String. The asset's MIME type.
Validation
- There is no client-side validation. getFileType reads a value the asset already holds and makes no request.
Behavior
- getFileType returns the content_type value after fetch or configure fills the asset.
- It returns null before the asset holds data.
Example
Basic usage: read the MIME type after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "MIME type: " + asset.getFileType());
} 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());
}getTags
getTags returns the tags on the asset.
Returns: String[]. The asset's tags.
Validation
- There is no client-side validation. getTags reads a value the asset already holds and makes no request.
Behavior
- getTags returns the tags array after fetch or configure fills the asset.
- It returns null, not an empty array, when the asset has no tags or does not hold data yet.
Example
Basic usage: read the tags after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.Arrays;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
String[] tags = asset.getTags();
if (tags == null) {
Log.d("Contentstack", "The asset has no tags");
} else {
Log.d("Contentstack", "Tags: " + Arrays.toString(tags));
}
} 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());
}getUpdateAt
getUpdateAt returns the time of the last change to the asset, as a Calendar.
Returns: Calendar. The asset's last update time.
Validation
- There is no client-side validation. getUpdateAt reads a value the asset already holds and makes no request.
Behavior
- getUpdateAt parses the updated_at value after fetch or configure fills the asset.
- It returns null when the asset does not hold data yet, when the JSON has no updated_at value, or when the SDK cannot parse the value.
Known issue The Calendar holds the UTC date and time from the response but carries the device's time zone, so getTimeInMillis() is off by the device's UTC offset. To get the exact instant, parse toJSON().optString("updated_at") yourself with a SimpleDateFormat set to the UTC time zone.
Example
Basic usage: read the last update time after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
import java.util.Calendar;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Calendar value = asset.getUpdateAt();
if (value != null) {
Log.d("Contentstack", "updated_at: " + value.getTime());
}
} 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());
}getUpdatedBy
getUpdatedBy returns the UID of the user who last changed the asset.
Returns: String. The UID of the user who last updated the asset.
Validation
- There is no client-side validation. getUpdatedBy makes no request.
- Throws NullPointerException if the asset does not hold data yet, because getUpdatedBy reads the asset JSON without a null check. Call it inside the onCompletion callback of fetch, or after configure.
Behavior
- getUpdatedBy returns the updated_by value after fetch or configure fills the asset.
- It returns an empty string when the JSON has no updated_by value.
Example
Basic usage: read the last updater UID after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "updated_by: " + asset.getUpdatedBy());
} 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 the URL that serves the file.
Returns: String. The asset's file URL.
Validation
- There is no client-side validation. getUrl reads a value the asset already holds and makes no request.
Behavior
- getUrl returns the url value after fetch or configure fills the asset.
- It returns null before the asset holds data.
- Pass the URL to the ImageTransform method on Stack to build a resized or converted image URL.
Example
Basic usage: read the file URL after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "URL: " + asset.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());
}includeBranch
includeBranch asks the API to add the _branch key, which names the branch that holds the asset.
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation.
- An invalid value surfaces as an Error in the callback when fetch 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, and fetch sends it.
- The Get a single asset request describes _branch as a top-level key of the response that holds the unique ID of the branch.
- The asset keeps the asset object of the response, which toJSON returns.
- includeBranch does not choose a branch. Set the branch for the stack with the setBranch method on Config.
Example
Basic usage: add branch details to the response
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.includeBranch();
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "Asset JSON: " + asset.toJSON());
} 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());
}includeDimension
includeDimension asks the API to add the height and width of an image asset to the response.
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation.
- An invalid value surfaces as an Error in the callback when fetch sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeDimension stores include_dimension=true, and fetch sends it.
- The Get a single asset request lists the supported image types: JPG, GIF, PNG, WebP, BMP, TIFF, SVG, and PSD.
- The SDK has no getter for the dimensions. Read them from the JSONObject that toJSON returns.
Example
Basic usage: fetch an image with its dimensions
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.includeDimension();
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "Asset JSON: " + asset.toJSON());
} 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());
}includeFallback
includeFallback asks the API to return the fallback-locale version of the asset when the requested locale has no published version.
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation.
- An invalid value surfaces as an Error in the callback when fetch sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeFallback stores include_fallback=true, and fetch sends it.
- Per the Get a single asset request, the API then returns the published asset details from the fallback locale when the specified locale holds no published content.
- Set the requested locale with the setLocale method.
Example
Basic usage: fetch a localized asset with fallback
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.setLocale("<LOCALE>").includeFallback();
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "File: " + asset.getFileName());
} 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());
}removeHeader
removeHeader removes one request header that the setHeader method set on this asset.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header to remove. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation of the header name.
- removeHeader ignores a null or empty key, and a key that the asset does not hold.
Behavior
- Client-side only. removeHeader changes the headers that fetch sends for this asset.
- removeHeader removes only headers set on the asset. It cannot remove a stack header such as environment or access_token.
- Use the removeHeader method on Stack to remove a stack header.
Example
Basic usage: drop a header before the request
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.setHeader("branch", "<BRANCH>");
asset.removeHeader("branch");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "File: " + asset.getFileName());
} 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());
}setCachePolicy
setCachePolicy sets where fetch reads this asset from: the network, the SDK's disk cache, or both.
| Name | Type | Description |
|---|---|---|
| cachePolicy (required) | CachePolicy | Where fetch reads the asset from. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation.
- A null policy makes the next fetch call onCompletion with an Error and ResponseType.UNKNOWN, and fetch sends no request.
Behavior
- The default policy is IGNORE_CACHE. setCachePolicy changes the policy for this asset only.
- The table below lists what fetch does for each CachePolicy value:
| Value | What fetch does |
|---|---|
| IGNORE_CACHE | Sends the request. This is the default. |
| NETWORK_ONLY | Sends the request. |
| CACHE_ONLY | Reads the cache and sends no request. |
| CACHE_ELSE_NETWORK | Reads the cache when the cached response is less than 60 seconds old, and sends the request otherwise. |
| CACHE_THEN_NETWORK | Reads the cache when a cached response exists, then sends the request. |
| NETWORK_ELSE_CACHE | Sends the request when the device has a connection, and reads the cache otherwise. |
- IGNORE_CACHE and NETWORK_ONLY behave the same. Both send the request and save the response in the SDK's cache.
- responseType in onCompletion names the source of the result: NETWORK, CACHE or UNKNOWN.
Known issue fetch cannot read an asset from the cache. When a policy finds a cached response for the asset, onCompletion receives an Error instead of the cached asset, and with CACHE_THEN_NETWORK no network request follows. Keep the default IGNORE_CACHE, or use NETWORK_ONLY.
Example
Basic usage: always fetch from the network
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.CachePolicy;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.setCachePolicy(CachePolicy.NETWORK_ONLY);
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "Source: " + responseType + ", file: " + asset.getFileName());
} 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());
}setHeader
setHeader adds one request header that fetch sends for this asset only.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header. |
| value (required) | String | Value of the header. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation of the header name or value.
- setHeader ignores the call when key or value is null or empty.
Behavior
- Client-side only. setHeader stores the header on this asset, and fetch sends it.
- A header set on the asset overrides a stack header with the same name, for this asset only.
- A second call with the same key replaces the value.
- Use the setHeader method on Stack to send a header with every request.
Example
Basic usage: fetch the asset from another branch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
// Overrides the stack's branch header for this asset only
asset.setHeader("branch", "<BRANCH>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "File: " + asset.getFileName());
} 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());
}setLocale
setLocale sets the locale that fetch requests the asset in.
| Name | Type | Description |
|---|---|---|
| locale (required) | String | Locale code to fetch, such as fr-fr. |
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation of the locale code.
- setLocale ignores a null value.
- An invalid value surfaces as an Error in the callback when fetch sends the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. setLocale stores the locale query parameter, and fetch sends it.
- A second call replaces the locale.
- Add the includeFallback method to get the fallback-locale version when the asset has no published version in this locale.
Example
Basic usage: fetch an asset in one locale
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.setLocale("<LOCALE>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
Log.d("Contentstack", "File: " + asset.getFileName() + " at " + asset.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());
}toJSON
toJSON returns every field of the asset as a JSONObject.
Returns: JSONObject. The asset's raw JSON data.
Validation
- There is no client-side validation. toJSON reads a value the asset already holds and makes no request.
Behavior
- After fetch, toJSON returns the asset object of the response. After configure, it returns the object you passed.
- It returns null before the asset holds data.
- Use it for values that have no getter, for example the image dimensions from includeDimension or _metadata.
- toJSON returns the object the asset holds, not a copy. A change to it changes what the time and user getters read.
Example
Basic usage: read the raw asset JSON after fetch
import android.util.Log;
import com.contentstack.sdk.Asset;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.FetchResultCallback;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;
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);
Asset asset = stack.asset("<ASSET_UID>");
asset.fetch(new FetchResultCallback() {
@Override
public void onCompletion(ResponseType responseType, Error error) {
if (error == null) {
JSONObject json = asset.toJSON();
Log.d("Contentstack", "Title: " + json.optString("title"));
} 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());
}