Version 6
Created by emmartins on Feb 1, 2011 6:14 AM. Last modified by emmartins on Apr 25, 2011 1:05 PM.

    The Maven Library Plugin can be used to manage build lifecycle of JAIN SLEE 1.1 Library jars. It provides the following goals:

     

    1. copy-dependencies - copies artifacts declared as dependencies to the library.
    2. generate-descriptor - generates the deployable unit XML descriptor, taking as input specific directories as sources of SLEE component jars and service XML descriptors.

     

    Note: parameters and properties will be represented by its name between ${}. For instance, the parameter X, when referred, will be through ${X}


    Quick Start

     

    To add the plugin to Maven build lifecycle simply add, to the top level <build /> element, the following XML:

     

    {code:xml}<plugin>
      <groupId>org.mobicents.tools</groupId>
      <artifactId>maven-library-plugin</artifactId>
      <version>1.0.0.FINAL</version>
      <configuration>
        <library-name>example-library</library-name>
        <library-vendor>org.mobicents</library-vendor>
        <library-version>1.0</library-version>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>copy-dependencies</goal>
            <goal>generate-descriptor</goal>
          </goals>
        </execution>
      </executions>
    </plugin>{code}

     

    This will tell Maven to execute all the goals provided by the plugin, in the default phases of its build lifecycle. Note that it's not mandatory to use all these goals, for instance it is expected that many usages don't declare the generate-ant-managent-script. 

     

    To build the JAIN SLEE Library jar, and install it in the local Maven repository, simply execute the command:

     

    mvn install

     

    The resulting jar will be created in the target directory.

     

    With no custom plugin configuration, besides the JAIN SLEE Library ID, and upon execution, there are a few assumptions:

     

    1. the jars, to be added to the Library jar, are all dependencies declared in the pom, and by its parent. These jar will be placed in the jars  directory.

     

    Referring Other JAIN SLEE 1.1 Library Components

     

    JAIN SLEE 1.1 Library Components can refer other components of same type, in a concept similar as Maven dependencies, and this can be done automatically by the plugin, through the configuration:

     

    {code:xml}<configuration>  
      <library-name>example-library</library-name>
      <library-vendor>org.mobicents</library-vendor>
      <library-version>1.0</library-version>
      <library-ref>
        <library-name>another-example-library</library-name>
        <library-vendor>org.mobicents</library-vendor>
        <library-version>1.0</library-version>
      </library-ref>   
    </configuration>{code}

     

    You can add multiple <library-ref/> elements.

     

    Referring Other JAIN SLEE 1.1 Components Types

     

    The Mobicents JAIN SLEE now supports an extension to allow Library jars or classes to depend on JAIN SLEE 1.1 component types other than Library, through the configuration:

     

    {code:xml}<configuration>
      <library-name>example-library</library-name>
      <library-vendor>org.mobicents</library-vendor>
      <library-version>1.0</library-version>
      <resource-adaptor-type-ref>
        <resource-adaptor-type-name>JAIN SIP</resource-adaptor-type-name>
        <resource-adaptor-type-vendor>javax.sip</resource-adaptor-type-vendor>
        <resource-adaptor-type-version>1.2</resource-adaptor-type-version>
      </resource-adaptor-type-ref>   
    </configuration>{code}

     

    In the example XML above a Resource Adaptor Type is referred, it also supports <event-type-ref/>, <profile-spec-ref/> and <sbb-ref/>. Multiple elements of same type are supported and order is not relevant.

     

    Adding Security Permissions

     

    JAIN SLEE Libraries support the usage of security permissions to allow a JAIN SLEE container, running with security policies, to properly set the runtime environment. The plugin looks for a <security-permissions/> element in the configuration, if such element is found the plugin copies it to the generated XML descriptor, an example:

     

    {code:xml}<configuration>
      <library-name>example-library</library-name>
      <library-vendor>org.mobicents</library-vendor>
      <library-version>1.0</library-version>
      <security-permissions>
            <description>
                Security permissions that allow this library classes to connect to arbitrary sockets.
            </description>
            <security-permission-spec>
                grant {
                       permission java.net.SocketPermission "*", "connect,resolve";
                      };
            </security-permission-spec>
      </security-permissions>   
    </configuration>{code}

     

    Plugin Goals

    copy-dependencies

    The copy-dependencies goal is in fact provided by the standard Maven Dependency Plugin (maven-dependency-plugin), the Mobicents plugin simply exposes it, changing its default configuration to be consistent with the usage of other Mobicents plugin goals:

     

    • the outputDirectory parameter, which defines where the dependencies are copied to, is set to ${project.build.outputDirectory}/jars
    • the excludeTransitive parameter, which defines whether dependencies of dependencies should be copied too, is set to true.

     

    In case the reader is not used to Maven yet, dependencies are declared through the <dependencies /> element, here is an example which declares several artifacts to be copied into the deployable unit:

     

    {code:xml}<dependencies>
      <dependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>example-lib-1</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>example-lib-2</artifactId>
        <version>${project.version}</version>
      </dependency>
    </dependencies>{code}

    generate-descriptor

    The generate-descriptor goal is responsible for generating the Library XML descriptor, the library-jar.xml file inside the META-INF directory. In short it collects the file names of jars, in a specific directory, and then generates the proper XML.

     

    It is possible to customize the plugin's usage through it's configuration parameters:

     

    • workDirectory - the work directory is the base path, used to calculate other directories which may not be set. By default this parameter points to Maven property ${project.build.outputDirectory}, which by default points to the directory target/classes.

     

    • jarDirectory - the path, from the Library jar's root, where jars will be packaged. If this parameter is set, and considering a jar named file.jar, then each <jar-name /> entry in the descriptor will be <jar-name>${jarDirectory}/file.jar</jar-name>, otherwise it will be will be <jar-name>file.jar</jar-name>. By default this parameter value is jars.

     

    • jarInputDirectory - the directory to be used as the source for jars. If the parameter is not set, ${workDirectory}/${jarDirectory} or ${workDirectory} will be used, depending if ${jarDirectory} is set or not. By default  this parameter is not set.

     

    Frequent Asked Questions

     

    • Is the plugin compatible with M2Eclipse Plugin? Yes, but you need to turn off Workspace Resolution or Resolve Workspace Dependencies when creating or importing the project. It is also recommended to use an external installation of Maven since the one embedded in M2Eclipse is quite different than the usual apache binaries.
    • Some jars, which are dependencies declared in the pom's parent, are bundled in the Library jar, how to avoid that? There are several configuration parameters, which can be used by the copy-dependencies goal, to exclude one or more dependencies. See the maven-dependency-plugin site for details and examples.
    • Is the plugin limited to bundling jars, or is it possible to add java classes or resources too? As any other jar packaging pom, simply use the standard src/main/java to hold Java classes which will be compiled and packaged in the resulting jar. For resources use src/main/resources.