contentful.java - Contentful Java Delivery Library

Java library for Content Delivery API and Content Preview API. It helps in easily accessing the content stored in Contentful using Java applications.

What is Contentful?

Contentful provides a content infrastructure for digital teams to power content in websites, apps, and devices. Contentful, unlike any other CMS, is built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship digital products faster.

Table of contents

• Core Features
• Getting Started
  • Setup
  • Client Creation
  • First Request
• Usage
  • Filtering
  • Calls in Parallel
  • Paging
  • Includes
  • Unwrapping
  • Preview Mode
  • Sync
  • Http Client
  • Proguard
  • Pre-Releases
• Documentation
• License
• Reaching Contentful
  • Bugs and Feature Requests
  • Sharing Confidential Information
  • Getting involved
• Code of Conduct

Core Features

• Content retrieval through Content Delivery API and Content Preview API.
• Synchronization
• Localization support
• Link resolution
• Supports Environments
• Synchronous and asynchrouns methods of fetching content

Getting Started

Setup

Install the Contentful dependency:

• Maven

<dependency>
  <groupId>com.contentful.java</groupId>
  <artifactId>java-sdk</artifactId>
  <version>10.5.18</version>
</dependency>

• Gradle

compile 'com.contentful.java:java-sdk:10.5.18'

This library requires Java 8 (or higher version) or Android 21.

Client Creation

The CDAClient manages all interactions with the Content Delivery API.

CDAClient client = CDAClient.builder()
    .setSpace("{space-key-goes-here}")
    .setToken("{access-token-goes-here}")
    .build();

The Space-id and Access Token are retrived from the Contentful WebApp.

First Request

Fetching content is achieved by calling the CDAClient.fetch()-method. It fetches all Resources from a Space. The following code fetches all Entries:

// Fetch entries
CDAArray array = 
    client
        .fetch(CDAEntry.class)
        .all();

Usage

Filtering

Filtering of Resources can be done by chaining method calls after the .fetch(). Using .one() and a Resource id retrieves only the specified Resource:

CDAEntry entry =
    client
        .fetch(CDAEntry.class)
        .one("{entry-id-goes-here}");

Fetching only Entries of a specific Content Type is done by adding the .withContentType({id}) call to the chain:

CDAArray result = 
    client
        .fetch(CDAEntry.class)
        .withContentType("{content-type-id-goes-here}")
        .orderBy("{some-field-id-to-order-by-goes-here}")
        .all();

Finally fetching Assets follows the same principles:

// Fetch an Asset with a specific id
CDAAsset asset =
    client
        .fetch(CDAAsset.class)
        .one("{asset-id-goes-here}");

Calls in Parallel

All of the above examples are executed synchronously. In order to request asynchronously, provide a callback to .all(…) or .one(…):

client
    .fetch(CDAAsset.class)
    .all(new CDACallback<CDAArray>() {
  @Override protected void onSuccess(CDAArray result) {
    // ...
  }
});

Note: The return value for any asynchronous methods is the Callback itself, making sure keeping a reference to it and clearing it according to its host lifecycle events is adviced.

If RxJava is required instead, the .observe() method can be used to get an Observable instance:

client
    .observe(CDAAsset.class)
    .one("jake")
    .subscribe(System.out::println);

Paging

If more then 100 Resources are in the Space, .fetchAll() only returns the first 100. If more Resources are needed, specify the limit with the .limit(X) for example:

CDAArray result = 
  client
    .fetch(CDAEntry.class)
    .limit(1000)
    .all();

The maximum number of Resources to be requested is 1000.

For more then 1000 Resources .skip(N), .limit(L) and .orderBy(F) methods are needed. By using .skip(N), the first N Resources are ignored and L, from .limit(L), items are returned.

To guarantee ordering, the use of the .orderBy method is required: It enforces the Array to be in a predictable order.

The following code is used to request all Entries:

// get the amount of Entries, without fetching the actual content
final int amountOfResourcesInContentful = 
  client
    .fetch(CDAEntry.class)
    .limit(0)
    .all()
    .total();

// create storage for the Entries
final List<CDAResource> resources = new ArrayList<CDAResource>(amountOfResourcesInContentful);

// use page size, based on usecase
final int PAGE_SIZE = 2;

// loop through all pages and store results
for(int page = 0; page * PAGE_SIZE < amountOfResourcesInContentful; ++page) {
  final CDAArray currentPagedItems = client
      .fetch(CDAEntry.class)
      .skip(page * PAGE_SIZE)
      .limit(PAGE_SIZE)
      .orderBy("sys.createdAt")
      .all();

  // add to current list of Entries
  resources.addAll(currentPagedItems.items());
}

Using the .reverseOrderBy() method reverses the order:

CDAArray result = 
    client
        .fetch(CDAEntry.class)
        .limit(23)
        .reverseOrderBy("sys.createdAt")
        .all();

The above snippet will fetch the first 23 Entries, sorted by creation date with the latest ones on top.

Sync is used to fetch all entries in a single call and to get only changed Resources in following calls.

Includes

The library contains a feature called link resolution, which will take a link and resolve them. So there is no need to look through entry id's manually, a simple .getField(…) retrieves and entry directly, no need to use the link elements themselves.

For this feature to work, the linked entry needs to be published (see preview) and the include level needs to be set to include this entry. A level of 2 means, that the links of links are getting resolved. Entries of deeper levels contain an empty field if the link could not be resolved. Finding the id of the not resolved field can be achieved through comparing the .rawFields with the .fields property of an Entry.

In order to change the level of includes, the following snippet can be used as a guide:

CDAArray found = client.fetch(CDAEntry.class)
        .include(1) // maximum is 10
        .all();

This only resolves the first level of includes. 10 is the maximum number of levels to be included and should be used sparingly, since this will bloat up the response by a lot.

Unwrapping

Unwrapping is the process of taking a CDAEntry and transforming it into custom types. The following code demonstrates the definition of a custom type:

import com.contentful.java.cda.TransformQuery.ContentfulEntryModel;
import com.contentful.java.cda.TransformQuery.ContentfulField;

@ContentfulEntryModel("cat")
public static class Cat {
  @ContentfulField
  String name;

  @ContentfulField("bestFriend")
  Cat mate;

  @ContentfulField
  FavoriteFood favoriteFood;

  @ContentfulSystemField("id")
  String contentfulId;

  @ContentfulField(value = "likes", locale = "de-DE")
  List<String> germanFavorites;
}

If this library should return a given response like the one above instead of a CDAEntry, the following code snippet will accomplish that:

Cat happycat = client
    .observeAndTransform(Cat.class)
    .one("happycat")
    .blockingFirst();

In addition to returning the Content in a fashion flexible for various use-cases, this feature also uses the select filter to only return the fields required, making the response smaller and more focused.

Notes:

• Specifying a value for the @ContentfulField-annotation , will use the value of the similarly called field id instead of the name of the custom field.
• A locale can be used to specify a given locale of this entry. If no locale is given, the default locale will be used.
• @ContentfulSystemField is used for CDAEntries attributes (sys.id, etc) to be inserted.
• If another type is wanted to be transformed, it should have @ContentfulEntryModel-annotation specified similarly as in Cat.

Select

The amount of data returned by the API can be reduced by using the .select() method on a query. With this, Contentful only returns the selected fields. The library enforces that the sys fields (.getAttribute() on an Entry) will always be returned, since it is used for the proper functioning of the library.

If reducing the payload size is wanted, the following snippet can explain how to accomplish that

CDAArray found = client.fetch(CDAEntry.class)
    .withContentType("cat");
    .select("fields.name");

This snippet makes sure that the entries of type cat are only containing its name field. All other fields will be null or its respective default value.

Note: The content type has to be added through .withContentType(…) otherwise an error ensues.

Preview

The Content Delivery API only returns published Entries. The Content Preview API will return all Entries, even not published ones:

CDAClient client = 
    CDAClient.builder()
        .setSpace("space-key-goes-here")
        .setToken("access-token-goes-here")
        .preview()
        .build();

The Preview Access Token is exposed on the Contentful Web App.

Note: In Preview, Resources can be invalid since no validation is performed prior to publishing.

Sync

Fetching all Resources and retrieving only changes on subsequent calls is accomplished by using the .sync()-methods:

SynchronizedSpace space = client.sync().fetch();

The SynchronizedSpace contains all published Resources. If .preview() (see Preview) is used, it also contains all unpublished Resources.

If changes are to be fetched later, calling sync() again using the given SynchronizedSpace as a parameter is needed:

SynchronizedSpace later = client.sync(space).fetch();

If an Entry gets deleted, its id is returned in theSynchronizedSpace.deletedEntries() set. Same is true for the deleted Assets through SynchronizedSpace.deletedAssets().

Http Client

Changing the settings of the http client, without losing the information setup in the client build process, is achieved by requesting the .defaultCallFactoryBuilder() from the CDAClient.Builder, changing it and then reapplying it:

// create a client builder as usual
CDAClient.Builder clientBuilder = CDAClient.builder()
        .setSpace("space-id-goes-here")
        .setEnvironment("environment-id-goes-here")  // optional
        .setToken("cda-token-goes-here");

// request the http client with the settings from above (token, error interceptor, etc)
OkHttpClient httpClient = clientBuilder.defaultCallFactoryBuilder()
        .addInterceptor(interceptor) // adding a custom interceptor
        .connectTimeout(5, TimeUnit.SECONDS) // adding a timeout 
        .cache(new Cache(new File("/tmp"), CACHE_SIZE_BYTES)) // adding a simple http cache
        .build();

// reapply the http changes and build a contentful client
CDAClient cdaClient = clientBuilder.setCallFactory(httpClient).build();

Proguard

The ProGuard configuration file is used to minify Android Apps using this library.

Rich Text renderer library

There is Java library for Rich Text API. It helps in easily rendering rich text stored in Contentful using Java.

Pre-releases

Development versions of this library are available through

• Sonatype's snapshots repository:

maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
implementation 'com.contentful.java:java-sdk:10.4.1-SNAPSHOT'

• jitpack.io:

maven { url 'https://jitpack.io' }
implementation 'com.github.contentful:contentful.java:java-sdk-10.4.1-SNAPSHOT'

Documentation

See

• JavaDoc
• API documentation

License

Copyright (c) 2019 Contentful GmbH. See LICENSE.txt for further details.

Reaching Contentful

Questions

• Use the community forum:
• Use the community slack channel:

Bugs and Feature Requests

• File an issue here .

Sharing Confidential Information

• File a support ticket at our Contentful Customer Support:

Getting involved

Code of Conduct

Contentful wants to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of their identity markers.

Full Code of Conduct.