Creating a new feature for your application
To create a new feature for your application is not difficult. You need to go to Eclipse and:
- Click on File->New->Project… to create a new Maven project with Maven Wizard.
Figure. New maven project
- The Maven project wizard is simple, just select where you want to locate the new project (by default it will be located in a new file in the workspace). Before clicking next make sure Create a simple project is NOT selected.
Figure. Select project name and location
- To add an Archetype to this list click on Add archetype button. The next step is straight forward, fill in the information you are given about the archetype (Maven will look up this Archetype as it does for any other artifact, by looking up the remote repositories listed in your settings XML. repository URL parameter is not mandatory, as long as you have the universAAL Nexus repository listed in your settings (which you will if you followed the maven configuration procedure)). This step is done only once because the archetype is installed in the local repository, and therefore is listed in the archetype catalog.
- groupID: org.universAAL.samples
- artifactID: karaf.feature-archetype
- version:
Figure. Add feature archetype
- Then look for feature archetype. Once the archetype is selected click next, and fill in the last required information. This is the groupID, artifactID, version that your new project should have.
- Click on finish and you are ready to go (after a while because it could take some time).
Figure. New feature project
Same as above can be achieved through maven commands. After all the Ecplise process we have just explained uses undelying maven processes to achieve this objective (Fill in the version of universAAL you are using).
mvn dependency:get archetype:crawl -DartifactId=org.universAAL.samples -DgroupId=karaf.feature-archetype -Dversion=... -DremoteRepositories=uaal::default::http://depot.universaal.org/maven-repo/releases/,uaal-snapshot::default::http://depot.universaal.org/maven-repo/snapshots/,uaal-p1::default::http://nexus.lst.tfo.upm.es/content/groups/public/
Previous command only needs to be executed once per universAAL version you use (it just downloads and registers the archetype, once registered you can use it as many times as needed)
mvn archetype:generate -DarchetypeArtifactId=org.universAAL.samples -DarchetypeGroupId=karaf.feature-archetype -DarchetypeVersion=...
You now need to modify the feature according to your application. The previous step (either eclipse or maven altenrative) generates an empty src/features/features.xml . Now, it is an example of how it should looks like as a feature. Text in red are conventions in universAAL and musn’t be changed. Text in capitals and bold are texts that must be modified according to your application but also some considerations must be taken into account:
- Applications may be dependent of platform managers, or other modules not included in the coordinator feature, then you need to add the corresponding dependencies
- Add those third-party features/bundles that your application needs and are not provided by the universAAL core. VERY IMPORTANT!!!
- Add ontology features needed from universAAL and/or your own
- Finally, add your bundles
- ensure all your feature repositories (where you'll find your dependency features) are listed.
- ensure you have as many features as you need. You may define features per module, or per functionality, or per application. Take into account what you need for each, and how they are supposed to be deployed. For Example you may have a client and a server features for your application.
- ensure each feature has its own distinct name (different also from imported repositories)
- ensure each feature has listed is dependency features. Concretely look for ontologies, and platform manangers
- ensure each feature has third party library dependencies it needs. They may be available in .ogsi package, which makes it convenient (you may use a standard url as shown for your bundles below). If they are standard Java library jars you need to add wrap: preceding your url so the loader knows.
- ensure each bundle has a correct starting level. For universAAL applications 80 should be ok. Start level indicates the order in which bundles should be loaded, in case of universAAL all its features are defined to start before 80.
- ensure each bundle is started, if needed. This ensures bundles do not need to be started manually after installing a particular feature.
<repository>mvn:GROUP_ID/ARTIFACT_ID/VERSION/xml/features</repository>
…
<feature name="uAAL-Service-SERVICE_NAME" description="SERVICE_DESCRIPTION" version="SERVICE-VERSION" resolver='(obr)'>
<feature>third-party</feature>
<bundle>third-party</bundle>
…
<feature>uAAL-Ont.ONTOLOGY_NAME</feature>
<feature>ontology</feature>
…
<bundle start-level='70' start='true'>mvn:<b>GROUP_ID/ARTIFACT_ID/VERSION</b></bundle>
</feature>
</features>
For more information please read our summary on features, or go in depth reading the karaf manual on provisioning.
Features are installed as normal maven projects from Eclipse or maven command prompt.
In karaf you may use the command:
feature:repo-add mvn:${feature.groupId}/${feature.artifactId}/${feature.version}/xml/features
to make its features available. Replace the variables (expressed in the form ${var}) for the group, artifact and version of the project for your feature.
In order to automatically include your features in the default list of features in a karaf distribution, edit “etc/org.apache.karaf.features.cfg” file of your karaf distribuition and add at featuresRepositories section the provision of your application feature in the form of:
mvn:${feature.groupId}/${feature.artifactId}/${feature.version}/xml/features
Replace the variables (expressed in the form ${var}) for the group, artifact and version of the project for your feature.
To ensure your feature starts when the distribution is started, add the name of your feature at featuresBoot section of the same file.
Run the distribution and enjoy!