Taxonomy

View as Markdown

Taxonomy

A taxonomy arranges the content of a stack into a hierarchy of terms that entries carry. Use this class to return the published entries that

  • carry one of several terms
  • carry a term, its descendants, or its ancestors
  • carry any term of a taxonomy
  • match a combination of these conditions with AND or OR

The taxonomy method on the stack returns the object and takes no arguments. Chain one or more filter methods on it, then call find. The class does not list taxonomies or read one taxonomy or term.

above

above matches entries tagged with any term above a given term, but not with the term itself.

NameTypeDescription
taxonomy (required)String

Field path, such as taxonomies.<TAXONOMY_UID>.

Default: Not applicable
termUid (required)String

UID of the term to start from.

Default: Not applicable

Returns: Taxonomy. The same taxonomy filter, for chaining.

Validation

  • above throws NullPointerException if taxonomy is null, or if termUid is null while taxonomy is not empty, because it calls isEmpty() on each value.
  • When taxonomy or termUid is empty, above records nothing and raises no error. find then sends the query without this condition.
  • There is no other client-side validation. Errors that do occur come from the find call that follows, not from above.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. above records the condition {"$above": "<TERM_UID>"} under the field path and sends no request.
  • find sends the condition in the shape that the Above Operator section describes. The API returns entries tagged with an ancestor of the term. An entry tagged only with the term itself does not match.
  • above sends no levels key, so the API matches terms up to its default depth of 10 levels. See Hierarchy depth on the Taxonomy class page.
  • A later in, exists, or hierarchy condition on the same field path replaces this one.
  • Use the equalAbove method to include entries tagged with the term itself.
  • Use the below method to match the descendants instead.

Example

Basic usage: match the terms above a term

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
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);
    Taxonomy taxonomy = stack.taxonomy().above("taxonomies.<TAXONOMY_UID>", "<TERM_UID>");

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

and

and matches entries that satisfy every one of the given taxonomy conditions.

NameTypeDescription
listOfItems (required)List<JSONObject>

Conditions to combine, one JSONObject each.

Default: Not applicable

Returns: Taxonomy. The same taxonomy filter, for chaining.

Validation

  • When listOfItems is null, and records nothing and raises no error.
  • and does not check the conditions inside the list. An empty list records an empty $and array.
  • There is no other client-side validation. Errors that do occur come from the find call that follows, not from and.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. and records the list under the $and key and sends no request.
  • find sends the condition in the shape that the AND Operator (Taxonomy) section describes. The API returns entries that satisfy every condition in the list.
  • Build each condition as a JSONObject with one field path and one value, such as {"taxonomies.color": "black"}. A value can also be an operator object, such as {"$in": [...]}.
  • A second call to and on the same instance replaces the whole list.
  • Use the or method to accept any one condition instead.

Example

Basic usage: match entries tagged both black and small

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
import org.json.JSONObject;

import java.util.Arrays;
import java.util.List;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    // JSONObject.put throws JSONException, which the outer catch handles
    JSONObject color = new JSONObject();
    color.put("taxonomies.color", "black");
    JSONObject size = new JSONObject();
    size.put("taxonomies.size", "small");
    List<JSONObject> conditions = Arrays.asList(color, size);
    Taxonomy taxonomy = stack.taxonomy().and(conditions);

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

below

below matches entries tagged with any term below a given term, but not with the term itself.

NameTypeDescription
taxonomy (required)String

Field path, such as taxonomies.<TAXONOMY_UID>.

Default: Not applicable
termsUid (required)String

UID of the term to start from.

Default: Not applicable

Returns: Taxonomy. The same taxonomy filter, for chaining.

Validation

  • below throws NullPointerException if taxonomy is null, or if termsUid is null while taxonomy is not empty, because it calls isEmpty() on each value.
  • When taxonomy or termsUid is empty, below records nothing and raises no error. find then sends the query without this condition.
  • There is no other client-side validation. Errors that do occur come from the find call that follows, not from below.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. below records the condition {"$below": "<TERM_UID>"} under the field path and sends no request.
  • find sends the condition in the shape that the Below Operator section describes. The API returns entries tagged with a descendant of the term. An entry tagged only with the term itself does not match.
  • below sends no levels key, so the API matches terms up to its default depth of 10 levels. See Hierarchy depth on the Taxonomy class page.
  • A later in, exists, or hierarchy condition on the same field path replaces this one.
  • Use the equalAndBelow method to include entries tagged with the term itself.
  • Use the above method to match the ancestors instead.

Example

Basic usage: match the terms below a term

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
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);
    Taxonomy taxonomy = stack.taxonomy().below("taxonomies.<TAXONOMY_UID>", "<TERM_UID>");

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

equalAbove

equalAbove matches entries tagged with a given term or with any term above it.

NameTypeDescription
taxonomy (required)String

Field path, such as taxonomies.<TAXONOMY_UID>.

Default: Not applicable
termUid (required)String

UID of the term to start from.

Default: Not applicable

Returns: Taxonomy. The same taxonomy filter, for chaining.

Validation

  • equalAbove throws NullPointerException if taxonomy is null, or if termUid is null while taxonomy is not empty, because it calls isEmpty() on each value.
  • When taxonomy or termUid is empty, equalAbove records nothing and raises no error. find then sends the query without this condition.
  • There is no other client-side validation. Errors that do occur come from the find call that follows, not from equalAbove.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. equalAbove records the condition {"$eq_above": "<TERM_UID>"} under the field path and sends no request.
  • find sends the condition in the shape that the Equal and Above Operator section describes. The API returns entries tagged with the term or with one of its ancestors.
  • equalAbove sends no levels key, so the API matches terms up to its default depth of 10 levels. See Hierarchy depth on the Taxonomy class page.
  • A later in, exists, or hierarchy condition on the same field path replaces this one.
  • Use the above method to leave out entries tagged only with the term itself.

Example

Basic usage: match a term and its ancestors

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
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);
    Taxonomy taxonomy = stack.taxonomy().equalAbove("taxonomies.<TAXONOMY_UID>", "<TERM_UID>");

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

equalAndBelow

equalAndBelow matches entries tagged with a given term or with any term below it.

NameTypeDescription
taxonomy (required)String

Field path, such as taxonomies.<TAXONOMY_UID>.

Default: Not applicable
termsUid (required)String

UID of the term to start from.

Default: Not applicable

Returns: Taxonomy. The same taxonomy filter, for chaining.

Validation

  • equalAndBelow throws NullPointerException if taxonomy is null, or if termsUid is null while taxonomy is not empty, because it calls isEmpty() on each value.
  • When taxonomy or termsUid is empty, equalAndBelow records nothing and raises no error. find then sends the query without this condition.
  • There is no other client-side validation. Errors that do occur come from the find call that follows, not from equalAndBelow.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. equalAndBelow records the condition {"$eq_below": "<TERM_UID>"} under the field path and sends no request.
  • find sends the condition in the shape that the Equal and Below Operator section describes. The API returns entries tagged with the term or with one of its descendants.
  • equalAndBelow sends no levels key, so the API matches terms up to its default depth of 10 levels. See Hierarchy depth on the Taxonomy class page.
  • A later in, exists, or hierarchy condition on the same field path replaces this one.
  • Use the below method to leave out entries tagged only with the term itself.

Example

Basic usage: match a term and its descendants

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
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);
    Taxonomy taxonomy = stack.taxonomy().equalAndBelow("taxonomies.<TAXONOMY_UID>", "<TERM_UID>");

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

exists

exists matches entries by whether they carry a term of the given taxonomy.

NameTypeDescription
taxonomy (required)String

Field path, such as taxonomies.<TAXONOMY_UID>.

Default: Not applicable
value (required)Boolean

true to match entries that carry the field.

Default: Not applicable

Returns: Taxonomy. The same taxonomy filter, for chaining.

Validation

  • exists throws NullPointerException if taxonomy is null, because it calls isEmpty() on it.
  • When taxonomy is empty or value is null, exists records nothing and raises no error. find then sends the query without this condition.
  • There is no other client-side validation. Errors that do occur come from the find call that follows, not from exists.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. exists records the condition {"$exists": value} under the field path and sends no request.
  • find sends the condition in the shape that the Exists Operator section describes. With true, the API returns entries that carry a term of the taxonomy.
  • exists sends false when you pass it. The API reference documents only true.
  • A later in, exists, or hierarchy condition on the same field path replaces this one.

Example

Basic usage: match entries that carry a taxonomy

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
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);
    Taxonomy taxonomy = stack.taxonomy().exists("taxonomies.<TAXONOMY_UID>", true);

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

find

find sends the recorded conditions and returns the entries that match them.

NameTypeDescription
callback (required)TaxonomyCallback

Receives the response body or the error.

Default: Not applicable

Returns: void. The result arrives in the callback.

Validation

  • There is no client-side validation of the recorded conditions. find sends whatever the instance holds, including an empty query when you chain no filter.
  • find throws RuntimeException instead of calling the callback when the request gets no response (no connection, timeout) or when the response body is not JSON. Wrap the call in try/catch inside the background thread.
  • When the API rejects the request, find calls the callback with a null response and an Error. This Error differs from the one that other classes return in the three ways below:
    • getErrorMessage() holds the error_message from the response body, or an empty string when the body has none.
    • getErrorCode() holds the error_code from the response body, or 0 when the body has none.
    • getStatusCode() is always 0, and getErrors() is an empty map.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • find calls Get all entries with defined taxonomies (GET /v3/taxonomies/entries), with the conditions as JSON in the query parameter. One call sends one request.
  • onResponse(JSONObject response, Error error) fires when the API answers.
    • On success, error is null and response is the whole parsed response body. The matching entries are in its entries array.
    • On failure, response is null and error describes the failure.
  • The callback runs on the thread that called find, not on the main thread. Post any UI update to the main thread, for example with a Handler on the main Looper.
  • The conditions stay on the instance after the call, so a second find sends the same query again.
  • find sends no limit, skip, locale, include_fallback, or include_taxonomy_terms parameter. The API applies its own defaults for these.

Example

Basic usage: return the entries tagged with a term

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
import org.json.JSONObject;

import java.util.Arrays;
import java.util.List;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    List<String> terms = Arrays.asList("<TERM_UID>");
    Taxonomy taxonomy = stack.taxonomy().in("taxonomies.<TAXONOMY_UID>", terms);

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

Update the UI with the result

import android.os.Handler;
import android.os.Looper;
import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
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);
    Taxonomy taxonomy = stack.taxonomy().exists("taxonomies.<TAXONOMY_UID>", true);

    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error != null) { Log.e("Contentstack", error.getErrorMessage()); return; }
                    JSONArray entries = response.optJSONArray("entries");
                    int count = entries == null ? 0 : entries.length();
                    // The callback runs on the background thread, so switch to the main thread
                    new Handler(Looper.getMainLooper()).post(() -> {
                        // Update your views here
                        Log.d("Contentstack", "Entries: " + count);
                    });
                }
            });
        } catch (RuntimeException e) {
            Log.e("Contentstack", e.getMessage());
        }
    }).start();
} catch (Exception e) {
    Log.e("Contentstack", e.getMessage());
}

in

in matches entries tagged with at least one of the given terms of a taxonomy.

NameTypeDescription
taxonomy (required)String

Field path, such as taxonomies.<TAXONOMY_UID>.

Default: Not applicable
listOfItems (required)List<String>

UIDs of the terms to match.

Default: Not applicable

Returns: Taxonomy. The same taxonomy filter, for chaining.

Validation

  • in throws RuntimeException if taxonomy is null, because org.json rejects a null key.
  • in does not check listOfItems. A null or empty list records an empty $in array.
  • in records an empty taxonomy string as a key. The other filter methods skip an empty field path instead.
  • There is no other client-side validation. Errors that do occur come from the find call that follows, not from in.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. in records the condition {"$in": ["<TERM_UID>", ...]} under the field path and sends no request.
  • find sends the condition in the shape that the IN Operator section describes. The API returns entries tagged with any of the listed terms.
  • in copies the list when you call it. Changing the list afterwards does not change the query.
  • A later in, exists, or hierarchy condition on the same field path replaces this one.
  • Use the equalAndBelow method to match a term together with the terms below it.

Example

Basic usage: match entries tagged with either of two terms

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
import org.json.JSONObject;

import java.util.Arrays;
import java.util.List;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    List<String> terms = Arrays.asList("red", "yellow");
    Taxonomy taxonomy = stack.taxonomy().in("taxonomies.color", terms);

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

or

or matches entries that satisfy at least one of the given taxonomy conditions.

NameTypeDescription
listOfItems (required)List<JSONObject>

Conditions to combine, one JSONObject each.

Default: Not applicable

Returns: Taxonomy. The same taxonomy filter, for chaining.

Validation

  • When listOfItems is null, or records nothing and raises no error.
  • or does not check the conditions inside the list. An empty list records an empty $or array.
  • There is no other client-side validation. Errors that do occur come from the find call that follows, not from or.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. or records the list under the $or key and sends no request.
  • find sends the condition in the shape that the OR Operator (Taxonomy) section describes. The API returns entries that satisfy at least one condition in the list.
  • Build each condition as a JSONObject with one field path and one value, such as {"taxonomies.color": "black"}. A value can also be an operator object, such as {"$in": [...]}.
  • A second call to or on the same instance replaces the whole list.
  • Use the and method to require every condition instead.

Example

Basic usage: match entries tagged black or small

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.Stack;
import com.contentstack.sdk.Taxonomy;
import com.contentstack.sdk.TaxonomyCallback;

import org.json.JSONArray;
import org.json.JSONObject;

import java.util.Arrays;
import java.util.List;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    // JSONObject.put throws JSONException, which the outer catch handles
    JSONObject color = new JSONObject();
    color.put("taxonomies.color", "black");
    JSONObject size = new JSONObject();
    size.put("taxonomies.size", "small");
    List<JSONObject> conditions = Arrays.asList(color, size);
    Taxonomy taxonomy = stack.taxonomy().or(conditions);

    // find blocks the calling thread, so run it off the main thread
    new Thread(() -> {
        try {
            taxonomy.find(new TaxonomyCallback() {
                @Override
                public void onResponse(JSONObject response, Error error) {
                    if (error == null) {
                        JSONArray entries = response.optJSONArray("entries");
                        Log.d("Contentstack", "Entries: " + (entries == null ? 0 : entries.length()));
                    } else {
                        // The API rejected the request. The status code is always 0 here.
                        Log.e("Contentstack", "Request failed: " + error.getErrorCode() + " "
                                + error.getErrorMessage());
                    }
                }
            });
        } catch (RuntimeException e) {
            // find throws when the request gets no response or the body is not JSON
            Log.e("Contentstack", "Network failure: " + e.getMessage());
        }
    }).start();
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}