Maven Petals Plug-in 2.4.0-SNAPSHOT

Version 13 by Christophe DENEUX
on Jun 16, 2014 16:48.

<< Changes from 12 to 13

compared with

Version 14 by Christophe DENEUX
on Aug 13, 2014 11:35.

Changes from 14 to 15 >>

Key

This line was removed.

This word was removed. This word was added.

This line was added.

Changes (2)

View Page History

...

{section}
{column}

h1. Introduction

This Maven plugin supports:

* Several _packaging_:
** *jbi-component*: used for a JBI components (binding component or service engine).
** *jbi-service-unit*: used for a standard service-units and deployable service units.
** *jbi-service-assembly*: used for a service assemblies.
** *jbi-shared-library*: used for a shared-libraries.

* Several _goals_:
** *jbi-package*: used to create a JBI archive.
** *jbi-configure*: used to configure a deliverable JBI archive.
** *jbi-install*: used to install a JBI archive on a Petals node.
** *jbi-start*: used to start a Petals component on a Petals node.
** *jbi-stop*: used to stop a Petals component on a Petals node.
** *jbi-uninstall*: used to uninstall a JBI archive from a Petals node (not implemented yet).
{column}
{column}
{panel:title=Table of content}{toc:maxLevel=3}{panel}
{panel:title=Contributors}{contributors}{panel}
{column}
{section}

h1. Packaging

As described previously, the plugin supports different packaging to build JBI artifacts.
This section details and illustrates them. As a general matter, defining specific packaging allows to use JBI archives as dependencies in other projects.
It also allows to define the build life cycle to apply on such a project.

{note}
When installing such artifacts in a repository, only the JBI archive is installed.
{note}

h2. jbi-component

This packaging identifies a Maven2 project as being the development of a JBI component (either a binding component, or a service engine).
The associated language is Java, which allows to use *maven-eclipse-plugin* to make this project an Eclipse project.

The build life cycle of a JBI component is:

|| Phases || Goals ||
| process-ressources | 1. org.apache.maven.plugins:maven-resources-plugin:resources |
| compile | 1. org.apache.maven.plugins:maven-compiler-plugin:compile |
| process-test-ressources | 1. org.apache.maven.plugins:maven-resources-plugin:testResources |
| test-compile | 1. org.apache.maven.plugins:maven-compiler-plugin:testCompile |
| test | 1. org.apache.maven.plugins:maven-surefire-plugin:test |
| package | 1. org.apache.maven.plugins:maven-jar-plugin:jar, \\
2. org.ow2.petals:maven-petals-plugin:jbi-package |
| install | 1. org.apache.maven.plugins:maven-install-plugin:install |
| deploy | 1. org.apache.maven.plugins:maven-deploy-plugin:deploy |

h2. jbi-service-unit

This packaging identifies a Maven2 project as being the development of a service-unit.
The associated language is Java, which allows to use *maven-eclipse-plugin* to make this project an Eclipse project.

The build life cycle of a service-unit is:

|| Phases || Goals ||
| process-ressources | 1. org.apache.maven.plugins:maven-resources-plugin:resources |
| compile | 1. org.apache.maven.plugins:maven-compiler-plugin:compile |
| process-test-ressources | 1. org.apache.maven.plugins:maven-resources-plugin:testResources |
| test-compile | 1. org.apache.maven.plugins:maven-compiler-plugin:testCompile |
| test | 1. org.apache.maven.plugins:maven-surefire-plugin:test |
| package | 1. org.apache.maven.plugins:maven-jar-plugin:jar, \\
2. org.ow2.petals:maven-petals-plugin:jbi-package |
| install | 1. org.apache.maven.plugins:maven-install-plugin:install |
| deploy | 1. org.apache.maven.plugins:maven-deploy-plugin:deploy |

h2. jbi-service-assembly

This packaging identifies a Maven2 project as being the development of a service assembly.
The associated language is Maven2's default language.

The build life cycle of a service assembly is:

|| Phases || Goals ||
| package | 1. org.ow2.petals:maven-petals-plugin:jbi-package |
| install | 1. org.apache.maven.plugins:maven-install-plugin:install |
| deploy | 1. org.apache.maven.plugins:maven-deploy-plugin:deploy |

h2. jbi-shared-library

This packaging identifies a Maven2 project as being the development of a shared-library.
The associated language is Java, which allows to use *maven-eclipse-plugin* to make this project an Eclipse project.

The build life cycle of a shared-library is:

|| Phases || Goals ||
| process-ressources | 1. org.apache.maven.plugins:maven-resources-plugin:resources |
| compile | 1. org.apache.maven.plugins:maven-compiler-plugin:compile |
| process-test-ressources | 1. org.apache.maven.plugins:maven-resources-plugin:testResources |
| test-compile | 1. org.apache.maven.plugins:maven-compiler-plugin:testCompile |
| test | 1. org.apache.maven.plugins:maven-surefire-plugin:test |
| package | 1. org.apache.maven.plugins:maven-jar-plugin:jar, \\
2. org.ow2.petals:maven-petals-plugin:jbi-package |
| install | 1. org.apache.maven.plugins:maven-install-plugin:install |
| deploy | 1. org.apache.maven.plugins:maven-deploy-plugin:deploy |

h2. Additional jbi resources packaging

For service unit, component, shared library ... you can provided a directory, thank to following xml element _additionalJBIResourceDirectory_, which allows to specify a directory where all contained files will be added to zip archive of the su, sl, component ...

This previous mechanism provide a way to package additional jbi resources into your su, sl, component as in the following example:
{code:lang=xml|title=pom.xml} <build>
<plugins>
<plugin>
<groupId>org.ow2.petals</groupId>
<artifactId>maven-petals-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<additionalJBIResourceDirectory>${project.build.directory}/additionals/</additionalJBIResourceDirectory>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.3</version>
<executions>
<execution>
<id>unpackaging</id>
<phase>process-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>com.ebmwebsourcing.petals-esb-enterprise.usecase1.node2</groupId>
<artifactId>su-filetransfer-P6-provide</artifactId>
<version>0-SNAPSHOT</version>
<type>jbi-service-unit</type>
<overWrite>false</overWrite>
<outputDirectory>${project.build.directory}/additionals/</outputDirectory>
<includes>**/*.wsdl</includes>
<excludes>**/*.class,**/*.jar</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>{code}
In the previous example, during the *mvn clean install* of the su-bpel-S9-provide, maven just unpackage the P6.wsdl located in +su-filetransfer-P6-provide+ dependency and copy the wsdl into 

{noformat}${project.build.directory}/additionals/ --> corresponding to target/additionals/{noformat}After that the maven-petals-plugin take the P6.wsdl file located into target/additionals precised by the following line:
{noformat}<additionalJBIResourceDirectory>${project.build.directory}/additionals</additionalJBIResourceDirectory>{noformat}

and copy this wsdl file into your _su-bpel-S9-provided.zip_ (it will be copy directly at the root path into zip file)

h1. Goals

As explained in introduction, the Petals plugin for Maven2 supports several goals.
This section details and illustrates them.

The available goals are:
* *jbi-package*: used to package a JBI archive.
* *jbi-configure*: used to configure a deliverable JBI archive.
* *jbi-install*: used to install a JBI archive.
* *jbi-start*: used to start a composant or a service assembly.
* *jbi-stop*: used to stop a composant or a service assembly.
* *jbi-uninstall*: used to uninstall a JBI archive.

h2. jbi-package

This goal allows the creation of a JBI archive.
Depending on the project nature (which is defined by its packaging attribute in the pom.xml), the right archive will be created.

{tip}
For a service assembly project, the service-units that are contained in this assembly must be declared as dependencies in the POM.
{tip}

\\
|| Parameter || Type || Default Value || Packaging || Description ||
| jbiName | String | $\{project.artifactId\}-$\{project.version\} | \* | The file name of the JBI archive (no file path or file extension). |
| verbose | boolean | false | \* | Verbose mode. When activated, information logged at the INFO level are displayed. Information from other levels are always displayed, independently of this mode activation. |
| jbiDirectory | String | $\{basedir\}/src/main/jbi | \* | Path to JBI sources. This path contains the JBI descriptor (jbi.xml). Every file being in this directory will be packaged in the JBI archive under the *META-INF* folder. |
| {anchor:jbi-package-updateJbiXml}updateJBIXml | boolean | true | \* | When true, the packaging updates the JBI descriptor from the project's POM. \\
This option must be activated to configure the JBI archive. |
| isStandardServiceUnit | boolean | false | jbi-service-unit | If the JBI update is activated, this parameter will enable/disable the generation of Petals extensions resulting in a deployable service unit. If *false*, a standard service unit will be generated, otherwise a deployable service unit will be packaged. |
| serviceUnitFileNameMappingInSA | String | $$\{artifactId\}-$$\{version\}.$$\{extension\} | jbi-service-assembly | This parameter makes sense only if the [updateJBIXml|#jbi-package-updateJbiXml] option is activated. \\
It defines the name format of JBI archives for the service-units this assembly embeds. It can be used to make them match the content of the JBI descriptor of the assembly. \\
\\
Configuring this parameter should work correctly when the issue [MNG-3558|http://jira.codehaus.org/browse/MNG-3558] is fixed. |
| serviceUnitNameMappingInSA | String | $$\{artifactId\}-$$\{version\} | jbi-service-assembly | This parameter makes sense only if the [updateJBIXml|#jbi-package-updateJbiXml] option is activated. \\
It defines the name format (the <name> mark-up> of service-units embedded by the service assembly archive. \\
\\
Configuring this parameter should work correctly when the issue [MNG-3558|http://jira.codehaus.org/browse/MNG-3558] is fixed. |
| serviceAssemblyNameMapping | String | $$\{artifactId\}-$$\{version\} | jbi-service-assembly | This parameter makes sense only if the [updateJBIXml|#jbi-package-updateJbiXml] option is activated. \\
It defines the format of the service assembly name in the JBI descriptor. \\
\\
Configuring this parameter should work correctly when the issue [MNG-3558|http://jira.codehaus.org/browse/MNG-3558] is fixed. |
| sharedLibraryNameMappingInComponent | String | $$\{artifactId\} | jbi-component | This parameter makes sense only if the [updateJBIXml|#jbi-package-updateJbiXml] option is activated. \\
When a component depends on a shared library, this last one can be automatically added in the component's JBI descriptor. This parameter defines the name of the shared-libraries to add in the JBI descriptor. \\
\\
Configuring this parameter should work correctly when the issue [MNG-3558|http://jira.codehaus.org/browse/MNG-3558] is fixed. |
| componentNameMapping | String | $$\{artifactId\} | jbi-component | This parameter makes sense only if the [updateJBIXml|#jbi-package-updateJbiXml] option is activated. \\
This parameter defines the name format of the component in the JBI descriptor. \\
\\
Configuring this parameter should work correctly when the issue [MNG-3558|http://jira.codehaus.org/browse/MNG-3558] is fixed. |
| sharedLibraryNameMapping | String | $$\{artifactId\} | jbi-shared-library | This parameter makes sense only if the [updateJBIXml|#jbi-package-updateJbiXml] option is activated. \\
This parameter defines the name format of the shared library in the JBI descriptor. \\
\\
Configuring this parameter should work correctly when the issue [MNG-3558|http://jira.codehaus.org/browse/MNG-3558] is fixed. |
| includeConfiguration \\ | boolean \\ | true \\ | \* \\ | Flag to activate JBI archive configuration when packaging it. To authorize the component configuration when packaging it, JBI descriptor update MUST be activated (see [updateJBIXml|#jbi-package-updateJbiXml]). \\
\\
If one of files needed by the component configuration is missing, no configuration is applied. \\ |
| jbiIdentifiersMappingFile | String | jbi-identifiers-mapping-file.properties | \* \\ | JBI identifiers mapping configuration file. Must be available through the plug-in class-path. \\
Each file line contains a key and a value. The value is used as expression defining the JBI identifier of the artifact matching the key. The key is composed of 4 mandatory fields separated by ":" (caution to use the escape character), each field can contain the value "*" to match any value: \\
# groupId,
# artifactId,
# version,
# packaging: one of jbi-component, jbi-shared-library, jbi-service-unit, jbi-service-assembly. \\
\\
Example, the following mapping rules define that all component identifiers contain the major version part except for the BC Soap:
{code} org.ow2.petals\:petals-bc-soap\:*\:jbi-component = ${artifactId}
*\:*\:*\:jbi-component = ${artifactId}-${version.major}
{code} |
| jbiIdentifiersMappingFileURL | URL | \- \\ | \* \\ | If the JBI shared library list mapping configuration file (jbiSharedLibrariesMappingFile) does not exist through the class-path, the file is look for according to this URL. |
| jbiVersionsMappingFile | String | jbi-versions-mapping-file.properties | \* \\ | JBI versions mapping configuration file. Must be available through the plug-in class-path. \\
Each file line contains a key and a value. The value is used as expression defining the JBI version of the artifact matching the key. The key is composed of 4 mandatory fields separated by ":" (caution to use the escape character), each field can contain the value "*" to match any value: \\
# groupId,
# artifactId,
# version,
# packaging: one of jbi-component, jbi-shared-library, jbi-service-unit, jbi-service-assembly. \\
\\
Example, the following mapping rules define that all shared libraries version identifiers are the major version: \\
{code}
*\:*\:*\:jbi-shared-library = ${version.major}
{code} |
| jbiVersionsMappingFileURL | URL | \- \\ | \* \\ | If the JBI versions mapping configuration file (jbiVersionsMappingFile) does not exist through the class-path, the file is look for according to this URL. |
| toExcludes | String | \- \\ | jbi-component \\
jbi-shared-library \\ | This parameter makes sense only if the [updateJBIXml\|#jbi-package-updateJbiXml] option is activated. It contains a list a JAR files (comma separated) to exclude from the packaging. \\ |
| downloadAndPackageWsdlResources | boolean | false | jbi-service-unit | If true, imports used in the WSDL of an SU will be resolved and packaged inside the service unit JBI archive. |

h3. How is updated the JBI descriptor ?

As explain below, the parameter [updateJBIXml|#jbi-package-updateJbiXml] is used to generated the JBI descriptor from the Maven POM file. Updates are done according to the nature of the JBI archive and following rules.

h4. JBI descriptor updates of a component archive

|| JBI descriptor node \\ || Source of the value \\ ||
| jbi/component/identification/name | The value is controlled by the parameter 'componentNameMapping' and identification values defined in the POM file of the component project. Can be overridden by the content of the configuration parameters if artifact configuration is enabled (includeConfiguration). \\ |
| jbi/component/identification/description | The value is the content of the tag <description> of the POM file, if not null. Otherwise the initial value is kept. \\ |
| jbi/component/component-class-path | Contains all dependencies resolved by Maven. Transitive dependencies of shared-library are not included. \\
Initial content is kept, even if not contained in the dependencies resolved by Maven. \\ |
| jbi/component/bootstrap-class-path | Same as jbi/component/component-class-path |
| jbi/component/shared-library | If the configuration mode is enabled (includeConfiguration): \\
* a tag <shared-library> is created for each shared library declared in:
** the configuration files (jbiSharedLibrariesMappingFile or jbiSharedLibrariesMappingFileURL), if they exist.
** otherwise, in the project POM file. shared library must be declared as a provided dependency with type set to 'jbi-shared-library'.
* If an identifier mapping is defined (see jbiIdentifiersMappingFile or jbiIdentifiersMappingFileURL) for the shared library, the resulting identifier is used as JBI identifier. Otherwise, it will be defined by the parameter 'sharedLibraryNameMappingInComponent'.
* If a version mapping configuration exists (jbiVersionsMappingFile or jbiVersionsMappingFileURL) for the shared library, the resulting value is used as version attribute of the shared library. Otherwise, the version defined into the POM is used. |

h4. JBI descriptor updates of a service unit

|| JBI descriptor node \\ || Source of the value \\ ||
| jbi/services/consumes/\* | Each placeholder as $\{my_variable} is replaced by the value of the property, defined in the POM, that as the same name. \\ |
| jbi/services/provides/\* | Same as previous one. \\ |

h4. JBI descriptor updates of a service assembly

|| JBI descriptor node \\ || Source of the value \\ ||
| jbi/service-assembly/identification/name | The value is controlled by the parameter 'serviceAssemblyNameMapping' and identification values defined in the POM file of the component project. Can be overridden by the content of the configuration parameters if artifact configuration is enabled (includeConfiguration). |
| jbi/service-assembly/identification/description | The value is the content of the tag <description> of the POM file, if not null. Otherwise the initial value is kept. |
| jbi/service-assembly/service-unit/identification/name | The value is controlled by the parameter 'serviceUnitNameMappingInSA' and identification values defined in the POM file of the service units. Can be overridden by the content of the configuration parameters if artifact configuration is enabled (includeConfiguration). |
| jbi/service-assembly/service-unit/identification/description | The value is the content of the tag <description> of the service unit POM file. |
| jbi/service-assembly/service-unit/target/artifacts-zip | The value is controlled by the parameter 'serviceUnitNameMappingInSA'. |
| jbi/service-assembly/service-unit/target/component-name | Content of the tag jbi/component/identification/name of the JBI descriptor of the component on which the service unit must be deployed. It's needed that the component is declared as dependency into the service unit project. Can be overridden by the content of the configuration parameters if artifact configuration is enabled (includeConfiguration). |

h4. JBI descriptor updates of a shared library

|| JBI descriptor node \\ || Source of the value \\ ||
| jbi/shared-library/@version | If the configuration mode is enabled (includeConfiguration): \\
* if a version mapping exists (jbiVersionsMappingFile orjbiVersionsMappingFileURL ) for the shared library, it is used to define the version attribute. Otherwise the version attribute is defined by the version declared in the POM file of the shared library. \\
otherwise: \\
* the version attribute is defined by the version declared in the POM file of the shared library. |
| jbi/shared-library/identification/name | If the configuration mode is enabled (includeConfiguration): \\
* if a identifier mapping exists (jbiIdentifiersMappingFile or jbiIdentifiersMappingFileURL) for the shared library, it is used to define the JBI identifier. Otherwise it is defined by the parameter 'sharedLibraryNameMappingInComponent'. \\
otherwise: \\
* the JBI identifier is defined by the parameter 'sharedLibraryNameMappingInComponent'. |
| jbi/shared-library/identification/description | The value is the content of the tag <description> of the POM file, if not null. Otherwise the initial value is kept. \\ |
| jbi/shared-library/shared-library-class-path | Defined according to all dependencies (direct and transitive) defined in the POM of the shared library. \\ |

h2. jbi-configure

This goal allows the configuration of a JBI archive. Depending on the JBI archive nature (which is defined by its packaging attribute), the right configuration archive will be applied. Only deliverable JBI archives (component, service assembly and shared library) can be configured by this goal, ie. service unit archive is excluded. The main use-case is the configuration of a JBI archive delivered by a provider.

{tip}
Configuration of a service assembly, ans its service units, is not implemented yet.
{tip}

h3. Use-case example

{note}

Since the version 2.4.0 of the Maven Petals Plugin, no more dummy POM file is required to run following usecases fully on command line.

But, to run following usecases them using a configuration packaged as Maven artifact (org.foo.bar:configuration:1.0.0), it is needed to have the following dummy POM file:

{code:language=xml|theme=Eclipse}
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

...

Wiki

All versions of Petals ESB

Helpful links

Maven Petals Plug-in 2.4.0-SNAPSHOT

Changes (2)