kontent.ai.delivery

Class DeliveryParameterBuilder

java.lang.Object

kontent.ai.delivery.DeliveryParameterBuilder

public class DeliveryParameterBuilder
extends java.lang.Object

Convenience class to help construct query parameters for any Listing Response.

For example given the following criteria:

• Only 'article' types
• Only return the 'title', 'summary', 'post_date', and 'teaser_image' elements
• Only return items where the 'personas' selected include 'coffee_lover'
• Order by 'post_date' desc order
• Returning no linked items (0 levels of depth)
• Returning only the first 3 items

The DeliveryParameterBuilder will look like this:

 DeliveryClient deliveryClient = new DeliveryClient("02a70003-e864-464e-b62c-e0ede97deb8c");
 List<ArticleItem> articles = deliveryClient.getItems(
         ArticleItem.class,
         DeliveryParameterBuilder.params()
                 .filterEquals("system.type", "article")
                 .projection("title", "summary", "post_date", "teaser_image")
                 .filterContains("elements.personas", "coffee_lover")
                 .orderByDesc("elements.post_date")
                 .linkedItemsDepth(0)
                 .page(null, 3)
                 .build());
 

Note: When using DeliveryClient.getItems(Class, List), if the type is registered with the client via DeliveryClient.registerType(Class), DeliveryClient.registerType(String, Class), or DeliveryClient.scanClasspathForMappings(String), the operator .filterEquals("system.type", your_mapped_type will automatically be added prior to the request if 'system_type' is not part of any other parameter in the request already.

Filtering Operators

When retrieving a list of content items from your project with DeliveryClient.getItems(List) and/or DeliveryClient.getItems(Class, List), you can filter large sets of content items by building query operators from content elements and system attributes. Note that the query operators do not apply to linked items represented by the ContentItemsListingResponse.getLinkedItems() field in the response.

If you want to limit the listing response only to certain elements, see projection(String...).

Filtering by system values

To filter by system attribute values, you need to use a query attribute in the 'system.<attribute_name>' format. The system attributes include 'id', 'name', 'codename', 'type', 'sitemap_locations', and 'last_modified'. For example, to retrieve only content items based on the Article content type, you can use .filterEquals("system.type", "article" as a query operator.

Filtering by element values

To filter by content element values, you need to use a query attribute in the 'elements.<element_codename>' format. For example, to retrieve only content items whose NumberElement named 'Price' has a value of 16, you can use .filterEquals("elements.price", "13" as a query operator.

Filtering operators

You can use the following filtering operators both with the system attributes and element values:

• filterEquals(String, String)
• filterLessThan(String, String)
• filterLessThanEquals(String, String)
• filterGreaterThan(String, String)
• filterGreaterThanEquals(String, String)
• filterRange(String, String, String)
• filterIn(String, String...)
• filterIn(String, Collection)
• filterContains(String, String)
• filterAny(String, String...)
• filterAny(String, Collection)
• filterAll(String, String...)
• filterAll(String, Collection)

Arrays vs. simple types

You can use the filterContains(String, String), filterAny(String, String...), filterAny(String, Collection), filterAny(String, String...), and filterAny(String, Collection) filtering operators only with arrays. Array attributes in Kontent include the sitemap locations system object (System.getSitemapLocations()), and the AssetsElement, LinkedItem, MultipleChoiceElement, and TaxonomyElement content elements. All the other system attributes and content type elements are simple types, such as strings or numbers.

Comparing values

The filtering operators filterLessThan(String, String), filterLessThanEquals(String, String), filterGreaterThan(String, String), filterGreaterThanEquals(String, String), and filterRange(String, String, String) work best with numbers. For example, you can retrieve products with price larger or equal to 15 by using .filterGreaterThanEquals("elements.price", "15"). Attributes that store dates (such as the last_modified system attribute or DateTimeElements) are represented as strings.

If you use the filters on attributes with string values, the Delivery API tries to perform a string comparison. For example, to retrieve content items modified during February and March you'd need to use a query such as .filterRange("system.last_modified", "2018-02-01", "2018-03-31"), specifying both the start and end dates.

Paging You can get only a small subset of a large collection of content items with the page(Integer, Integer) operator. The first argument is the number of pages to skip, with the second being the page size. Using these argument, you can display a specific page of results and iterate over a list of content items or types.

For example, when you have a ContentItemsListingResponse.getPagination() with a Pagination.getCount() of 10 items, you can use .page(10, 10) to retrieve the second page of results.

For details about the pagination data in each listing response, see the Pagination object.

Projection

Choose which parts of content to retrieve with the projection(String...) operator.

For example, to retrieve only the elements with codenames 'title', 'summary', and 'related_articles': .projection("title", "summary", "related_articles")

Linked items

Content items might reference linked items using the LinkedItem. Recursively, these linked items can reference another LinkedItem element. By default, only one level of linked items are returned.

If you want to include more than one level of linked items in a response, use the linkedItemsDepth(Integer) operator.

If you want to exclude all linked items, use the excludeLinkedItems() operator.

Note: When retrieving content items, linked items cannot be filtered.

See Also:

Kontent.ai API reference - Listing response

Constructor Summary

Constructors

Constructor and Description
DeliveryParameterBuilder()

Method Summary

Modifier and Type	Method and Description
java.util.List<NameValuePair>	build() Builds the query parameters to pass into the DeliveryClient from this DeliveryParametersBuilder.
DeliveryParameterBuilder	excludeLinkedItems() Excludes all linked items.
DeliveryParameterBuilder	filterAll(java.lang.String attribute, java.util.Collection<java.lang.String> values) Attribute with an array of values contains the specified list of values.
DeliveryParameterBuilder	filterAll(java.lang.String attribute, java.lang.String... values) Attribute with an array of values contains the specified list of values.
DeliveryParameterBuilder	filterAny(java.lang.String attribute, java.util.Collection<java.lang.String> values) Attribute with an array of values contains any value from the specified list of values.
DeliveryParameterBuilder	filterAny(java.lang.String attribute, java.lang.String... values) Attribute with an array of values contains any value from the specified list of values.
DeliveryParameterBuilder	filterContains(java.lang.String attribute, java.lang.String value) Attribute with an array of values contains the specified value.
DeliveryParameterBuilder	filterEmpty(java.lang.String attribute) Attribute value is empty.
DeliveryParameterBuilder	filterEquals(java.lang.String attribute, java.lang.String value) Attribute value is the same as the specified value.
DeliveryParameterBuilder	filterGreaterThan(java.lang.String attribute, java.lang.String value) Attribute value is greater than the specified value.
DeliveryParameterBuilder	filterGreaterThanEquals(java.lang.String attribute, java.lang.String value) Attribute value is greater than or equals the specified value.
DeliveryParameterBuilder	filterIn(java.lang.String attribute, java.util.Collection<java.lang.String> values) Attribute value is in the specified list of values.
DeliveryParameterBuilder	filterIn(java.lang.String attribute, java.lang.String... values) Attribute value is in the specified list of values.
DeliveryParameterBuilder	filterLessThan(java.lang.String attribute, java.lang.String value) Attribute value is less than the specified value.
DeliveryParameterBuilder	filterLessThanEquals(java.lang.String attribute, java.lang.String value) Attribute value is less than or equals the specified value.
DeliveryParameterBuilder	filterNotEmpty(java.lang.String attribute) Attribute value is not empty.
DeliveryParameterBuilder	filterNotEquals(java.lang.String attribute, java.lang.String value) Attribute value is not the same as the specified value.
DeliveryParameterBuilder	filterNotIn(java.lang.String attribute, java.util.Collection<java.lang.String> values) Attribute value is not in the specified list of values.
DeliveryParameterBuilder	filterNotIn(java.lang.String attribute, java.lang.String... values) Attribute value is not in the specified list of values.
DeliveryParameterBuilder	filterRange(java.lang.String attribute, java.lang.String lower, java.lang.String upper) Attribute value falls in the specified range of two values, both inclusive.
DeliveryParameterBuilder	includeTotalCount() Adds the information about the total number of content items matching your query.
DeliveryParameterBuilder	language(java.util.Locale language) Determines which language variant of content to return.
DeliveryParameterBuilder	language(java.lang.String language) Determines which language variant of content to return.
DeliveryParameterBuilder	linkedItemsDepth(java.lang.Integer depth) Choose the depth of linked items to return.
DeliveryParameterBuilder	orderByAsc(java.lang.String attribute) Sort the ContentItemsListingResponse by the attribute in ascending order.
DeliveryParameterBuilder	orderByDesc(java.lang.String attribute) Sort the ContentItemsListingResponse by the attribute in descending order.
DeliveryParameterBuilder	page(java.lang.Integer skip, java.lang.Integer limit) Allows a subset of a query.
static DeliveryParameterBuilder	params() Constructs a new DeliveryParameterBuilder.
DeliveryParameterBuilder	projection(java.lang.String... elements) Choose which parts of content to retrieve.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DeliveryParameterBuilder

public DeliveryParameterBuilder()

Method Detail

params

public static DeliveryParameterBuilder params()

Constructs a new DeliveryParameterBuilder.

Returns:

A newly constructed DeliveryParameterBuilder.

filterEquals

public DeliveryParameterBuilder filterEquals(java.lang.String attribute,
                                             java.lang.String value)

Attribute value is the same as the specified value.

Parameters:

attribute - The attribute.

value - The value.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators.

filterNotEquals

public DeliveryParameterBuilder filterNotEquals(java.lang.String attribute,
                                                java.lang.String value)

Attribute value is not the same as the specified value.

Parameters:

attribute - The attribute.

value - The value.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators.

filterEmpty

public DeliveryParameterBuilder filterEmpty(java.lang.String attribute)

Attribute value is empty.

Parameters:

attribute - The attribute.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators.

filterNotEmpty

public DeliveryParameterBuilder filterNotEmpty(java.lang.String attribute)

Attribute value is not empty.

Parameters:

attribute - The attribute.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators.

filterLessThan

public DeliveryParameterBuilder filterLessThan(java.lang.String attribute,
                                               java.lang.String value)

Attribute value is less than the specified value.

Parameters:

attribute - The attribute.

value - The value.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Comparing values.

filterLessThanEquals

public DeliveryParameterBuilder filterLessThanEquals(java.lang.String attribute,
                                                     java.lang.String value)

Attribute value is less than or equals the specified value.

Parameters:

attribute - The attribute.

value - The value.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Comparing values.

filterGreaterThan

public DeliveryParameterBuilder filterGreaterThan(java.lang.String attribute,
                                                  java.lang.String value)

Attribute value is greater than the specified value.

Parameters:

attribute - The attribute.

value - The value.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Comparing values.

filterGreaterThanEquals

public DeliveryParameterBuilder filterGreaterThanEquals(java.lang.String attribute,
                                                        java.lang.String value)

Attribute value is greater than or equals the specified value.

Parameters:

attribute - The attribute.

value - The value.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Comparing values.

filterRange

public DeliveryParameterBuilder filterRange(java.lang.String attribute,
                                            java.lang.String lower,
                                            java.lang.String upper)

Attribute value falls in the specified range of two values, both inclusive.

Parameters:

attribute - The attribute.

lower - The lower bound value.

upper - The upper bound value.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Comparing values.

filterIn

public DeliveryParameterBuilder filterIn(java.lang.String attribute,
                                         java.lang.String... values)

Attribute value is in the specified list of values.

Parameters:

attribute - The attribute.

values - The values.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators.

filterIn

public DeliveryParameterBuilder filterIn(java.lang.String attribute,
                                         java.util.Collection<java.lang.String> values)

Attribute value is in the specified list of values.

Parameters:

attribute - The attribute.

values - The values.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators.

filterNotIn

public DeliveryParameterBuilder filterNotIn(java.lang.String attribute,
                                            java.lang.String... values)

Attribute value is not in the specified list of values.

Parameters:

attribute - The attribute.

values - The values.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators.

filterNotIn

public DeliveryParameterBuilder filterNotIn(java.lang.String attribute,
                                            java.util.Collection<java.lang.String> values)

Attribute value is not in the specified list of values.

Parameters:

attribute - The attribute.

values - The values.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators.

filterContains

public DeliveryParameterBuilder filterContains(java.lang.String attribute,
                                               java.lang.String value)

Attribute with an array of values contains the specified value.

Parameters:

attribute - The attribute.

value - The value.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Arrays vs. simple types.

filterAny

public DeliveryParameterBuilder filterAny(java.lang.String attribute,
                                          java.lang.String... values)

Attribute with an array of values contains any value from the specified list of values.

Parameters:

attribute - The attribute.

values - The values.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Arrays vs. simple types.

filterAny

public DeliveryParameterBuilder filterAny(java.lang.String attribute,
                                          java.util.Collection<java.lang.String> values)

Attribute with an array of values contains any value from the specified list of values.

Parameters:

attribute - The attribute.

values - The values.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Arrays vs. simple types.

filterAll

public DeliveryParameterBuilder filterAll(java.lang.String attribute,
                                          java.lang.String... values)

Attribute with an array of values contains the specified list of values.

Parameters:

attribute - The attribute.

values - The values.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Arrays vs. simple types.

filterAll

public DeliveryParameterBuilder filterAll(java.lang.String attribute,
                                          java.util.Collection<java.lang.String> values)

Attribute with an array of values contains the specified list of values.

Parameters:

attribute - The attribute.

values - The values.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More in Filtering operators., More in Arrays vs. simple types.

orderByAsc

public DeliveryParameterBuilder orderByAsc(java.lang.String attribute)

Sort the ContentItemsListingResponse by the attribute in ascending order. As with filtering, you can use both the 'system' and 'elements' attributes to sort data.

Parameters:

attribute - The attribute to sort on.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More on Content Ordering

orderByDesc

public DeliveryParameterBuilder orderByDesc(java.lang.String attribute)

Sort the ContentItemsListingResponse by the attribute in descending order. As with filtering, you can use both the 'system' and 'elements' attributes to sort data.

Parameters:

attribute - The attribute to sort on.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More on Content Ordering

page

public DeliveryParameterBuilder page(java.lang.Integer skip,
                                     java.lang.Integer limit)

Allows a subset of a query. This can be used with DeliveryClient.getItems(List) and DeliveryClient.getItems(Class, List). If the Page convention is desired, use DeliveryClient.getPageOfItems(Class, List).

Parameters:

skip - The number of items to skip. For the second page of 10, use the value '10' and limit of '10'. The API treats 'null' as a '0' skip value.

limit - The size of the page.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

Pagination, Page, More on Paging

projection

public DeliveryParameterBuilder projection(java.lang.String... elements)

Choose which parts of content to retrieve. For example, to retrieve only the elements with codenames 'title', 'summary', and 'related_articles': .projection("title", "summary", "related_articles")

Parameters:

elements - The elements to retrieve.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More on Projection

linkedItemsDepth

public DeliveryParameterBuilder linkedItemsDepth(java.lang.Integer depth)

Choose the depth of linked items to return.

Parameters:

depth - The number of levels of depth to return.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More on Linked items

excludeLinkedItems

public DeliveryParameterBuilder excludeLinkedItems()

Excludes all linked items. Analogous to .linkedItemsDepth(0)

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More on Linked items

language

public DeliveryParameterBuilder language(java.lang.String language)

Determines which language variant of content to return. By default, the API returns content in the default project language. If the requested content is not available in the specified language variant, the API follows the language fallbacks as configured in the Localization settings of the project. Example: en-US.

Parameters:

language - The language variant to return.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More on Localization, Language fallbacks

language

public DeliveryParameterBuilder language(java.util.Locale language)

Determines which language variant of content to return. By default, the API returns content in the default project language. If the requested content is not available in the specified language variant, the API follows the language fallbacks as configured in the Localization settings of the project. Example: en-US.

Parameters:

language - The language variant to return.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

More on Localization, Language fallbacks

includeTotalCount

public DeliveryParameterBuilder includeTotalCount()

Adds the information about the total number of content items matching your query. The number doesn't include linked items returned as part of the modular_content property. For the total number of items returned within the response, see the X-Request-Charge header. Asking for the total number of content items might increase the response time. When set to true, the pagination object returned in the API response contains an additional total_count property.

Returns:

This DeliveryParameterBuilder with the added operator.

See Also:

Content items

build

public java.util.List<NameValuePair> build()

Builds the query parameters to pass into the DeliveryClient from this DeliveryParametersBuilder.

Returns:

A list of NameValuePairs representing API query parameters.