2014/03/12
12 Mar, 2014

[Tutorial] How to create a feature from WSO2 Carbon Component

  • Amal Gunatilake
  • Senior Software Engineer - WSO2
Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.

This tutorial is a continuation of the previous one on How to write a WSO2 Carbon Component. If you don’t have the knowledge on creating a Carbon Component, we recommend you to follow the previous tutorial. In this tutorial, we will be creating a feature and we will install the feature to the Carbon server by adding the feature to the p2-repository.

First of all, in order to follow this tutorial successfully, you will need the following resources and basic knowledge in the following areas.

In the following example, we will show you how to create the feature from the student-manager Carbon component.

Creating a feature from the Carbon Component

This will be done in 3 steps.

  • Creating the server feature
  • Creating the console (UI) feature
  • Creating the composite feature from the above 2 features

Create 3 sub maven projects inside the student-manager-features project.

  • org.wso2.carbon.student.mgt.server.feature
    • artifactId - org.wso2.carbon.student.mgt.server.feature
    • packaging - pom
    • name - WSO2 Carbon - Student Manager Server Feature
    • dependency - org.wso2.carbon.student.mgt
    • plugin - carbon-p2-plugin
  • org.wso2.carbon.student.mgt.ui.feature
    • artifactId - org.wso2.carbon.student.mgt.ui.feature
    • packaging - pom
    • name - WSO2 Carbon - Student Manager UI Feature
    • dependency - org.wso2.carbon.student.mgt.stub
    • dependency - org.wso2.carbon.student.mgt.ui
    • plugin - carbon-p2-plugin
  • org.wso2.carbon.student.mgt.feature
    • artifactId - org.wso2.carbon.student.mgt.feature
    • packaging - pom
    • name - WSO2 Carbon - Student Manager Aggregate Feature
    • dependency - org.wso2.carbon.student.mgt.server.feature (zip type)
    • dependency - org.wso2.carbon.student.mgt.ui.feature (zip type)
    • plugin - carbon-p2-plugin
    • plugin - maven-antrun-plugin

Note: If you are using an IDE to create the projects, it will auto create the source folders. Since these projects do not require any implementations, we can delete the src folders. When adding these projects, the parent project should be updated accordingly with <modules> and the current projects with the <parent> tags. If you are using an IDE, it will auto generate them.

Download and put the feature.properties file into the student-manager-features folder. This will prompt the user during the installation.

 

The folder structure will look like the image shown below.

Folder structure

  • org.wso2.carbon.student.mgt.server.feature → pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>org.wso2.carbon</groupId>
        <artifactId>student-manager-features</artifactId>
        <version>4.2.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>org.wso2.carbon.student.mgt.server.feature</artifactId>
    <packaging>pom</packaging>
    <name>WSO2 Carbon - Student Manager Server Feature</name>

    <dependencies>
        <dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.student.mgt</artifactId>
            <version>4.2.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.wso2.maven</groupId>
                <artifactId>carbon-p2-plugin</artifactId>
                <version>1.5.3</version>
                <executions>
                    <execution>
                        <id>p2-feature-generation</id>
                        <phase>package</phase>
                        <goals>
                            <goal>p2-feature-gen</goal>
                        </goals>
                        <configuration>
                            <id>org.wso2.carbon.student.mgt.server</id>
                            <propertiesFile>../feature.properties</propertiesFile>
                            <adviceFile>
                                <properties>
                                    <propertyDef>org.wso2.carbon.p2.category.type:server</propertyDef>
                                    <propertyDef>org.eclipse.equinox.p2.type.group:false</propertyDef>
                                </properties>
                            </adviceFile>
                            <bundles>
                                <bundleDef>org.wso2.carbon:org.wso2.carbon.student.mgt</bundleDef>
                            </bundles>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>
  • org.wso2.carbon.student.mgt.ui.feature → pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>org.wso2.carbon</groupId>
        <artifactId>student-manager-features</artifactId>
        <version>4.2.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>org.wso2.carbon.student.mgt.ui.feature</artifactId>
    <name>WSO2 Carbon - Student Manager UI Feature</name>

    <dependencies>
        <dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.student.mgt.stub</artifactId>
            <version>4.2.0</version>
        </dependency>
        <dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.student.mgt.ui</artifactId>
            <version>4.2.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.wso2.maven</groupId>
                <artifactId>carbon-p2-plugin</artifactId>
                <version>1.5.3</version>
                <executions>
                    <execution>
                        <id>p2-feature-generation</id>
                        <phase>package</phase>
                        <goals>
                            <goal>p2-feature-gen</goal>
                        </goals>
                        <configuration>
                            <id>org.wso2.carbon.student.mgt.ui</id>
                            <propertiesFile>../feature.properties</propertiesFile>
                            <adviceFile>
                                <properties>
                                    <propertyDef>org.wso2.carbon.p2.category.type:console</propertyDef>
                                    <propertyDef>org.eclipse.equinox.p2.type.group:false</propertyDef>
                                </properties>
                            </adviceFile>
                            <bundles>
                                <bundleDef>org.wso2.carbon:org.wso2.carbon.student.mgt.stub</bundleDef>
                                <bundleDef>org.wso2.carbon:org.wso2.carbon.student.mgt.ui</bundleDef>
                            </bundles>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>
  • org.wso2.carbon.student.mgt.feature → pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>org.wso2.carbon</groupId>
        <artifactId>student-manager-features</artifactId>
        <version>4.2.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>org.wso2.carbon.student.mgt.feature</artifactId>
    <packaging>pom</packaging>

    <name>WSO2 Carbon - Student Manager Aggregate Feature</name>

    <dependencies>
        <dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.student.mgt.server.feature</artifactId>
            <version>4.2.0</version>
            <type>zip</type>
        </dependency>
        <dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.student.mgt.ui.feature</artifactId>
            <version>4.2.0</version>
            <type>zip</type>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.wso2.maven</groupId>
                <artifactId>carbon-p2-plugin</artifactId>
                <version>1.5.3</version>
                <executions>
                    <execution>
                        <id>p2-feature-generation</id>
                        <phase>package</phase>
                        <goals>
                            <goal>p2-feature-gen</goal>
                        </goals>
                        <configuration>
                            <id>org.wso2.carbon.student.mgt</id>
                            <propertiesFile>../feature.properties</propertiesFile>
                            <adviceFile>
                                <properties>
                                    <propertyDef>org.eclipse.equinox.p2.type.group:true</propertyDef>
                                </properties>
                            </adviceFile>
                            <includedFeatures>
                                <includedFeatureDef>org.wso2.carbon:org.wso2.carbon.student.mgt.server.feature</includedFeatureDef>
                                <includedFeatureDef>org.wso2.carbon:org.wso2.carbon.student.mgt.ui.feature</includedFeatureDef>
                            </includedFeatures>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-antrun-plugin</artifactId>
                <executions>
                    <execution>
                        <id>clean_target</id>
                        <phase>install</phase>
                        <configuration>
                            <tasks>
                                <delete dir="src/main/resources"/>
                                <delete dir="src/main"/>
                                <delete dir="src"/>
                            </tasks>
                        </configuration>
                        <goals>
                            <goal>run</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Note:

  • org.wso2.carbon.p2.category.type: server | console | common - This property is used to define whether the feature is a back-end (server), UI (console) or a common feature. This property is read by the feature manager for BE, FE filtering
  • org.eclipse.equinox.p2.type.group: true | false - This property is important to be explicitly defined as ‘false’ when the feature is not a group type feature and you don’t want it to be listed in the feature manager UI (we list the group type features in the feature manager UI). For sub features (console, UI), which are dependencies to the aggregate-feature, use this property as false
  • In the server feature, we need to include only the server OSGI bundle <bundleDef>org.wso2.carbon:org.wso2.carbon.student.mgt</bundleDef>
  • In the UI feature, we have to include both ui and stub OSGI bundles as the UI bundle depends on the stub
  • The aggregate feature have dependencies from generated new server and UI features, and when creating the jar to remove the unnecessary src, main, resources folders, maven-antrun-plugin has been used

In order to install the feature to the Carbon server, we have to create a p2-repo.

  • update the student-manager-repository → pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>student-manager</artifactId>
        <groupId>org.wso2.carbon</groupId>
        <version>4.2.0</version>
    </parent>

    <modelVersion>4.0.0</modelVersion>

    <artifactId>wso2carbon-student-mgt-repository</artifactId>
    <packaging>pom</packaging>
    <name>WSO2 Carbon - Student Manager Feature Repository</name>

    <build>
        <plugins>
            <plugin>
                <groupId>org.wso2.maven</groupId>
                <artifactId>carbon-p2-plugin</artifactId>
                <version>1.5.3</version>
                <executions>
                    <execution>
                        <id>2-p2-repo-generation</id>
                        <phase>package</phase>
                        <goals>
                            <goal>p2-repo-gen</goal>
                        </goals>
                        <configuration>
                            <metadataRepository>file:${basedir}/target/p2-repo</metadataRepository>
                            <artifactRepository>file:${basedir}/target/p2-repo</artifactRepository>
                            <publishArtifacts>true</publishArtifacts>
                            <publishArtifactRepository>true</publishArtifactRepository>
                            <featureArtifacts>
                                <featureArtifactDef>
                                    org.wso2.carbon:org.wso2.carbon.student.mgt.feature:4.2.0
                                </featureArtifactDef>
                            </featureArtifacts>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Note: After successfully building the features, we include the final Aggregate feature bundle to the p2-repo.

After building the student-manager-repository by adding the repository (student-manager-repository/target/p2-repo/) to the Carbon server repository, we can install the feature.

Add repo

Go to configurations in the Carbon server instance and click on the Features on the left navigation panel. Then click on the Add repository button.

Add repo settings

Give a name to the repository and enter your local repository full path (student-manager-repository/target/p2-repo).

Install feature

Select the repository from the Repository list, remove the tick from the Group features by category and click on the Find Features button. Select the Student Manager Aggregate and click Install.

You have now successfully created a Carbon Component feature!

 

About Author

  • Amal Gunatilake
  • Senior Software Engineer
  • WSO2