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
- 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.2</version>
</dependency>
- Gradle
compile 'com.contentful.java:java-sdk:10.5.2'
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 specifyied 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 inCat
.
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
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'
Documentation
See
License
Copyright (c) 2019 Contentful GmbH. See LICENSE.txt for further details.
Reaching Contentful
Questions
Bugs and Feature Requests
Sharing Confidential Information
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.