This documentation is for WSO2 Carbon 4.4.3. View documentation for the latest release.
Using the Carbon P2 Plugin - Carbon 4.4.3 - WSO2 Documentation
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.
||
Skip to end of metadata
Go to start of metadata

Introduction to Carbon P2 plugin

The WSO2 Carbon P2 plugin is a Maven plugin that is used for installing Carbon features in a Carbon product, a P2 repository or a specific product profile.

What is a Carbon feature?

A Carbon feature is an installable form of one or more logically related Carbon components. You can create a Carbon feature by grouping one or more Carbon features. You can install these features into Carbon-based products using the feature manager in the management console of the product, or via the p2-profile-gen Maven goal of the Carbon P2 plugin.

What is a P2 repository?

A P2 repository is a collection of Carbon features. It acts as a feature aggregator. You can point a Carbon product to a P2 repository and install one or more feature(s) from the repository. Once a feature is installed, the feature is copied to the Carbon product.

What is a product profile?

A product profile is a logical grouping of a set of features/components, which creates a virtual boundary for execution. Every Carbon product ships a default profile. With the Carbon P2 plugin, you can create profiles and install Carbon features in the profiles.

A Carbon product (WSO2 ESB, WSO2 AS etc.) is made by installing the relevant Carbon features on top of the Carbon Kernel using the following steps:

  1. Create profiles on top of the Carbon Kernel using the materialize-product Maven goal.
  2. Install the relevant features using the p2-profile-gen Maven goal.

Maven goals in the Carbon P2 plugin

The following table lists the Maven goals that are defined in the P2 plugin, which are used for installing features in Carbon products, P2 repositories and product profiles as explained below. 

PurposeMaven goalConfigurations
Generate Carbon featuresP2-feature-genConfiguring the P2-feature-gen Maven goal

Generate P2 repositories

P2-repo-gen

Configuring the P2-repo-gen Maven goal

Publish a product into a P2 repository

publish-product

Configuring the publish-product Maven goal

Generate product profiles

materialize-product

Configuring the materialize-product Maven goal

Install Carbon features into a product profile

p2-profile-gen

Configuring the p2-profile-gen Maven goal

All these goals are executed during the packaging phase of the Maven build's default life cycle, except the P2-feature-gen Maven goal, which follows a different life cycle. You have the flexibility to configure the behavior of the plugin by passing specific parameters for these Maven goals. See the following section for detailed information on these configurations.

Carbon P2 plugin configurations

The following sections describe the configurations of the Maven goals that are implemented in the Carbon P2 plugin. 

Configuring the P2-feature-gen Maven goal

A sample pom.xml file that is configured using the P2-feature-gen Maven goal is shown below.

<build>
    <plugins>
        	<plugin>
            	<groupId>org.wso2.maven</groupId>
            	<artifactId>carbon-p2-plugin</artifactId>
            	<version>${carbon.p2.plugin.version}</version>
            	<executions>
                	<execution>
                    	<id>p2-feature-generation</id>
                    	<phase>package</phase>
                    	<goals>
                        	<goal>p2-feature-gen</goal>
                    	</goals>
                    	<configuration>
                        	//plugin configuration goes here.
                    	</configuration>
                	</execution>
            	</executions>
        	</plugin>
    </plugins>
</build>

You can modify the above configurations by adding the following parameters within the <configuration> element:

ParameterDescriptionMandatoryExample
id

The Id of the feature being generated.

No<id>org.wso2.carbon.core.feature</id>
copyright

The copyright text that should be attached to the feature.xml file.

No<copyright>COPYRIGHT</copyright>
licenceUrl

The license URL that should be given in the feature.xml file.

No<licenseUrl>LICENSE_URL</licenseUrl>
licenceThe license that should be attached to the feature.xml file.No<license>LICENSE</license>
manifest

This points to the location of the manifest file. The content in this file is considered if the manifest is present when generating the feature.xml file. This manifest file is copied and its content will be updated as the feature.xml file.

No<manifest>LOCATION_OF_THE_MANIFEST_FILE</manifest>
propertyFile

This points to the location of the properties file. Properties in the property file (if exists) are merged with the properties passed to the Maven goal through the <properties> parameter explained below.

No

<propertyFile>PATH_FOR_THE_PROPERTY_FILE</propertyFile>


properties

A collection of key-value pairs passed to the Maven goal, which should be written to the feature.properties output file. 

Yes
<properties>
	<property>
		<name>name1</name
		<value>value1</value>
	</property>
	<property>
		<name>name2</name
		<value>value2</value>
	</property>
</properties>
adviceFile

Content to be written to the p2.inf output file are fed into the p2-feature-gen maven goal using this adviceFile property.

Yes
<adviceFile>
	<properties>
	<propertyDef>org.wso2.carbon.p2.category.type:console</properDef>
<properties>	
</advice>
bundles

Specifies the OSGI bundles that should be included in the feature being created. These bundles should be given as Maven coordinates. The P2 plugin supports 3 variations as shown below:

<bundles>
 	<bundleDef>{groupId}:{artifactId}:{version}</bundleDef>
 	<bundleDef>{groupId}:{artifactId}:{version}:	{compatibility}</bundleDef>
 	<bundleDef>{groupId}:{artifactId}:{compatibility}:{version}</bundleDef>
</bundles>

If the 1st bundle format is used, the default value for compatibility (which is “equivalent”) is used.

The following values are permitted for compatibility;

  • perfect

  • equivalent

  • compatible

  • greaterOrEqual

  • patch
No

-

 includeFeatures

Carbon features that need to be included in the feature being built are specified using the includeFeatures property. These included features are copied to the final output ZIP file. Included features can be given in 4 different ways as shown below.

<includedFeatures>
 <featureDef>{groupId}:{artifactId}</featureDef>        
 <featureDef>{groupId}:{artifactId}:{version}</featureDef>
 <featureDef>{groupId}:{artifactId}:optional</featureDef>
 <featureDef>{groupId}:{artifactId}:{version}:optional</featureDef>
</includedFeature>

If the term “optional” is given as a featureDef, that feature is marked as optional.

No

-

 importFeatures

The dependant features for the feature being built are included here. These import features are included in the feature.xml file, but are not copied to the final ZIP file. Import features can be given in 5 different ways as shown below.

<importFeatures>                              
<featureDef>{featureId}</featureDef>         
<featureDef>{featureId}:{compatibility}</featureDef> 
<featureDef>{featureId}:{compatibility}:{version}</featureDef>
<featureDef>{featureId}:{version}</featureDef> 
<featureDef>{featureId}:{version}:{compatible}</featureDef> 
</importFeatures>

By default, the compatibility is set to "equivalent". If compatibility is set to “optional”, this import feature is marked as “optional”.

The following values are permitted for compatibility;

  • perfect

  • equivalent

  • compatible

  • greaterOrEqual

  • patch
No

-

Configuring the P2-repo-gen Maven goal

A sample pom.xml file that is configured using the P2-repo-gen Maven goal is shown below.

<build>
    <plugins>
        	<plugin>
            	<groupId>org.wso2.maven</groupId>
            	<artifactId>carbon-p2-plugin</artifactId>
            	<version>${carbon.p2.plugin.version}</version>
            	<executions>
                	<execution>
                    	<id>p2-repo-generation</id>
                    	<phase>package</phase>
                    	<goals>
                        	<goal>p2-repo-gen</goal>
                    	</goals>
                    	<configuration>
                        	//plugin configuration goes here.
                    	</configuration>
                	</execution>
            	</executions>
        	</plugin>
    </plugins>
</build>

You can modify the above configurations by adding the following parameters within the <configuration> element:

ParameterDescriptionMandatoryExample
name

The name of the newly created artifact repository. If you do not specify this, the artifact ID of the project is taken by default.

Yes<name>LOCATION_OF_THE_MANIFEST_FILE</name>
metadataRepository

The URL of the location where the metadata repository should be created.
Note that this value should be the same value as for the artifactRepository property explained below. 

Yes<metadataRepository>file:/home/p2-repo</metadataRepository>
artifactRepository

The URL of the location where the artifact repository should be created.

Important: For carbon, both artifacts and metadata reside in the same repository. Therefore, the value for both metadataRepository and artifactRepository should be the same.

Yes

<artifactRepository>file:/home/p2-repo</artifactRepository>

featureArtifacts

The set of features that need to be included in the repository are passed to the p2-repo-gen Maven goal through this parameter. Features can be provided in 2 different ways as shown below.

<featureArtifacts>
   <featureArtifactDef>{groupId}:{artifactId}</featureArtifactDef>
   <featureArtifactDef>{groupId}:{artifactId}:{version}</featureArtifactDef>
<features>

If the version is not given, the plugin tries to extract the version from the project’s dependency list. The Maven goal will search for the given artifact in the local .m2 repository. If it is not found there, the goal will search in the configured remote repositories. Not finding the artifact may cause the Maven goal to terminate with a BUILD FAILURE.

Important: For the plugin to work properly, the artifact representing each feature is required to be specified as a Maven dependency.

Yes

-

bundleArtifacts

The set of bundles that need to be included in the repository are passed to the p2-repo-gen Maven goal through this parameter. Bundle artifacts can be provided in two ways as shown below.

<bundleArtifacts>
       <bundleArtifactDef>{groupId}:{artifactId}</bundleArtifactDef>
       <bundleArtifactDef>{groupId}:{artifactId}:{version}</bundleArtifactDef>
 <bundleArtifacts>

If the version is not given, the Maven goal will search for the given artifact in the local .m2 repository to resolve the version. If it is not found there, the goal will search in the the configured remote repositories. Not finding the artifact may cause the Maven goal to terminate with a BUILD FAILURE. So for the plugin to work properly, the artifact representing each bundle needs to be specified as a Maven dependency.

Yes

-

 

 archiveSpecifies whether the generated artifact should be archived or not. This is a boolean value. Thus, permitted values are either true or false. The default value is false. No <archive>false</archive>

Configuring the publish-product Maven goal

A sample pom.xml file that is configured using the publish-product Maven goal is shown below. 

<build>
    <plugins>
        	<plugin>
            	<groupId>org.wso2.maven</groupId>
            	<artifactId>carbon-p2-plugin</artifactId>
            	<version>${carbon.p2.plugin.version}</version>
            	<executions>
                	<execution>
                    	<id>publishing products</id>
                    	<phase>package</phase>
                    	<goals>
                        	      <goal>publish-product</goal>
                    	</goals>
                    	<configuration>
                        	//plugin configuration goes here.
                    	</configuration>
                	</execution>
            	</executions>
        	</plugin>
    </plugins>
</build>

You can modify the above configurations by adding the following parameters within the <configuration> element:

ParameterDescriptionMandatoryExample
metadataRepository

The URL of the location where the metadata repository should be created.

Note that this value should be the same value as for the artifactRepository property explained below. 

Yes<metadataRepository>file:/home/p2-repo</metadataRepository>
artifactRepository

The URL of the location where the artifact repository is to be created.

Important: For carbon, both artifacts and metadata reside in the same repository. Therefore the value for both metadataRepository and artifactRepository should be the same. 

Yes<artifactRepository>file:/home/p2-repo</artifactRepository>
executable

Points to the executable file.

Yes<executable>${basedir}/target/org.eclipse.equinox.executable_3.5.0.v20110530-7P7NFUFFLWUl76mart</executable>
productConfigurationLocation of the .product file. Yes<productConfigurationFile>${basedir}/carbon.product</productConfigurationFile>

Configuring the materialize-product Maven goal 

A sample pom.xml file that is configured using the materialize-product Maven goal is shown below.

<build>
    <plugins>
        	<plugin>
            	<groupId>org.wso2.maven</groupId>
            	<artifactId>carbon-p2-plugin</artifactId>
            	<version>${carbon.p2.plugin.version}</version>
            	<executions>
                	<execution>
                    	<id>materialize-product</id>
                    	<phase>package</phase>
                    	<goals>
                        	<goal>materialize-product</goal>
                    	</goals>
                    	<configuration>
                        	//plugin configuration goes here.
                    	</configuration>
                	</execution>
            	</executions>
        	</plugin>
	</plugins>
</build>

You can modify the above configurations by adding the following parameters within the <configuration> element.

ParameterDescriptionMandatoryExample
metadataRepository

The URL of the location where the metadata repository should be created.

Note that this value should be the same value as for the artifactRepository property explained below. 

Yes<metadataRepository>file:/home/p2-repo</metadataRepository>
artifactRepository

The URL of the location where the artifact repository should be created.

Important: For carbon, both artifacts and metadata reside in the same repository. Therefore, the value for both metadataRepository and artifactRepository should be the same. 

Yes<artifactRepository>file:/home/p2-repo</artifactRepository>
targetPath

Points to the components folder of the Carbon product in which the profile is being created.

Yes<targetPath>file:${basedir}/target/wso2carbon-core-${carbon.kernel.version}/repository/components</targetPath>
profile

Name of the profile to be created.

Yes<profile>worker</profile>
productConfigurationLocation of the .product file.Yes<productConfigurationFile>${basedir}/carbon.product</productConfigurationFile>

Configuring the p2-profile-gen Maven goal

A sample pom.xml file that is configured using the p2-profile-gen Maven goal is shown below.

<build>
    <plugins>
        	<plugin>
            	<groupId>org.wso2.maven</groupId>
            	<artifactId>carbon-p2-plugin</artifactId>
            	<version>${carbon.p2.plugin.version}</version>
            	<executions>
                	<execution>
                    	<id>feature-installation</id>
                    	<phase>package</phase>
                    	<goals>
                        	<goal>p2-profile-gen</goal>
                    	</goals>
                    	<configuration>
                        	//plugin configuration goes here.
                    	</configuration>
                	</execution>
            	</executions>
        	</plugin>
    </plugins>
</build>

You can modify the above configurations by adding the following parameters within the <configuration> element.

ParameterDescriptionMandatoryExample
destination

Points to the <CARBON_HOME>/repository/components/ directory.

Yes

<destination>/home/Carbon/wso2carbon-4.4.0/repository/components</destination>

profile

The profile that needs to be updated with the new set of features in the destination.

Yes<profile>default</profile>
metadataRepository

The URL of the location where the metadata repository should be created.

Note that this value should be the same value as for the artifactRepository property explained below. 

Yes<metadataRepository>file:/home/p2-repo</metadataRepository>
artifactRepository

The URL of the location where the artifact repository should be created.

Important: For carbon, both artifacts and metadata resides in the same repository. Therefore, the value for both metadataRepository and artifactRepository should be the same. 

Yes<artifactRepository>file:/home/p2-repo</artifactRepository>
features

The features to be installed in the destination profile. Features that you add here should already exist in the P2 repository to which the <repositoryURL> parameter of the plugin points.

 

Yes
<features>
<feature>
   <id>org.wso2.carbon.registry.contentsearch.feature.group</id>
   <version>4.4.0</version>
</feature>
<feature>
   <id>org.wso2.ciphertool.feature.group</id>
   <version>4.4.0</version>
</feature>
</features>

Add the ID of the feature being installed for the <ID> property, and add the version of the feature being installed as the value of the <version> property.

deleteOldProfileFilesSpecifies whether to delete old *.profile folders located in the <CARBON_HOME>/repository/components/p2/org.eclipse.equinox.p2.engine/profileRegistry/ directory. The default value is set to true.No<deleteOldProfileFiles>true</deleteOldProfileFiles>
  • No labels