Folder

View as Markdown

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:

NameTypeDescription
folderUidStringUID 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.

NameTypeDescription
key (required)String

Name of the request header.

Default: Not applicable
value (required)String

Value of the request header.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap<String, String>

Header names and values to add.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)Object

Value of the query parameter.

Default: Not applicable

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.

NameTypeDescription
params (required)HashMap<String, Object>

Query parameter names and values to add.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the folder under an asset key.

Default: Not applicable
requestBody.asset.name (required)String

Name of the new folder.

Default: Not applicable
requestBody.asset.parent_uidString

UID of the parent folder.

Default: API default (root)

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.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the folder under an asset key.

Default: Not applicable
requestBody.asset.name (required)String

New name of the folder.

Default: Not applicable
requestBody.asset.parent_uidString

UID of the folder to move this folder into.

Default: API default

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