Headless Java CMS: In depth guide for developers

December 1, 2024

Romain Gauthier

Jahia is committed to providing developers with the best possible user experience Learn more

Introduction

Headless CMSs have gained in popularity over the last 7 years; however, many are pure SAAS products that can’t be extended nor heavily customized; the others are based on node.js. Consequently, organizations using Java as their main backend language are left without any obvious solution. In this article, you’ll read about the key features of a good headless Java CMS. And, of course, how does Jahia match these criteria.

Modularity with OSGi

The most important attribute of a Java CMS, headless or not, is its modularity. Modularity is what enables Java developers to customize and extend the CMS. In the Java world, there is only one technology that supports modularity properly: OSGi.

Let’s review the main requirements of good modularity, nicely covered in OSGi:

Isolation: The most complex problem to solve is to ensure that the libraries you use in your code won’t conflict with the ones provided by the CMS vendor. Isolation will ensure that you can use any library you want and that your code won’t break when updating the version of your CMS.
Dependency management: Managing dependencies between your modules or between your modules and the cms core capabilities must be done properly. OSGi provides advanced support, including the ability to declare dependencies to a range of versions.
Hot deployment: If you need to restart your application every time you deploy code, your development flow will be painfully slow. You need a CMS that supports hot deployment. This feature is also useful to change the configuration of your application on the fly.
Support for whiteboard pattern: This pattern is the perfect complement to hot deployment; it allows developers who are coding modules to declare implementations that will be deployed in the platform. For instance, in Jahia, you can declare “Actions”. Actions are code that will be executed when a given URL is called. The whiteboard pattern allows you to declare your actions in your module and ensure that they will be picked up by Jahia when you deploy your module. The whiteboard pattern is based on registries, each registry being used to store the actions, filters, jobs, or any other integration point that the platform may support. The code inside Jahia leveraging the whiteboard pattern is the OSGi registry.
Bonus: Tooling. A good modularity technology comes with good tooling to update configuration, deploy, start, stop, and undeploy modules. This tooling should be accessible using HTTP APIs, command lines, and UIs. Jahia uses Karaf as an OSGi implementation, providing most of these features. Jahia also added a UI to deploy and manage modules and a provisioning API based on YAML.

Content modeling

One of the differences between a CMS and a regular application is the agility required to manage the data model, referred to as content modeling or content types. There are typically 2 approaches to this requirement:

CMS that provides a UI to build content types. This approach allows one to learn content modeling quickly.
CMS that allows content types to be deployed as code, making sure that the content types are versioned at the same time as the rest of your code.

Jahia is the 2nd kind, providing many options for content modeling. You can learn more on our developer experience page.

API Extension

Once you have a way to deploy Java code - thanks to good modularity - the most usual requirement for a headless Java CMS would be to create custom API endpoints.

Jahia mostly uses GraphQL, and you can extend existing endpoints or create new ones. The capability applies to queries, mutations, and subscriptions. If you want to have a look at what a GraphQL extension looks like, a sample is available in our GraphQL Github repository.

Other integration patterns

Besides customizing APIs, a good headless Java CMS will also support other integration patterns, such as:

Services: Reusable code implementing any custom behavior
Actions: Execute code based on a URL
Jobs: Execute code based on a schedule
Selectors initializers: Programmatically populate dropdowns or other selectors used by content authors
Other patterns can include filters, rules, validators, decorators, etc.

If you want to see what it looks like in Jahia, there is a dedicated repository: OSGi modules samples.

Open source / open core

Being able to access the source code of a product that you want to extend or customize is often very valuable. It makes debugging easier and the relationship with the vendor more straightforward.

Most of Jahia’s code is open source, and our entire codebase is accessible to our customers.

Authoring experience

You should not forget that a good headless Java CMS needs to be a good CMS. So don’t forget to check the features for the business users you’re working with. For more information, read the article Headless CMS - Which features for Marketers?.

Presentation layer / The head

If you’re reading this post and looking for a headless CMS, you might not agree with all the lines below.. and that’s ok. At Jahia, we believe a presentation layer (generating HTML from content items) is always convenient and often essential. The capability to render full HTML Pages or HTML fragments provides much more flexibility than a CMS that can only output JSON.

Jahia provides 2 presentation (aka templating) technologies:

JSP (Java Server Pages), as good old Java
JSX (JavaScript XML), which can be embedded in JavaScript modules.

Complementary components

A CMS alone is sometimes not enough. If your project involves working with customer data, especially with high write frequency, you should never store that data in a CMS. Managing content and managing customer data requires different kinds of architecture. In other words, the best complement to a good CMS is a good CDP (Customer Data Platform).

Jahia is contributing heavily to the Apache Unomi project. Our customers use it to store and manage form data, user-generated content, behavioral data, visitor preferences, etc.