Building a new OSGi module

Using the Jahia Studio to create a new project

The easiest way to create a new OSGi module is simply to create a new module using the Jahia Studio that allows you to create and modify module or template projects directly from the Jahia server development environment. It will by default use the OSGi packaging and all you will have to do is simply customize it for your needs.

We will not give the details here on how to create a new project using the Studio, as this is already explained in detail in the Jahia templating guide, available on the Jahia.com website.

Using a Maven Archetype

We provide a Maven archetype to get started quickly with a new project. The Maven Archetype is also used internally by the Jahia Studio to initialize a new project. The steps below guide you through the process of creating a new project.

Create a new project using a Maven Archetype:
```
mvn archetype:generate -Dfilter=org.jahia.archetypes:
```
(do not forget the colon at the end of the filter value)

Select the required archetype, e.g.:

2: remote -> org.jahia.archetypes:jahia-module-archetype (Archetype for creating a new module project to be run on a Jahia server)

Chose the latest archetype version available from the list
Enter project metadata and confirm
Change into project directory and build using:
```
mvn clean install
```

You can then open the Maven project in your favorite IDE and start building your Jahia OSGi module.

From scratch

First and foremost, if you’re ok using the Jahia Modules parent project, it will automatically configure both the Felix Maven Bundle Plugin and Jahia Maven Plugin to use defaults that make sense for most projects. To do so simply set as a parent to your Maven project:

<parent>
    <artifactId>jahia-modules</artifactId>
    <groupId>org.jahia.modules</groupId>
    <version>7.2.0.0</version>
    <relativePath/>
</parent>

If you prefer not to use Jahia module parent project, you will have to setup the plugins yourself, as explained here. To build an OSGi project, it is recommended to use the Felix Maven Bundle Plugin to help with the basic packaging. This is fairly easy to setup. First change the project’s packaging to bundle:

<packaging>bundle</packaging>

Then configure and add the plugin to the project:

<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
        <instructions>
            <Bundle-Name>${project.name}</Bundle-Name>
            <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
            <Bundle-Category>jahia-module</Bundle-Category>
            <Implementation-Title>${project.name}</Implementation-Title>
            <Implementation-Version>${project.version}</Implementation-Version>
            <Implementation-Vendor>${project.organization.name}</Implementation-Vendor>
            <Implementation-URL>${project.organization.url}</Implementation-URL>
            <Specification-Title>${project.name}</Specification-Title>
            <Specification-Version>${project.version}</Specification-Version>
            <Specification-Vendor>${project.organization.name}</Specification-Vendor>
            <!-- Jahia manifest attributes -->
            <Jahia-Depends>default</Jahia-Depends>
            <Jahia-Module-Type>module</Jahia-Module-Type>
            <Jahia-Root-Folder>${project.artifactId}</Jahia-Root-Folder>
            <Jahia-Source-Folders>${project.basedir}</Jahia-Source-Folders>
            <Jahia-Static-Resources>/css,/icons,/images,/img,/javascript</Jahia-Static-Resources>
            <Export-Package></Export-Package>

This is the default minimal configuration for building a Jahia OSGi module bundle.

However, there are a few things that the Felix Bundle Maven plugin cannot do, it cannot scan in non-Java resources for package uses such as:

JSPs
Taglibs
Groovy files
Spring descriptors
Content definitions
Content import files

Fortunately, we provide a goal in the Jahia Maven Plugin that will integrate with the Felix Bundle plugin that will scan all the standard Jahia module resources for you and build the required import package statements in the Felix Bundle plugin configuration.

Here is an example of setting up the Jahia Maven Plugin to scan for dependencies:

<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
        <instructions>
            <Bundle-Name>${project.name}</Bundle-Name>
            <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
            <Bundle-Category>jahia-module</Bundle-Category>
            <Implementation-Title>${project.name}</Implementation-Title>
            <Implementation-Version>${project.version}</Implementation-Version>
            <Implementation-Vendor>${project.organization.name}</Implementation-Vendor>
            <Implementation-URL>${project.organization.url}</Implementation-URL>
            <Specification-Title>${project.name}</Specification-Title>
            <Specification-Version>${project.version}</Specification-Version>
            <Specification-Vendor>${project.organization.name}</Specification-Vendor>
            <!-- Jahia manifest attributes -->
            <Jahia-Depends>default</Jahia-Depends>
            <Jahia-Module-Type>module</Jahia-Module-Type>
            <Jahia-Root-Folder>${project.artifactId}</Jahia-Root-Folder>
            <Jahia-Source-Folders>${project.basedir}</Jahia-Source-Folders>
            <Jahia-Static-Resources>/css,/icons,/images,/img,/javascript</Jahia-Static-Resources>
            <Export-Package></Export-Package>
            <!-- uncomment if you also configure the Jahia Maven plugin jahia:dependencies goal
            <Import-Package>*,${jahia.plugin.projectPackageImport}</Import-Package>
            <Provide-Capability>${jahia.plugin.providedNodeTypes}</Provide-Capability>
            <Require-Capability>${jahia.plugin.requiredNodeTypes}</Require-Capability>
            -->
            <Embed-Dependency>*; scope=compile; type=!pom;
                inline=true</Embed-Dependency>
            <Embed-Transitive>true</Embed-Transitive>
            <_removeheaders>
                Include-Resource,
                Private-Package,
                Embed-Dependency,
                Embed-Transitive
            </_removeheaders>
        </instructions>
        <archive>
            <addMavenDescriptor>false</addMavenDescriptor>
        </archive>
    </configuration>
</plugin>

The plugin will generate the value for the property jahia.plugin.projectPackageImport that was already inserted in the Felix Maven Bundle Plugin configuration we had previously setup. Now the project is ready for building, which you can simply do using:

mvn clean install

Note, please, if your module uses node type or mixin definitions from another module, it is recommended to explicitly define the dependency between modules. See Node type definitions under Mutualization between modules in Development best practices.