View Source

Overview

The following details divers advanced aspects of Pax Runner profiles. Usual profile usage is explained in user guide. This features are only available starting with release 0.18.0 of Pax Runner.

How profiles works

Pax Runner profiles, specified by using the --profile option are basically just simple, but yet powerful, shortcuts to composite files that are scanned by composite scanner, process that results in a set of files that makes up the specified profile(s), files that will be provisioned to the target framework.
What Pax Runner does is to take each specified profile name and transform it into a composite spec as follow:

scan-composite:mvn:<profiles group id>/<profile name>/<profile version>/composite

where profiles group id is either the group id specified in the profile name or the group id specified by --profilesGroupId or a default group id = org.ops4j.pax.runner.profiles. profile name is the one specified same for profile version, if any

Lets take an example:

pax-run --profiles=p1,p2/1.0,g3/p3/1.5.0

In this case the first profile p1 will be transformed to scan-composite:mvn:org.ops4j.pax.runner.profiles/p1//composite as there is no group (so default group is used) and no version. The second profile that has a version, p2/1.0 will be transformed to scan-composite:mvn:org.ops4j.pax.runner.profiles/p2/1.0/composite. The last profile has both a group and a version, so it will be transformed to scan-composite:mvn:g3/p3/1.5.0/composite. This means that the examaple above is similar to:

pax-run scan-composite:mvn:org.ops4j.pax.runner.profiles/p1//composite
        scan-composite:mvn:org.ops4j.pax.runner.profiles/p2/1.0/composite
        scan-composite:mvn:g3/p3/1.5.0/composite

There are some inherent advantages of using this approach. First of all it means that the profiles will benefit from maven discovery process, meaning searching across different repositories, from local repository to Maven Central and we can version the profiles. As the profiles files are maven artifacts they can be released if if feel in need of having a more strict control of profiles. Even better as they use the "composite" classifier you can release them together with your artifacts or assemblies.

By default we are using the following repository (see also below how you can ops4j:change it): https://scm.ops4j.org/repos/ops4j/projects/pax/runner-repository/, which is hosted in OPS4J Subversion for easy maintenance as you can read bellow.

Maintaining OPS4J hosted Pax Runner profiles

We maintain an "surrogate" Maven repository in the subversion repository of OPS4J. It is a surrogate because it is not actually generated by using maven tools but maintained by hand as it will be explained bellow. The decision to use subversion for this job is due to the benefits we get "for free": same policy as for any other OPS4J project = just create an account and you can start maintaining profiles (yes, as for the projects themselves we are using the "open participation" principle), there are various tools that allow you to checkout, commit the profile files, we can easy track what and when was changed , reverting if necessary.

So, let's get started: checkout the svn repository (example is using the command line but you may use any other svn tool as an IDE for example):

svn co https://scm.ops4j.org/repos/ops4j/projects/pax/runner-repository/

This will create a new directory name runner-repository. Navigate to the root of all profiles:

cd runner-repository/org/ops4j/pax/runner/profiles/

Here you will find all the profiles available as default in Pax Runner. Now you can update an existing profile, add a new version to an existing profile, create a new profile.

Update an existing profile

Lets say you wanna change the log profile version 1.3.0:

First edit and save the file log/1.3.0/log-1.3.0.composite.
Then commit the change by using svn ci log/1.3.0/log-1.3.0.composite -m "My change".
Please do not do this just for fun or training purposes (editing the log profile) as people may depend on its content.

Add a new version to an existing profile

Lets say that Pax Logging 1.4.0 is out and you want to add a profile for it:

First create a directory named 1.4.0 in the log directory. In this directory create a file named log-1.4.0.composite, maybe as a copy of another log profile version.
Edit and save log-1.4.0.composite according to your needs.
Inform Maven about the new version by editing and saving maven-metadata.xml. Add an entry for the new version under the <versions> node, similar to existing ones. If this is the latest released version (as in our example) edit also the <release> tag. Also change the <lastUpdated> tag, where the value is the time stamp in the format YYYYMMDDhhmmss
Last commit you changes by using svn ci log/* -m "Added version 1.4.0 of log profile".

Create a new profile

Lets say you just have an useful profile that you want to share, lets name it foo and the version is 1.0.0:

First create a new directory named foo
Then create another directory named 1.0.0 under foo directory. In this directory create a file named foo-1.0.0.composite
Edit and save the {foo-1.0.0.composite}} including the scanning specs required by your profile. Take a look at other profiles available for guidance
Create a file named maven-metadata.xml in foo directory.

Edit and save maven-metadata.xml with a content like:

<?xml version="1.0" encoding="UTF-8"?>
<metadata>
  <groupId>org.ops4j.pax.runner.profiles</groupId>
  <artifactId>foo</artifactId>
  <version>1.0.0</version>
  <versioning>
    <release>1.0.0</release>
    <versions>
      <version>1.0.0</version>
    </versions>
    <lastUpdated>20090331000000</lastUpdated>
  </versioning>
</metadata>

Note that the <lastUpdated> is the time stamp in the format YYYYMMDDhhmmss

Last commit you changes by using {svn add foo}} and svn ci log/* -m "Added version 1.4.0 of log profile".

Setup default profiles group

When transforming the profile name into a mvn: url, Pax Runner will add a Maven groupId. By default this is org.ops4j.pax.runner.profiles but you can change it by using the --profilesGroupId option as in the following example:

pax-run --profilesGroupId=org.foo.profiles

In this case when using a profile like --profiles=log, the profile definition file will be mvn:org.foo.profiles/log//composite instead of the default mvn:org.ops4j.pax.runner.profiles/log//composite.

Setup profiles repositories

When using profiles in Pax Runner, as you already know the profiles names are transformed into composite scanning specs using the mvn: protocol. This means that the profiles will be looked up from maven repositories (local/remote). When you are using profiles (--profiles), Pax Runner will automatically add a Pax Runner repository to the list of remote repositories and so, Maven url handler will be able to find the profile associated composite file.
The default repository is: http://scm.ops4j.org/repos/ops4j/projects/pax/runner-repository/

But there are cases you may want to change this repository or more repositories. In that case can use the --profilesRepositories option. The value of this property is a comma (,) separated list of repository urls. For example:

pax-run --profilesRepositories=file://Users/Somebody/local-profiles,http://somewhere.org/remote-profiles

In case that your are using the --repositories option and the option value does not start with a plus , the profiles repositories will not be added to the list of repositories searched by Maven url handler, because in that case Pax Runner considers that you are very strict about the repositories to be used.