Petals Documentation > Petals ESB > Petals Components > Maven Petals Plug-in > Maven Petals Plug-in 3.4.0+

Maven Petals Plug-in 3.4.0+

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-validate: used to validate a JBI archive project,
    • jbi-package: used to create a JBI archive.
    • jbi-configure: used to configure a deliverable JBI archive.
Java 17 or upper is required to run this version of the Maven Petals Plugin.
Maven 3.9.1 or upper is required to run this version of the Maven Petals Plugin.
This version must be used with elements of Petals ESB 5.4.0+ distributions.
Starting with version 3.0.0 of the plugin, the id of the maven artefact changed from maven-petals-plugin to petals-maven-plugin.
Table of content
Contributors
No contributors found for: authors on selected page(s)

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.

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

jbi-component

This packaging identifies a Maven project as being the development of a JBI component (either a binding component, or a service engine).
The associated language is Java.

The build life cycle of a JBI component is:

Phases Goals
validate 1. org.ow2.petals:petals-maven-plugin:jbi-validate
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:petals-maven-plugin:jbi-package
install 1. org.apache.maven.plugins:maven-install-plugin:install
deploy 1. org.apache.maven.plugins:maven-deploy-plugin:deploy

jbi-service-unit

This packaging identifies a Maven project as being the development of a service-unit.
The associated language is Java.

The build life cycle of a service-unit is:

Phases Goals
validate 1. org.ow2.petals:petals-maven-plugin:jbi-validate
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:petals-maven-plugin:jbi-package
install 1. org.apache.maven.plugins:maven-install-plugin:install
deploy 1. org.apache.maven.plugins:maven-deploy-plugin:deploy

jbi-service-assembly

This packaging identifies a Maven project as being the development of a service assembly.
The associated language is Maven's default language (i.e., none).

The build life cycle of a service assembly is:

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

jbi-shared-library

This packaging identifies a Maven project as being the development of a shared-library.
The associated language is Java.

The build life cycle of a shared-library is:

Phases Goals
validate 1. org.ow2.petals:petals-maven-plugin:jbi-validate
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:petals-maven-plugin:jbi-package
install 1. org.apache.maven.plugins:maven-install-plugin:install
deploy 1. org.apache.maven.plugins:maven-deploy-plugin:deploy

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:

pom.xml
 <build>
    <plugins>
      <plugin>
	<groupId>org.ow2.petals</groupId>
	<artifactId>petals-maven-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>

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 

${project.build.directory}/additionals/ --> corresponding to target/additionals/

After that the petals-maven-plugin take the P6.wsdl file located into target/additionals precised by the following line:

<additionalJBIResourceDirectory>${project.build.directory}/additionals</additionalJBIResourceDirectory>

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

Goals

As explained in introduction, the Petals plugin for Maven 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-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.

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


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.
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 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. Maven project properties completed with 'version.major' and 'version.minor' can be used as expression patterns.

See how to escape property resolution to be able to correctly set value for this parameter.
serviceUnitNameMappingInSA String $${artifactId}-$${version} jbi-service-assembly This parameter makes sense only if the updateJBIXml option is activated.
It defines the name format (the <name> mark-up) of service-units embedded by the service assembly archive. Maven project properties completed with 'version.major' and 'version.minor' can be used as expression patterns.

See how to escape property resolution to be able to correctly set value for this parameter.
serviceAssemblyNameMapping String $${artifactId}-$${version} jbi-service-assembly This parameter makes sense only if the updateJBIXml option is activated.
It defines the format of the service assembly name in the JBI descriptor. Maven project properties completed with 'version.major' and 'version.minor' can be used as expression patterns.

See how to escape property resolution to be able to correctly set value for this parameter.
sharedLibraryNameMappingInComponent String $${artifactId} jbi-component This parameter makes sense only if the 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. Maven project properties completed with 'version.major' and 'version.minor' can be used as expression patterns.

See how to escape property resolution to be able to correctly set value for this parameter.
componentNameMapping String $${artifactId} jbi-component This parameter makes sense only if the updateJBIXml option is activated.
This parameter defines the name format of the component in the JBI descriptor. Maven project properties completed with 'version.major' and 'version.minor' can be used as expression patterns.

See how to escape property resolution to be able to correctly set value for this parameter.
sharedLibraryNameMapping String $${artifactId} jbi-shared-library This parameter makes sense only if the updateJBIXml option is activated.
This parameter defines the name format of the shared library in the JBI descriptor. Maven project properties completed with 'version.major' and 'version.minor' can be used as expression patterns.

See how to escape property resolution to be able to correctly set value for this parameter.
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).

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:
  1. groupId,
  2. artifactId,
  3. version,
  4. 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: 
     org.ow2.petals\:petals-bc-soap\:*\:jbi-component = ${artifactId}
*\:*\:*\:jbi-component = ${artifactId}-${version.major}
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:
  1. groupId,
  2. artifactId,
  3. version,
  4. 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: 
    *\:*\:*\:jbi-shared-library = ${version.major}
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\ 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.
attachJar boolean false * If true, the jar will be installed and deployed alongside the JBI component's zip into Maven repositories.
jbiComponentUsed String with pattern "<groupId>:<artifactId>" - jbi-service-unit If several JBI component dependencies are declared, this parameter identifies the JBI component to use to run the service unit. To use this parameter, the parameter 'updateJBIXml' must be set to true.

How is updated the JBI descriptor ?

As explain below, the parameter 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.

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.

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.

JBI descriptor updates of a service assembly

If there is no jbi.xml file present in the source tree, petals-maven-plugin will generate one by itself based on the dependencies declared in the pom.xml
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).

JBI descriptor updates of a shared library

If there is no jbi.xml file present in the source tree, petals-maven-plugin will generate one by itself based on the dependencies declared in the pom.xml
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.

How to escape "$" to avoid property resolution ?

For some parameters it is needed to set value as: "$${artifactId}-$${version}", and associated properties must not be resolved. The sign "$" must be escaped as following in the POM file:

   <properties>
      <dollar>$</dollar>
   </properties>

   <build>
      <plugins>
         <plugin>
            <groupId>org.ow2.petals</groupId>
            <artifactId>petals-maven-plugin</artifactId>
            <configuration>
               <serviceUnitNameMappingInSA>${dollar}${dollar}{artifactId}-${dollar}${dollar}{version}</serviceUnitNameMappingInSA>
            </configuration>
         </plugin>
      </plugins>
   </build>

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.

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

Use-case example

Since the version 2.4.0 of the Maven Petals Plugin, no more dummy POM file is required to run following usecases on command line.
But, to run 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: 
<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">

        <modelVersion>4.0.0</modelVersion>

        <name>Dummy POM</name>
        <artifactId>foo-bar</artifactId>
        <groupId>com.foo.bar</groupId>
        <version>0-SNAPSHOT</version>
        <packaging>pom</packaging>

        <build>
         <plugins>
            <plugin>
              <groupId>org.ow2.petals</groupId>
              <artifactId>petals-maven-plugin</artifactId>
              <version>2.3.0</version>
              <extensions>true</extensions>
              <dependencies>
               <dependency>
                  <groupId>org.foo.bar</groupId>
		  <artifactId>configuration</artifactId>
		  <version>1.0.0</version>
               </dependency>
              </dependencies>
            </plugin>
         </plugins>
        </build>

</project>

Use-case 1 : How to set a JMS driver into a component

For example, we wish, on the same JBI container:

  • to use the ActiveMQ v4.1.1 as JMS server and the BC JMS to interact with Petals ESB through JMS messages. So the BC JMS needs the shared library associated  to its ActiveMQ server version.
  • to use the ActiveMQ v5.2.0 as JMS server and the BC Soap to interact with Petals ESB through SOAP over JMS. So the BC Soap needs the shared library associated  to its ActiveMQ server version.

In one hand, we need to deploy these shared libraries on the JBI container. So, each shared library MUST have a different JBI identifier name, for example petals-sl-jms-activemq-4 et petals-sl-jms-activemq-5.

In other hand, we don't want to change the content of the component JBI descriptor when upgrading a shared library because of bug fixes. So, we can you use the major digit of the version as version attribute for shared library identifier.

So, we need to inject this JBI identifier name and version attribute of the shared libraries in the JBI components:

  • First, we configure the shared libraries using the goal 'jbi-configure':
mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals -DartifactId=petals-sl-jms-activemq -Dversion=4.1.1 -DjbiIdentifiersMappingFileURL=http://myhost:myport/myPath/jbi-identifiers-mapping-file.properties

mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals -DartifactId=petals-sl-jms-activemq -Dversion=5.2.0 -DjbiIdentifiersMappingFileURL=http://myhost:myport/myPath/jbi-identifiers-mapping-file.properties
  • Next, we configure the components:
mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals -DartifactId=petals-bc-jms -Dversion=3.1.1 -DjbiIdentifiersMappingFileURL=http://myhost:myport/myPath/jbi-identifiers-mapping-file.properties -DjbiSharedLibrariesMappingFileURL=http://myhost:myport/myPath/jbi-shared-libraries-list-mapping-file.properties -DjbiVersionsMappingFileURL=http://myhost:myport/myPath/jbi-versions-mapping-file.properties

mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals -DartifactId=petals-bc-soap -Dversion=4.0.2 -DjbiIdentifiersMappingFileURL=http://myhost:myport/myPath/jbi-identifiers-mapping-file.properties -DjbiSharedLibrariesMappingFileURL=http://myhost:myport/myPath/jbi-shared-libraries-list-mapping-file.properties -DjbiVersionsMappingFileURL=http://myhost:myport/myPath/jbi-versions-mapping-file.properties
  • using the following content of the file 'jbi-identifiers-mapping-file.properties':
*\:*\:*\:jbi-component = ${artifactId}-${version.major}
*\:*\:*\:jbi-shared-library = ${artifactId}-${version.major}
*\:*\:*\:jbi-service-unit = ${artifactId}-${version}
*\:*\:*\:jbi-service-assembly = ${artifactId}-${version}
  • using the following content of the file 'jbi-shared-libraries-list-mapping-file.properties':
org.ow2.petals\:petals-bc-jms\:*\:1 = org.ow2.petals:petals-sl-jms-activemq:4.1.1
org.ow2.petals\:petals-bc-soap\:*\:1 = org.ow2.petals:petals-sl-jms-activemq:5.2.0
  • using the following content of the file 'jbi-versions-mapping-file.properties':
*\:*\:*\:jbi-shared-library = ${version.major}

Use-case 2 : How to package an interceptor

The Petals CDK proposes some extension points to add specific processing. These points are named 'interceptors'. An interceptor must be packaged into the JBI component archive. This packaging can be done by the goal 'jbi-configure'.

For example, we wish to package our interceptor, available as a Maven artifact: org.ow2.petals.samples:my-interceptor:1.0.0:jar, into the BC Soap. So we will configure the BC Soap with an extra class-path element (our interceptor). And, as our interceptor is only needed to the component runtime, not to the component bootstrap, we will use the following command line:

mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals -DartifactId=petals-bc-soap -Dversion=4.0.2 -DjbiExtraComponentClasspathMappingURL=file:///home/myuser/my-extra-component-classpath-mapping.properties

where the file /home/myuser/my-extra-component-classpath-mapping.properties contains:

org.ow2.petals\:petals-bc-soap\:*\:1=org.ow2.petals.samples\:my-interceptor\:1.0.0

You can enable or disable a interceptor using the configuration file associated to the parameter componentInterceptorCustomizationFile of the goal jbi-configure. The following configuration will configure the interceptors of the component petals-bc-soap: The interceptor MyCustomInterceptorNameNotActivated is disable, the interceptor MyCustomInterceptorNameActivated is enabled with a dedicated parameter.

org.ow2.petals\:petals-bc-soap\:1 = foo.bar.MyInterceptor:MyCustomInterceptorNameNotActivated:false
org.ow2.petals\:petals-bc-soap\:2 = foo.bar.My2ndInterceptor:MyCustomInterceptorNameActivated:true:paramName1:paramValue1

Use-case 3 : How to configure a service unit to use an interceptor

An interceptor must be configured to be executed on needed phases: accept, accept-response, send and send-response associated to the message exchanges.

Such a configuration can be updated directly from the service assembly containing service units without to restart a development cycle. Just use the goal 'jbi-configure' as following:

mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals.samples -DartifactId=interceptor-sa -Dversion=1.0.0 -DserviceInterceptorCustomizationFileURL=file:///home/myuser/service-interceptors-customization.properties -DserviceInterceptionConfigurationName=productionConfiguration

where:

  • org.ow2.petals.samples:interceptor-sa:1.0.0 is the service assembly containing service units to configure,
  • serviceInterceptorCustomizationFileURL specifies a file containing the configurations of interceptors to apply,
  • serviceInterceptionConfigurationName defines the interceptor configuration to apply

The service interceptor customization file contains something like that:

productionConfiguration\:provider\:*\:*\:*\:accept\:1 = MyCustomInterceptorName:paramName1:paramValue1:paramName2:paramValue2
productionConfiguration\:provider\:*\:*\:*\:accept-response\:1 = MyCustomInterceptorName:paramName1:paramValue1:paramName2:paramValue2

devConfiguration\:provider\:*\:*\:*\:accept\:1 = MyCustomInterceptorName:paramName1:paramValue1:paramName2:paramValue2
devConfiguration\:provider\:*\:*\:*\:accept\:2 = MyCustomInterceptorName:paramName1:paramValue1
devConfiguration\:provider\:*\:*\:*\:accept-response\:1 = MyCustomInterceptorName:paramName1:paramValue1
devConfiguration\:provider\:*\:*\:*\:accept-response\:2 = MyCustomInterceptorName:paramName1:paramValue1

Use-case 4 : How to install the same component in two different versions on the same container

For example, we wish, on the same JBI container:

  • to use the BC Soap version 3.1.4 to connect old service assemblies,
  • to use the BC Soap version 4.0.5 to use the last functions provided by the BC Soap.

This needs different JBI identifier in each component. So we can suffix the JBI identifier with the major digit of the version two create different identifiers for each component:

mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals -DartifactId=petals-bc-soap -Dversion=3.1.4 -DjbiIdentifiersMappingFileURL=http://myhost:myport/myPath/jbi-identifiers-mapping-file.properties

mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals -DartifactId=petals-bc-soap -Dversion=4.0.5 -DjbiIdentifiersMappingFileURL=http://myhost:myport/myPath/jbi-identifiers-mapping-file.properties

using the following content of the file 'jbi-identifiers-mapping-file.properties':

*\:*\:*\:jbi-component = ${artifactId}-${version.major}
*\:*\:*\:jbi-shared-library = ${artifactId}-${version.major}
*\:*\:*\:jbi-service-unit = ${artifactId}-${version}
*\:*\:*\:jbi-service-assembly = ${artifactId}-${version}
To use a configuration available as Maven artifact, use the following command line: 
mvn org.ow2.petals:petals-maven-plugin:2.4.0:jbi-configure -DgroupId=org.ow2.petals -DartifactId=petals-bc-soap -Dversion=3.1.4 -DjbiIdentifiersMappingFile=jbi-identifiers-mapping-file.properties

where jbi-identifiers-mapping-file.properties is available as resource into the configuration Maven artifact.

Don't forget to configure your service assemblies to be able to deploy them on the right component identified by the right JBI identifier.

Parameters

Parameter Type Default Value Packaging Description
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.
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: 

    org.ow2.petals\:petals-bc-soap\:*\:jbi-component = ${artifactId}
*\:*\:*\:jbi-component = ${artifactId}-${version.major}

jbiIdentifiersMappingFileURL URL -
*
If the JBI identifiers mapping configuration file (jbiIdentifiersMappingFile) does not exist through the classpath, the file is look for according to this URL. This parameter can be used to have a JBI identifiers mapping configuration located in a file of the current project: {{ file://$

{basedir}/src/main/jbi-configure/jbiIdentifiersMappingFile-InstComp0.properties}}

jbiSharedLibrariesMappingFile String jbi-shared-libraries-list-mapping-file.properties *
JBI shared library list 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 a Maven artifact to use as shared library by the artifact matching the key. Use one line per shared library.
The key is composed of 4 mandatory fields separated by ":" (caution to use the escape character), each field (except the fourth) can contain the value "*" to match any value:
  • groupId,
  • artifactId,
  • version,
  • ordering number: in case of several shared library this field will define the declaration order of shared libraries. In case of only one sahred library use the value "1".
    The value is composed of 3 mandatory fields separated by ":" defining a Maven artifact to use as shared library:
  • groupId,
  • artifactId,
  • version.
    Example, the following mapping rules define that all versions of the BC JMS will use the shared library including the ActiveMQ JMS client and an other one: 

    org.ow2.petals\:petals-bc-jms\:*\:1 = org.ow2.petals:petals-sl-jms-activemq:5.2.0
org.ow2.petals\:petals-bc-jms\:*\:2 = org.ow2.petals:petals-sl-jms-otherjmsprovider:1.0.0

jbiSharedLibrariesMappingFileURL URL -
*
If the JBI shared library list mapping configuration file (jbiSharedLibrariesMappingFile) does not exist through the classpath, 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 plugin classpath.
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: 

    *\:*\:*\:jbi-shared-library = ${version.major}

jbiVersionsMappingFileURL URL -
*
If the JBI versions mapping configuration file (jbiVersionsMappingFile) does not exist through the classpath, the file is look for according to this URL.
sharedLibraryNameMappingInComponent String $${artifactId} jbi-component This parameter is used as pattern to defined the JBI identifier name of a shared library into the component JBI descriptor if nothing is defined into mapping files (jbiIdentifiersMappingFile or jbiIdentifiersMappingFileURL)
Configuring this parameter should work correctly when the issue MNG-3558 is fixed.
groupId String -
*
GroupId of the deliverable JBI artefact to configure.
artifactId String -
*
ArtifactId of the deliverable JBI artefact to configure.
version String -
*
Version of the deliverable JBI artefact to configure.
outputDirectory File
${project.build.directory} *
Configured JBI artifact output directory
targetName String -
*
Configured JBI artifact target file name, without the extension (.zip)
jbiExtraBootstrapClasspathMappingFile String
jbi-extra-bootstrap-classpath-mapping-file.properties jbi-component
Extra bootstrap class-path elements list 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 a Maven artifact to use as extra class-path elements by the artifact matching the key. Use one line per extra class-path element.
The key is composed of 4 mandatory fields separated by ":" (caution to use the escape character), each field (except the fourth) can contain the value "*" to match any value:
  • groupId,
  • artifactId,
  • version,
  • ordering number: in case of several artifacts completing the classpath elements, this field will define the declaration order of artifact. In case of only one artifact use the value "1".
    The value is composed of 3 mandatory fields and 1 optional field separated by ":" defining a Maven artifact to use as extra class-path element:
  • groupId,
  • artifactId,
  • version,
  • packaging (optional, default is 'jar').
    Example, the following mapping rules define that all versions of the BC SOAP will use the extra bootstrap class-path elements provided by all dependencies of the artifact com.foo.bar:foo-bar:1.2.0 and artifact com.foo.bar:foo-resources:1.2.0:zip : 
    org.ow2.petals\:petals-bc-soap\:*\:1=com.foo.bar:foo-bar:1.2.0
org.ow2.petals\:petals-bc-soap\:*\:2=com.foo.bar:foo-resources:1.2.0:zip
jbiExtraBootstrapClasspathMappingFileURL URL
-
jbi-component
If the extra bootstrap class-path elements list mapping configuration file (jbiExtraBootstrapClasspathMappingFile) does not exist through the class-path, the file is look for according to this URL.
jbiExtraComponentClasspathMappingFile String
jbi-extra-component-classpath-mapping-file.properties jbi-component Extra component class-path elements list 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 a Maven artifact to use as extra class-path elements by the artifact matching the key. Use one line per extra class-path element.
The key is composed of 4 mandatory fields separated by ":" (caution to use the escape character), each field (except the fourth) can contain the value "*" to match any value:
  • groupId,
  • artifactId,
  • version,
  • ordering number: in case of several artifacts completing the classpath elements, this field will define the declaration order of artifact. In case of only one artifact use the value "1".
    The value is composed of 3 mandatory fields and 1 optional field separated by ":" defining a Maven artifact to use as extra class-path element:
  • groupId,
  • artifactId,
  • version,
  • packaging (optional, default is 'jar').
    Example, the following mapping rules define that all versions of the BC SOAP will use the extra component class-path elements provided by all dependencies of the artifact com.foo.bar:foo-bar:1.2.0 and artifact com.foo.bar:foo-resources:1.2.0:zip : 

    org.ow2.petals\:petals-bc-soap\:*\:1=com.foo.bar:foo-bar:1.2.0
org.ow2.petals\:petals-bc-soap\:*\:2=com.foo.bar:foo-resources:1.2.0:zip

jbiExtraBootstrapClasspathMappingFileURL URL -
jbi-component If the extra component class-path elements list mapping configuration file (jbiExtraComponentClasspathMappingFile) does not exist through the class-path, the file is look for according to this URL.
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.
componentInterceptorCustomizationFile String component-interceptors-customization.properties jbi-component Component interceptor customization file containing customization of interceptors to package into JBI components. All jars embedded into the JBI component are introspected to discover available interceptors, and each interceptor are automaticaly declared in the JBI component.
The default interceptor declaration is:
  • interceptor name: interceptor class name without package
  • activation state: false
    Each file line contains a key and a value. The value is used as a Maven artifact to identify the interceptor to packaged in JBI components. Use one line per interceptor to declare in a JBI component.
    The key is composed of 4 mandatory fields separated by ":" (caution to use the escape character) to identify th JBI component in which interceptors will be packaged, each field (except the fourth) can contain the value "*" to match any value:
  • groupId,
  • artifactId,
  • version,
  • ordering number: in case of several artifacts completing the classpath elements, this field will define the declaration order of artifact. In case of only one artifact use the value "1".
    The value is composed of 3 mandatory fields following by optional fields separated by ":" customizing the interceptor:
  • interceptor class: it's the full class name of the interceptor, used as key to associate the following customization,
  • interceptor name: name of the interceptor,
  • activation: true activates the interceptor at component level,
  • interceptor parameters list as: param-name-1:param-value-1:param-name-2:param-value-2:...
    Example, the following declaration rules customize the interceptor configuration with specific interceptor name and activation states: 
    org.ow2.petals\:petals-bc-soap\:1 = foo.bar.MyInterceptor:MyCustomInterceptorNameNotActivated:false:paramName1:paramValue1:paramName2:paramValue2:...
org.ow2.petals\:petals-bc-soap\:2 = foo.bar.My2ndInterceptor:MyCustomInterceptorNameActivated:true:paramName1:paramValue1
componentInterceptorCustomizationFileURL URL - jbi-component Component interceptor customization file (componentInterceptorCustomizationFile). If it does not exist through the classpath, the file is look for according to this URL.
serviceInterceptorCustomizationFile String service-interceptors-customization.properties jbi-service-unit Service interceptor customization file containing customization of interceptors to set into service-unit.
Each file line contains a key and a value. The value is used to defined the interceptor configuration to apply on phase identified by the key.
The key is composed of 7 mandatory fields separated by ":" (caution to use the escape character) to identify the phase on which the interception occurs:
  • configuration name,
  • service unit type: possible values are: provider, consumer,
  • interface name: interface name of the provider or consumer,
  • service name: service name of the provider or consumer,
  • endpoint name: endpoint name of the provider or consumer,
  • phase name: possible values are: accept, accept-response, send and send-response,
  • ordering number: in case of several interceptor to define on one phase, this field will define the declaration order of interceptor. In case of only one, use the value "1".
    The value is composed of 1 mandatory field following by optional fields separated by ":" customizing the interceptor:
  • interceptor name: name of the interceptor defined at component level,
  • interceptor parameters list as: param-name-1:param-value-1:param-name-2:param-value-2:...
    Example, the following declaration rules customize the interceptor configuration with specific interceptor name and activation states: 
    configNameA\:provider\:*\:*\:*\:accept\:1 = MyCustomInterceptorNameNotActivated:paramName1:paramValue1:paramName2:paramValue2:...
configNameA\:provider\:*\:*\:*\:accept\:2 = MyCustomInterceptorNameActivated:paramName1:paramValue1
configNameA\:provider\:*\:*\:*\:accept-response\:1 = MyCustomInterceptorNameNotActivated:paramName1:paramValue1:paramName2:paramValue2:...
configNameA\:provider\:*\:*\:*\:accept-response\:2 = MyCustomInterceptorNameActivated:paramName1:paramValue1
configNameA\:provider\:*\:*\:*\:send\:1 = ...
configNameA\:provider\:*\:*\:*\:send-response\:1 = ...
serviceInterceptorCustomizationFileURL URL - jbi-service-unit Service interceptor customization file (serviceInterceptorCustomizationFile). If it does not exist through the classpath, the file is look for according to this URL.
serviceInterceptionConfigurationName String - jbi-service-unit Service interceptor configuration name to use to configure interceptors of service units.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.