Developing Jahia extensions

Extension points

Multiple parts of Jahia can be extended by adding Java classes in modules. A module developer can, for example, add a new action that will add a new HTTP endpoint, add a render filter that will change the rendering, or modify the HTML cache key generation by adding CacheKeyPartGenerator.

In versions before Jahia 8, this was usually done by declaring Spring Beans. These beans were processed and registered into the Jahia core. Now you can do the same thing with OSGi services, without relying on any Spring context. You just need to expose the same classes as OSGi services with the same properties.

Using Declarative Services to build extensions

All extension points in Jahia should be implemented using OSGi Declarative Services. This section shows how to achieve this before looking at the various extension types.

Code samples

Sample code showing how to extend Jahia with Declarative Services (DS) are available at https://github.com/Jahia/OSGi-modules-samples.

Simple component

When using Declarative Services, you need to add the @Component annotation to declare your class as DS component with the service attribute set to the base class. The component can set its attribute directly in its activator:

@Component(service = RenderFilter.class, immediate = true)
public class TestFilter extends AbstractFilter {

    @Activate
    public void activate() {
        setPriority(1);
        setApplyOnConfigurations("page");
    }

Configured component

A component can also rely on an OSGi configuration. By default, the configuration has the same name as the component, which is the fully qualified class name. In the following example, the content of <data>/karaf/etc/org.mypackage.MyChoiceListInitializer.cfg is passed in the props parameter of the activator.

@Component(service = {ModuleChoiceListInitializer.class, ModuleChoiceListRenderer.class})
public class MyChoiceListInitializer extends AbstractChoiceListRenderer implements ModuleChoiceListRenderer, ModuleChoiceListInitializer {

    @Activate
    public void activate(Map<String, ?> props) {
        setKey((String) props.get("key"));
    }
}

You can also use an annotation type containing the properties you expect instead of the generic Map<String, ?> type. This allows you to have typed attributes and default values.

    @interface Param {
        String key() default "default-key";
    }

    @Activate
    public void activate(Param p) {
        setName(p.key());
    }

Note that you can provide configuration files in modules in resources/META-INF/configurations. They will be copied to <data>/karaf/etc.

Component factories

Another useful feature of DS components is the component factory. You can create multiple instances of your beans based on multiple configuration files. Compared to the previous example, you need to modify the component scope to Bundle, as in the following example:

@Component(service = RenderFilter.class, scope = ServiceScope.BUNDLE)
public class MyFilter extends AbstractFilter {

    @Activate
    public void activate(Map<String, ?> props) {
        try {
            BeanUtils.copyProperties(this, props);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

You can then define multiple configuration files, all named org.mypackage.MyFilter-<id>.cfg, with a different id for each config. One instance of the component is created for each configuration.

Hot reload

Another benefit of DS components is that it allows hot reloading of components without requiring server restarts. For example, you can use Declarative Services to add a servlet filter (by extending AbstractServletFilter) and deploy without requiring a server restart to activate. (See sample code https://github.com/Jahia/OSGi-modules-samples/tree/master/servlet-filter-samples).

Extension types

Basic usage

Custom GraphQL Query implementation

org.jahia.modules.graphql.provider.dxm.DXGraphQLExtensionsProvider

Custom GraphQL Mutation implementation

Custom Actions

Custom Render filters

Custom Choicelist Initializer

Authentication

Custom Authentication Valve