Java library for Content Delivery API and Content Preview API. It helps in easily accessing the content stored in Contentful using Java applications.
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
- Content retrieval through Content Delivery API and Content Preview API.
- Synchronization
- Localization support
- Link resolution
- Supports Environments
- Synchronous and asynchrouns methods of fetching content
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.
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.
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();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}");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);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.
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 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
valuefor the@ContentfulField-annotation , will use the value of the similarly called field id instead of the name of the custom field.- A
localecan be used to specify a given locale of this entry. If no locale is given, the default locale will be used.@ContentfulSystemFieldis 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 inCat.- Limitation on Unwrapping: Using Unwrapping does not currently allow direct access to the raw JSON for rich text fields, as the SDK automatically transforms fields into the custom model structure. For cases where raw JSON is needed:
- Use the
rawFieldsmap inCDAEntryto directly access the unprocessed JSON of any field, including rich text.- Alternatively, make a direct HTTP request to the Contentful API to retrieve the full raw JSON response.
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.
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.
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().
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();The ProGuard configuration file is used to minify Android Apps using this library.
There is Java library for Rich Text API. It helps in easily rendering rich text stored in Contentful using Java.
Development versions of this library are available through
maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
implementation 'com.contentful.java:java-sdk:10.4.1-SNAPSHOT'maven { url 'https://jitpack.io' }
implementation 'com.github.contentful:contentful.java:java-sdk-10.4.1-SNAPSHOT'See
Copyright (c) 2019 Contentful GmbH. See LICENSE.txt for further details.
- Use the community forum:
- Use the community slack channel:
- File an issue here
.
- File a support ticket at our Contentful Customer Support:
Contentful wants to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of their identity markers.