Headless Java CMS: In depth guide for developers

Introduction

A headless Java CMS is a content management system that runs on the JVM, serves content through APIs and lets developers extend it with their own Java code. Organizations that use Java as their main back-end language often want a CMS they can extend and deploy like the rest of their estate. This guide lists the key features of a good headless Java CMS and shows how Jahia matches each criterion.

If you are weighing architectures first, read our comparison of headless and traditional CMS.

Modularity with OSGi: the base of a headless Java CMS

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, OSGi addresses modularity at the application level. JPMS modularizes the JDK itself.

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 lets a module embed its own dependencies, even when their versions differ from the ones Jahia uses.
• 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. In Jahia, extension points should be implemented as OSGi Declarative Services.
• 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 Apache 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.

For the Spring angle, read our article on Spring Boot and OSGi.

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: 

1. CMS that provides a UI to build content types. This approach allows one to learn content modeling quickly.
2. 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: GraphQL in a headless Java CMS

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 and mutations. 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: Code behind a URL, called for example when a form is submitted
• Jobs: Execute code based on a schedule
• Choicelist initializers: Programmatically populate the dropdown lists authors see
• 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. 

Jahia is open core: the core is available under Apache 2.0 or the commercial JSEL license, as the license header of the public repository shows. The Enterprise distribution is commercial.

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 our article on 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. 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. 

To see how JSX is rendered and hydrated, read our article on React hydration in Java.

Complementary components 

A CMS alone is sometimes not enough. Customer data, especially with a high write frequency, needs a different architecture from content: store it in a CDP (Customer Data Platform). Jahia's CDP is built on Apache Unomi, the open source customer data platform that originated at Jahia. It is integrated into the platform. It also stores and manages visitor profiles, including form data and behavioral data.

Conclusion

In short, a good Headless Java CMS needs to:

• Be modular and based on OSGi
• Provide a flexible data/content model
• Offer customization/extensibility of APIs
• Support multiple integration patterns
• Be a good CMS for business users
• Have a presentation layer (so ideally not pure headless)

If you want to know more, you can: 

• Read our page summarizing our developer experience
• Read our page summarizing our technical architecture
• Compare platforms with our checklist for choosing a Java CMS.
• Try Jahia and go through our tutorials, describing the integration of a landing page in Jahia