Folder
Folder
An asset folder groups assets in a stack. Use this class to
- create an asset folder, at the root or inside another folder
- fetch one folder, with its full path if you need it
- rename a folder or move it under another folder
- delete a folder and the assets in it
The folder method on Asset returns a new Folder. It has two forms:
| Name | Type | Description |
|---|---|---|
| folderUid | String | UID of the folder. Omit it to create a folder. |
Additional Resource The Asset Folder Collection requests in the Assets section of the Content Management API (CMA) reference describe each folder request and its response.
addHeader
addHeader adds one request header to the requests that this folder object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the request header. |
| value (required) | String | Value of the request header. |
Returns: Folder. The same folder, for chaining.
Validation
- There is no client-side validation. addHeader stores any key and value.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
- A null key or value passes here. execute() then throws IllegalArgumentException on the next request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeader stores the header on this folder object and makes no request.
- Every request method on this folder object sends every stored header.
- asset.folder() copies the headers of the asset into the new object. addHeader changes only this object, not the stack or other objects.
- A second call with the same key replaces the first value, including a header the stack set, such as authorization or branch.
Example
Basic usage: fetch a folder from another branch
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchFolderOnBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>")
.addHeader("branch", "<BRANCH>");
Response<ResponseBody> response = folder.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeaders
addHeaders adds several request headers at once to the requests that this folder object sends.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names and values to add. |
Returns: Folder. The same folder, for chaining.
Validation
- Throws NullPointerException when the map is null, because addHeaders copies its entries.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeaders copies every pair into the headers of this folder object and makes no request.
- Every request method on this folder object sends every stored header.
- A key that already exists takes the new value, including a header the stack set, such as authorization or branch.
Example
Basic usage: add headers from a map
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class FetchFolderWithHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, String> headers = new HashMap<>();
headers.put("branch", "<BRANCH>");
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>").addHeaders(headers);
Response<ResponseBody> response = folder.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParam
addParam adds one query parameter to the requests that this folder object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | Object | Value of the query parameter. |
Returns: Folder. The same folder, for chaining.
Validation
- There is no client-side validation. addParam stores any key and value.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
- A null key or value passes here. execute() then throws IllegalArgumentException on a request that sends query parameters.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParam stores the pair on this folder object and makes no request.
- fetch, create, and update send every stored parameter. delete does not send them.
- The SDK writes the value with its toString() method. Pass a JSONObject for a JSON value such as query, because its toString() returns JSON.
- A second call with the same key replaces the first value. The parameter stays on the object for every later request until removeParam removes it.
Example
Basic usage: include the folder path when you fetch a folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchFolderPath {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>")
.addParam("include_path", true);
Response<ResponseBody> response = folder.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParams
addParams adds several query parameters at once to the requests that this folder object sends.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Query parameter names and values to add. |
Returns: Folder. The same folder, for chaining.
Validation
- Throws NullPointerException when the map is null, because addParams copies its entries.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParams copies every pair into the query parameters of this folder object and makes no request.
- fetch, create, and update send every stored parameter. delete does not send them.
- A key that already exists takes the new value. Keys that are not in the map keep their values.
Example
Basic usage: add the folder path and branch details in one call
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class FetchFolderWithParams {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, Object> params = new HashMap<>();
params.put("include_path", true);
params.put("include_branch", true);
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>").addParams(params);
Response<ResponseBody> response = folder.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}create
create builds the request that creates an asset folder, at the root of the stack or inside a parent folder.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the folder under an asset key. |
| requestBody.asset.name (required) | String | Name of the new folder. |
| requestBody.asset.parent_uid | String | UID of the parent folder. |
Returns: Call<ResponseBody>. The request for the new folder, sent when you call execute().
Validation
- There is no client-side validation. create does not check requestBody.
- execute() throws IllegalArgumentException when requestBody is null, because the request needs a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Create a folder request (POST /v3/assets/folders) with requestBody as the JSON body and the query parameters on this object.
- Without parent_uid, the API creates the folder at the root of the stack.
- The API reference sets a maximum of 300 folders and five levels of nesting.
- The response body is the raw JSON from the API, with the new folder under an asset key. Read its uid to work on the folder later.
- create does not use a folder UID, so it works on asset.folder() and on asset.folder("<FOLDER_UID>") alike. The new folder does not go inside the folder whose UID the object holds unless you pass that UID as parent_uid.
Example
Basic usage: create a folder at the root of the stack
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateRootFolder {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder();
JSONObject details = new JSONObject();
details.put("name", "docs-test-images");
JSONObject requestBody = new JSONObject();
requestBody.put("asset", details);
Response<ResponseBody> response = folder.create(requestBody).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: create a folder inside a parent folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateNestedFolder {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder();
JSONObject details = new JSONObject();
details.put("name", "docs-test-banners");
details.put("parent_uid", "<FOLDER_UID>");
JSONObject requestBody = new JSONObject();
requestBody.put("asset", details);
Response<ResponseBody> response = folder.create(requestBody).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}delete
delete builds the request that deletes one asset folder together with every asset inside it.
Returns: Call<ResponseBody>. The request for the deletion notice, sent when you call execute().
Validation
- Throws IllegalAccessError when the folder has no UID or an empty UID, because the request path needs one. Create the object with asset.folder("<FOLDER_UID>").
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
Warning delete removes the folder and all the assets in it, not only the folder. The folder requests in the API reference include no restore request. Move the assets you want to keep out of the folder before you delete it.
- One execute() sends one Delete a folder request (DELETE /v3/assets/folders/{folder_uid}) with the headers on this object.
- delete does not send the query parameters from addParam.
- The response body is the raw JSON from the API, with a notice message.
Example
Basic usage: delete a folder and its assets
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteFolder {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>");
Response<ResponseBody> response = folder.delete().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}fetch
fetch builds the request that retrieves one asset folder by its UID.
Returns: Call<ResponseBody>. The request for the folder, sent when you call execute().
Validation
- Throws IllegalAccessError when the folder has no UID or an empty UID, because the request path needs one. Create the object with asset.folder("<FOLDER_UID>").
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get a single folder request (GET /v3/assets/folders/{folder_uid}) with the headers and query parameters on this object.
- The API reference lists the following two query parameters for this request. Add them with addParam:
- include_path: true adds a path array with the name and UID of each parent folder.
- include_branch: true adds the _branch key to the response.
- The response body is the raw JSON from the API, with the folder under an asset key. A folder carries is_dir set to true and a name instead of a file name.
Example
Basic usage: fetch one folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchFolder {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>");
Response<ResponseBody> response = folder.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Full path: fetch a nested folder with the names of its parent folders
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchFolderWithPath {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>")
.addParam("include_path", true)
.addParam("include_branch", true);
Response<ResponseBody> response = folder.fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}removeParam
removeParam removes one query parameter from this folder object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter to remove. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. A key that the object does not hold changes nothing, and removeParam does not throw.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. removeParam deletes the parameter from this folder object and makes no request.
- Later requests from fetch, create, and update no longer send the parameter.
- removeParam returns nothing, so call it as its own statement, not in a chain.
Example
Basic usage: drop a parameter before the next request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveFolderParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>")
.addParam("include_path", true)
.addParam("include_branch", true);
folder.removeParam("include_branch");
Response<ResponseBody> response = folder.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}update
update builds the request that renames an asset folder or moves it under another folder.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the folder under an asset key. |
| requestBody.asset.name (required) | String | New name of the folder. |
| requestBody.asset.parent_uid | String | UID of the folder to move this folder into. |
Returns: Call<ResponseBody>. The request for the updated folder, sent when you call execute().
Validation
- Throws IllegalAccessError when the folder has no UID or an empty UID, because the request path needs one. Create the object with asset.folder("<FOLDER_UID>").
- execute() throws IllegalArgumentException when requestBody is null, because the request needs a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Update or move folder request (PUT /v3/assets/folders/{folder_uid}) with requestBody as the JSON body and the query parameters on this object.
- parent_uid moves the folder. The folder cannot move inside itself or inside one of its child folders, and the API reference sets a maximum of five levels of nesting.
- The response body is the raw JSON from the API, with the updated folder under an asset key.
Example
Basic usage: rename a folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class RenameFolder {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>");
JSONObject details = new JSONObject();
details.put("name", "Product images");
JSONObject requestBody = new JSONObject();
requestBody.put("asset", details);
Response<ResponseBody> response = folder.update(requestBody).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: rename a folder and move it under another folder
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Folder;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class MoveFolder {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Folder folder = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").asset().folder("<FOLDER_UID>");
// Pass the UID of the destination folder as the first program argument
String parentUid = args[0];
JSONObject details = new JSONObject();
details.put("name", "Archived banners");
details.put("parent_uid", parentUid);
JSONObject requestBody = new JSONObject();
requestBody.put("asset", details);
Response<ResponseBody> response = folder.update(requestBody).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}