The JBoss Tools Locus project

Summary

JBoss Tools Locus is an adjunct to http://www.eclipse.org/orbit/[Eclipse Orbit]. This project's purpose is to package non-OSGi POJO jars as OSGi bundles (wrapping them with additional metadata) and to publish them to an update site from which they can be consumed by p2 based builds and products.

This project's contents should never duplicate what's already in Eclipse Orbit; instead, it should provide newer versions of plugins already in Orbit, or plugins which cannot be included in Orbit for some reason (technical, licensing or otherwise).

Why Locus ?

Locus was created because we started seeing a number of jars being repeately added to JBoss Tools or related plugins which Eclipse Orbit for mixed reasons does not contain. Thus we needed something to provide a repository to be used for builds/downloads.

How do I use a library from Locus

The JBoss Tools Locus update is https://repository.jboss.org/nexus/content/unzip/unzip/org/jboss/tools/locus/jbosstools-locus/[published to Nexus].

You can therefore use Locus bundles in your target platform (eg., https://github.com/jbosstools/jbosstools-integration-stack/blob/master/target-platform/src/targets/integration-stack-base-ea.target#L12-L32[target] file) like this:

[source,xml]

<location includeAllPlatforms="false" includeConfigurePhase="false" includeMode="slicer" includeSource="true" type="InstallableUnit">
  <unit id="org.apache.servicemix.bundles.aopalliance" version="1.0.0.3"/>

  <unit id="org.jboss.tools.locus.jcip.annotations" version="1.0.0.v20131024-0922"/>
  <unit id="org.jboss.tools.locus.sf.saxon" version="9.2.1.v20131024-0922"/>
  <unit id="org.jboss.tools.locus.sf.saxon" version="9.5.1.v20151110-1025"/>
  <unit id="org.jboss.tools.locus.jsonschema2pojo.jsonschema2pojo-core" version="0.4.13.v20160122-1745"/>
  <unit id="org.jboss.tools.locus.apache.directory.bouncycastle.stub" version="1.0.0.v20151110-1025"/>
  <unit id="org.jboss.tools.locus.jaxb-core" version="2.2.7.v20160127-1545"/>
  <unit id="org.jboss.tools.locus.jaxb-impl" version="2.2.7.v20160113-1915"/>
  <unit id="org.jboss.tools.locus.jaxb-xjc" version="2.2.7.v20160125-1950"/>
  <unit id="org.jboss.tools.locus.mockito" version="1.9.5.v20131024-0922"/>

  <unit id="org.springframework.aspects" version="3.1.4.RELEASE"/>
  <unit id="org.springframework.osgi.core" version="1.2.1"/>
  <unit id="org.springframework.osgi.extender" version="1.2.1"/>
  <unit id="org.springframework.osgi.extensions.annotations" version="1.2.1"/>
  <unit id="org.springframework.osgi.io" version="1.2.1"/>
  <repository location="https://repository.jboss.org/nexus/content/unzip/unzip/org/jboss/tools/locus/jbosstools-locus/1.6.0-SNAPSHOT/jbosstools-locus-1.6.0-SNAPSHOT-updatesite.zip-unzip/"/>
</location>

---

Where possible use 'Import-Package' instead of 'Require-Bundle' in your consumer's MANIFEST.MF to reduce sensitivity to different bundlings of the same library.

Why not just use Orbit ?

Eclipse Orbit's http://www.eclipse.org/orbit/[mandate] states:

"The Orbit mandate does not allow the project to be used for
building or maintaining third-party libraries that are not
approved by the Eclipse foundation for us in Eclipse
projects."

This mandate means that if no eclipse.org project requests new jars or updates because of bugs in the Eclipse.org Orbit or a 3rd party jar are missing there will not be any updates/additions. This have lead to us being stuck with older or buggy 3rd party jars than what we would like thus we needed to find another way to handle this.

Thus JBoss Tools Locus exists mainly to support development of http://jboss.org/tools[JBoss Tools], but the Locus site is not tied to any specific release of JBoss Tools.

The site it self is not meant to be used directly by users, but mainly used to have a common set of dependencies that can be used in builds and actual releases.

Maintaining Locus

Rules/Guidelines

The following is the current guidelines for libraries included in Locus. They are heavily based by http://wiki.eclipse.org/Adding_Bundles_to_Orbit[Orbit]'s rules, but adjusted to be more lightweight and with smaller chance of overlap.

1. Do not put anything into Locus before having tried hard to get it into Eclipse Orbit.
   • See http://download.eclipse.org/tools/orbit/downloads/[Orbit builds] to see existing Orbit content.
   • See http://wiki.eclipse.org/index.php/Orbit_Faq[Orbit FAQ] on how to get something into Orbit.
2. Do not include jars directly into the repository, use Maven coordinates for the build as much as possible.
   • Want to keep the repository lean and clean for easy building and contributions.
3. Do not build from source, use the already available public binaries.
   • We are not trying to create forks of libraries.
4. Each plugin should have:
   • LICENSE file with info about the relevant license
   • A matching source bundle
5. Set the Bundle-RequiredExecutionEnvironment header to the absolute minimum JRE required by the library
6. Do always use org.jboss.tools.locus.<libraryname> as bundleid
   • The bundle id is set to Locus to avoid any http://wiki.eclipse.org/Bundle_Naming[potential conflicts] with Orbit.
7. Bundle-Version should be the original library version number followed by .qualifier in the fourth segment. In the event that the original number is already four segments, that version number should be used and then followed by "_qualifier"
8. Do not modify the functionality or behavior of any library.
   • Mockito is the only exception to this because of https://groups.google.com/forum/?hl=en&fromgroups=#!topic/mockito/eLE186uE0uc[this Mockito bug], documented https://issues.jboss.org/browse/JBIDE-14315[here].

Bundles will be published into a p2 update site, which will then be pushed to Nexus. Please note that the version of the Update Site (and the Target Platform used to resolve upstream dependencies like ant, junit, and osgi) will not necessarily match each other, or any of the plugins in Locus.

Building and Releasing

Locus builds with a simple mvn clean verify. This produces a copy of the latest SNAPSHOT of Locus update-site in site/target/repository.

The Locus update-site is released on JBoss Nexus (only releases are allowed so far, SNAPSHOTs are not available published). In order to publish a new release of Locus, just follow these steps:

In this example the version to be released is 1.8.0 and locus repository is origin.

• First, switch from SNAPSHOT to Final:

[source,bash]

# set specific release version
mvn -Dtycho.mode=maven versions:set -DnewVersion=1.8.0
rm -f pom.xml.versionsBackup */pom.xml.versionsBackup */*/pom.xml.versionsBackup */*/*/pom.xml.versionsBackup

# edit ./target-platforms/multiple/locus-multiple.target to set the correct version = 1.8.0
# edit ./pom.xml to set the correct version of TARGET_PLATFORM_VERSION = 1.8.0 and previousVersion = 1.6.0.Final
vim ./target-platforms/multiple/locus-multiple.target ./pom.xml

# commit changes
git add .
git commit -m "prepare for JBoss Tools Locus 1.8.0" .
# git tag and push to origin
git tag 1.8.0
git push origin 1.8.0
git push origin master

---

• Next, rebuild in Jenkins to deploy to Nexus staging repo:

  google-chrome https://dev-platform-jenkins.rhev-ci-vms.eng.rdu2.redhat.com/job/jbosstools-locus.site/build

(or run the build locally with)

mvn deploy

• When done, disable the job and ensure the build is kept forever.

• Now you can login to Nexus.

• First, go here to see what's live:

https://repository.jboss.org/nexus/#nexus-search;gav~org.jboss.tools.locus~jbosstools-locus~1.*~~

• Next, go here to review the staged content, CLOSE the repo, and RELEASE it from staging to production:

https://repository.jboss.org/nexus/#stagingRepositories

NOTE: this can be automated.

• https://github.com/jbosstools/jbosstools-build/blob/master/parent/pom.xml#L541-L553
• https://dev-platform-jenkins.rhev-ci-vms.eng.rdu2.redhat.com/job/jbosstools-build.parent_master/config.xml (search for "deploy")

Once released, the repository becomes accessible a few minutes later here:

• Update Sites:

https://repository.jboss.org/nexus/content/unzip/unzip/org/jboss/tools/locus/jbosstools-locus/1.8.0/jbosstools-locus-1.8.0-updatesite.zip-unzip/ http://repository.jboss.org/nexus/content/unzip/unzip/org/jboss/tools/locus/jbosstools-locus/1.8.0-SNAPSHOT/jbosstools-locus-1.8.0-SNAPSHOT-updatesite.zip-unzip/

• Update Site Zips:

https://repository.jboss.org/nexus/content/groups/public/org/jboss/tools/locus/jbosstools-locus/1.8.0/jbosstools-locus-1.8.0-updatesite.zip https://repository.jboss.org/nexus/content/repositories/snapshots/org/jboss/tools/locus/jbosstools-locus/1.8.0-SNAPSHOT/

Finally, you can prepare the master branch for the next snapshot release:

[source,bash]

# set master to new snapshot version
mvn -Dtycho.mode=maven versions:set -DnewVersion=1.8.0-SNAPSHOT
rm -f pom.xml.versionsBackup */pom.xml.versionsBackup */*/pom.xml.versionsBackup */*/*/pom.xml.versionsBackup

# edit ./target-platforms/multiple/locus-multiple.target to set the correct version = 1.8.0-SNAPSHOT
# edit ./pom.xml to set the correct version of TARGET_PLATFORM_VERSION = 1.8.0-SNAPSHOT and previousVersion = 1.8.0
vim ./target-platforms/multiple/locus-multiple.target ./pom.xml

# commit changes
git add .
git commit -m "prepare for JBoss Tools Locus 1.8.0-SNAPSHOT" .
git push origin master

---

What does 'Locus' mean ?

Locus has many http://www.thefreedictionary.com/locus[meanings], one of them is "a set of points whose location satisfies or is determined by one or more specified conditions, the locus of points equidistant from a given point is a circle". Thus it is not an Orbit, but similar.