Guidelines for Carbon Feature Developers

1. Follow the general feature hierarchy when developing Carbon features

• Aggregate/Composite feature
• Server feature
• Console feature
• Common feature (if any)

2.  Follow the general naming convention in features : Just like the feature’s ID is important to identify features at runtime , the name is important for the users to identify features uniquely in the UI. So every feature’s name should follow a convention, be unique and should be self-describing.

3. Use p2 properties meaningfully in the advice file given at the p2-feature-gen goal in your feature’s pom.xml

• org.wso2.carbon.p2.category.type: server | console | common

Above property is used to define whether the feature is a backend (server), UI (console) or a common feature. This property is read by 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 feature manager UI. (We list down 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.

Usage Sample :

<adviceFile>

<properties>

               <propertyDef>org.wso2.carbon.p2.category.type:server</propertyDef>

                       <propertyDef>org.eclipse.equinox.p2.type.group:false</propertyDef>

           </properties>

</adviceFile>

4. Correctly give the relative path to the feature.properties in the feature’s pom: This properties file   contains the license and copyright text to be viewed in feature manager UI. The file is located at branches/4.0.0/features/etc/feature.properties.

The relative path from your feature to this file needs to be given correctly in order to load the license and copyright in the UI

Usage Sample:

<propertiesFile>../../../etc/feature.properties</propertiesFile>

5. Use correct carbon-p2-plugin instruction to construct the features

• bundleDef : Use this when you need to include a component/bundle in your feature. The bundle included is considered as an integral part of the feature and doesn’t support updates during a new feature installation.

Usage Sample :

<bundles>

           <bundleDef>org.wso2.carbon:org.wso2.carbon.security.mgt</bundleDef>

</bundles>

• includedFeatureDef : Use this when you need to include a sub-feature in your composite feature. The included feature is considered a part of your composite feature and it is not enforced by new installations and updates are not supported at the time of installation.

(eg: Include the console, server and common features in your composite feature. And set org.eclipse.equinox.p2.type.group: true only in your composite feature)

Usage Sample :

<includedFeatures> <includedFeatureDef>org.wso2.carbon:org.wso2.carbon.core.common.feature:4.0.2</includedFeatureDef>
<includedFeatures>

• importBundleDef : Use this when you require an external bundle outside your component as a dependency for your feature. This is considered as an optional feature dependency and if specified, is enforced by new installations and supports update at the time of installation.

Usage Sample :

<importBundles>

              <importBundleDef>org.wso2.xkms.wso2:xkms</importBundleDef>

</importBundles>

• importFeatureDef : Use this when you require an external feature as a dependency for your feature. This is considered as an optional feature dependency and if specified, is enforced by new installations and supports update at the time of installation.

Usage Sample :

<importFeatures>    <importFeatureDef>org.wso2.carbon.core.server:${wso2carbon.version}</importFeatureDef>

</importFeatures>

6. Use p2-touchpoint instructions to perform additional configuration operations for the feature.

Using touchpoint instructions we can do things like copying configuration files to target system during a p2 phase (collect, configure, install, uninstall, unconfigure). You can define these touchpoint instructions in the p2.inf file of your feature.

Usage Sample :

instructions.configure = \

org.eclipse.equinox.p2.touchpoint.natives.copy(source:${installFolder}/features/org.wso2.carbon.apimgt.publisher_${feature.version}/publisher/,target:${installFolder}/../deployment/server/jaggeryapps/publisher,overwrite:true);\

Common mistakes in creating features

• Not using  org.eclipse.equinox.p2.type.group:false property in sub-features: Because of this we can see low-level  sub-features listed as top-level features in the featuremanager UI.
  
  
• Not giving the relative path correctly to feature.properties. This causes the license and copyright not being loaded in the feature manager UI.

• Including external features instead of properly defining external dependencies as ImportedFeatures: This makes the included features tightly coupled to the composite feature and doesn’t allow to be updated to a newer version during a new feature installation. This leads to further complications in installing several features/categories at once as there could be newer versions of the included features as dependencies which are supposed to be target update

• Not following the naming convention of features: Some of the existing features have repeated names for sub-features as well as it’s composite. This will confuse the user as it will be hard to differentiate features in the UI. It will also give the impression that a certain feature is duplicated.

• Not using p2-touchpoint instructions to copy required configuration files to the target directories during feature installation phase: Some of our features require additional configuration files copied to the target system in-order to the system to function properly. But in many features in our platform the required config files are copied to the target directory at product build time (in product assembly). This will break the feature installation because the required config files are not copied to target system at feature installation time. This could lead to system malfunction after a feature installation.