How to use the iPOJO Maven Plug-in¶

How to use the iPOJO Maven Plug-in

Basic configuration¶

To use the iPOJO Maven plug-in, edit the following pom.xml (replace all $XXX elements):

<project>
    <modelVersion>4.0.0</modelVersion>

    <groupId>$YOUR_GROUP_ID</groupId>
    <artifactId>$YOUR_ARTIFACT_ID</artifactId>
    <version>$YOUR_ARTIFACT_VERSION</version>

    <name>$YOUR_PROJECT_NAME</name>

    <!-- Use the bundle packaging type -->
    <packaging>bundle</packaging>

    <dependencies>
       $YOUR_MAVEN_DEPENDENCIES
    </dependencies>

    <build>
      <plugins>
          <!-- BND Maven Plugin Configuration -->
          <plugin>
              <groupId>org.apache.felix</groupId>
              <artifactId>maven-bundle-plugin</artifactId>
               <extensions>true</extensions>
               <configuration>
                   <instructions>
                       <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
                      <Private-Package>$YOUR_PRIVATE_PACKAGE</Private-Package>
                      <Export-Package>$YOUR_EXPORTED_PACKAGE</Export-Package>
                  </instructions>
              </configuration>
          </plugin>
          <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-ipojo-plugin</artifactId>
                <version>1.12.1</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>ipojo-bundle</goal>
                        </goals>
                  </execution>
              </executions>
          </plugin>
      </plugins>
  </build>
</project>

The iPOJO Maven Plug-in is generally used with the BND Maven Plug-in (more details here). However the two configurations are completely separated. So, you can use all BND Maven plug-in features. The iPOJO configuration section can be used as previously written without any changes. However it requires that your metadata file is either inside src/main/ipojo or inside the src/main/resources folder and named "metadata.xml".

Execution¶

To manipulate your project, use the "mvn clean install" command. The output should be like:

[INFO] Scanning for projects...
[INFO] ----------------------------------------------------------------------------
[INFO] Building Hello Client
[INFO]      task-segment: [clean, install]
[INFO] ----------------------------------------------------------------------------
[INFO] [clean:clean]
[INFO] Deleting directory ...hello.client\target
[INFO] Deleting directory ...hello.client\target\classes
[INFO] Deleting directory ...hello.client\target\test-classes
[INFO] Deleting directory ...hello.client\target\site
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] Copying 1 resource
[INFO] [compiler:compile]
[INFO] Compiling 1 source file to ...hello.client\target\classes
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] Resource directory does not exist: ...hello.client\src\test\resources
[INFO] [compiler:testCompile]
[INFO] No sources to compile
[INFO] [surefire:test]
[INFO] No tests to run.
[INFO] [bundle:bundle]
[INFO] [org.apache.felix.ipojo.:ipojo-bundle {execution: default}]
[INFO] Start bundle manipulation
[INFO] Metadata File : ...hello.client\target\classes\metadata.xml
[INFO] Input Bundle File : ...hello.client\target\hello.client-0.0.1.jar
[INFO] Bundle manipulation - SUCCESS
[INFO] [install:install]
[INFO] Installing ...hello.client\target\hello.client-0.0.1.jar to D:\Dev\maven-repo\ipojo\example\hello.client\0.0.1\hello.client-0.0.1.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9 seconds
[INFO] Finished at: Mon Aug 13 14:04:55 CEST 2007
[INFO] Final Memory: 6M/13M
[INFO] ------------------------------------------------------------------------

Configuration Options¶

You can configure the localization of the iPOJO metadata file as following:

<plugin>
       <groupId>org.apache.felix</groupId>
       <artifactId>maven-ipojo-plugin</artifactId>
       <version>1.12.1</version>
       <executions>
              <execution>
              <goals>
                      <goal>ipojo-bundle</goal>
               </goals>
               <configuration>
                        <metadata>ipojo/meta.xml</metadata>
               </configuration>
               </execution>
      </executions>
</plugin>

In the metadata element, you can specify your metadata file or directory. The given file path is relative to the root directory ("./ipojo/meta.xml"). If the specified location is a directory, all contained XML files will be used. By default, the plugin searches metadata files into the src/main/ipojo folder. If not found then it searches for target/classes/metadata.xml and ./metadata.xml.

The directory support was introduced in the `1.7.0` version. Previously only one metadata file was found. Before the `1.7.0`, the set location was searched in all resource folders. This is no more supported because it's an anti-pattern.

The second option allows skipping annotations processing, by using the ignoreAnnotations element:

<plugin>
       <groupId>org.apache.felix</groupId>
       <artifactId>maven-ipojo-plugin</artifactId>
       <version>1.12.1</version>
       <executions>
              <execution>
              <goals>
                      <goal>ipojo-bundle</goal>
               </goals>
               <configuration>
                      <ignoreAnnotations>true</ignoreAnnotations>
               </configuration>
               </execution>
      </executions>
</plugin>

You can also ignore embedded XML-Schemas to use external ones. To do so, add the ignoreEmbeddedSchemas. If set to true, the manipulator doesn't use embedded XML-Schemas:

<plugin>
       <groupId>org.apache.felix</groupId>
       <artifactId>maven-ipojo-plugin</artifactId>
       <version>1.12.1</version>
       <executions>
              <execution>
              <goals>
                      <goal>ipojo-bundle</goal>
               </goals>
               <configuration>
                      <ignoreEmbeddedSchemas>true</ignoreEmbeddedSchemas>
               </configuration>
               </execution>
      </executions>
</plugin>

Generate the skeleton of your iPOJO bundle¶

The maven-ipojo-plugin provides a way to generate the skeleton of your project. To generate this structure, just launch the following command:

mvn org.apache.maven.plugins:maven-archetype-plugin:generate \
-DarchetypeArtifactId=maven-ipojo-plugin \
-DarchetypeGroupId=org.apache.felix \
-DartifactId=ARTIFACT_NAME_OF_YOUR_PROJECT \
-DgroupId=GROUP_ID_OF_YOUR_PROJECT \
-DarchetypeVersion=VERSION_OF_YOUR_PROJECT \
-DpackageName=PACKAGE_NAME

This command generates : a pom file (to update), the src/main/java and src/main/resources folders, * the structure of your package name.

The generated project uses iPOJO annotation and is ready to be deployed.

Maven Archetype

The maven-ipojo-plugin archetype generates a pom file using the latest released version of the maven-ipojo-plugin.

Describing iPOJO configuration in the pom file¶

It is also possible to describe iPOJO components and instances inside the pom file (avoiding using a externalized file). The configuration can be described in the metadata attribute inside a CDATA block.

<plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-ipojo-plugin</artifactId>
        <version>1.12.1</version>
        <executions>
            <execution>
                <goals>
                    <goal>ipojo-bundle</goal>
                </goals>
                <configuration>
                    <ignoreAnnotations>true</ignoreAnnotations>
                    <metadata>
                            <![CDATA[
                            <ipojo
                             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                             xsi:schemaLocation="org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/CURRENT/core.xsd"
                             xmlns="org.apache.felix.ipojo">
                             <component
                                classname="org.apache.felix.ipojo.test.scenarios.component.LifecycleControllerTest"
                                name="LFC-Test">
                                <provides />
                                <controller field="m_state" />
                                <properties>
                                    <property name="conf" field="m_conf" method="setConf" />
                                </properties>
                             </component>
                             <component
                                classname="org.apache.felix.ipojo.test.scenarios.component.LifecycleControllerTest"
                                name="LFC-Test-Immediate" immediate="true" architecture="true">
                                <provides />
                                <controller field="m_state" />
                                <properties>
                                    <property name="conf" field="m_conf" method="setConf" />
                                </properties>
                             </component>
                            </ipojo>
                           ]]>
                    </metadata>
                </configuration>
            </execution>
        </executions>
</plugin>