contentful-management.java - Contentful Java Management SDK

Java SDK for Content Management API. It helps in editing and creating content stored in Contentful with 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.

• contentful-management.java - Contentful Java Management SDK
  • What is Contentful?
• Core Features
• Getting Started
  • Setup
  • Client Creation
  • First Request
• Usage
  • Modules
  • Calls in Parallel
  • Environment Configuration
  • Default HTTP Client
  • RichText Hierarchy
  • Pre-releases
• Documentation
• License
• Reaching Contentful
  • Questions
  • Bugs and Feature Requests
  • Sharing Confidential Information
  • Getting involved
• Code of Conduct

Core Features

• Content manipulation through Content Management API.
• Supported Endpoints
  • ApiKeys
  • Assets
  • Bulk actions
  • ContentTypes
  • ContentTags
  • EditorInterface
  • Entries
  • Environments
  • Locales
  • Organizations
  • PersonalAccessTokens
  • PreviewApiKeys
  • Roles
  • Scheduled actions
  • SpaceMemberships

Getting Started

Setup

Install the Contentful dependency:

• Maven

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

• Gradle

compile 'com.contentful.java:cma-sdk:3.4.23'

This SDK requires Java 8 (or higher version).

Client Creation

The CMAClient manages all interactions with the Content Management API.

final CMAClient client =
    new CMAClient
        .Builder()
        .setAccessToken("<access_token>")
        .build();

The Access Token can easily be obtained through the management API documentation.

First Request

By selecting a Module, say .entries() and using its manipulator methods, like .fetchAll(), changes can be applied to the underlying resources. Resources can be fetched as following:

final CMAArray<CMAEntry> array =
    client
        .entries()
        .fetchAll();

Usage

Modules

A client performs various operations on different types of Resources (such as Assets, Content Types, Entries, Spaces, etc). Every type of Resource is represented by a Module in the CMAClient class, for example:

client.spaces() // returns the Spaces Module
client.entries() // returns the Entries Module
client.assets() // returns the Assets Module
…

Calls in Parallel

Each Module contains a set of methods that perform various operations on the specified Resource type. Every method has a corresponding asynchronous extension which can be accessed through the async() method of the Module, for example the following synchronous call

final CMAArray<CMASpace> array =
    client
        .spaces()
        .fetchAll(
	    "space_id",
	    "environment_id"
	);

can be expressed by this asynchronous call:

final CMAArray<CMASpace> array =
    client
        .spaces()
        .async()
        .fetchAll(
	    "space_id",
	    "environment_id",
	    new CMACallback<CMAArray<CMASpace>>() {
  @Override protected void onSuccess(CMAArray<CMASpace> result) {
    // success
  }

  @Override protected void onFailure(RetrofitError retrofitError) {
    // failure
  }
});

Note: The default CMACallback has an empty onFailure() implementation. If failures are of interest, overriding this method is mandatory.

Note: [The CMA documentation][docs] offers more code snippets for all Modules.

Environment Configuration

Instead of repeating the Space and _Environment _ids with every call like so

final CMAArray<CMAEntry> array =
    client
        .entries()
        .fetchAll(
            "space_id",
            "environment_id",
        );

the client can be configured to always use the same values:

final CMAClient client =
    new CMAClient
        .Builder()
        .setAccessToken("<access_token>")
        .setSpaceId("<space_id>")
        .setEnvironmentId("<environment_id>")
        .build();

This changes the parameters Modules are using:

final CMAArray<CMAEntry> array =
    client
        .entries()
        .fetchAll();

Words of warning

The Modules apiKeys, environments, roles, spaceMemberships, uiExtensions, uploads, and webhooks, do not support Environments different to master. If the above configuration is used with these Modules, they throw an exception. Creation of a new client without specifying an Environment id is needed:

final CMAArray<CMAApiKey> array =
    client
        .apiKeys()
        .fetchAll(
	   "spaceid"
	);

Default HTTP Client

The SDK uses [Retrofit][2] as a REST client, which detects [OkHttp][3] in the classpath and uses it if available, or else it falls back to the default HttpURLConnection.

The recommended approach would be to add [OkHttp][3] as a dependency to your project, but that is completely optional.

It is possible to specify a custom client to be used, refer to the [official documentation][4] for instructions.

RichText Hierarchy

In order to create and update rich text fields, the following rule set is enforced from Contentful:

1. A Document cannot be nested inside a Document.
2. A Document can only contain Paragraphs, Lists, or Texts.
3. Paragraphs can contain Paragraphs or Text and Link nodes.
4. Links have to be inside of Paragraphs.
5. A List has to be inside of a Document.
6. A ListItem has to contain at least one Paragraph.

For supported and tested combinations of Nodes, please take a look at the Rich Text End to End tests, those will be kept updated over time and should give an overview on what is possible.

Pre-releases

Snapshots of the development version are available through

• [Sonatype's snapshots repository][snap]

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

• jitpack.io:

maven { url 'https://jitpack.io' }
compile 'com.github.contentful:contentful.java:cma-sdk-3.3.3-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: [![Contentful Community Forum](https://img.shields.io/badge/-Join%20Communi