GBIF Maven Repository

GBIF uses Maven to build projects, manage the dependencies and also to generate online java docs as part of a maven site. I would like to take the chance and introduce some basic maven features that we use at GBIF.

Repository & Sites

We host a maven repository that we use for keeping external not yet mavenized libraries and to deploy our own developments. All projects can deploy a maven site with java docs, test coverage, dependencies and the regular maven things. The subfolder will be named after the artifactId of the project, so make sure its unique within GBIF! Apache has more information on customizing a maven site per project.

GBIF Parent POM

All GBIF maven projects should make use of our shared parent POM that defines the repository and site URLs, the apache 2 licensing, other popular maven repositories and basic build rules. One of the most important settings in this mother pom is the groupId=org.gbif. We would like all GBIF projects to share the same groupId, which means the artifactId has to be unique for all projects! This allows us to deploy maven sites easily and reduces scattered code, so please don't override it! In case you need to add it manually (not using the archetypes below) to your project, place the following at the top of your POM:

<parent>
   <groupId>org.gbif</groupId>
   <artifactId>motherpom</artifactId>
   <version>1.0-SNAPSHOT</version>
 </parent>

For existing poms please also update the following:

• inherit from this pom (via at the very top)
• remove groupIds, so that we all inherit "org.gbif"
• update our artifactId so that it is unique (we now all share org.gbif)
• add new property googlecode.project so that SVN, issue tracking and project homepage is set out of the box: <googlecode.project>gbif-indexingtoolkit</googlecode.project>
• optionally add/update developers

Settings.xml

In order to deploy to the repository or create new maven sites, authentication is required. The parent POM contains all the public information, but you need to have a local maven settings file that contains at least the user and password. A minimal settings.xml looks like this:

<settings>
 <servers>
   <server>
     <id>gbif</id>
     <username>maven-user</username>
     <password>the maven-user password, please email us if you need it</password>
   </server>
 </servers>
</settings>

On OSX this file should be sitting in your maven home folder, i.e.

/Users/you_username/.m2/settings.xml

Maven Archetypes

We host 2 basic gbif archetypes that you can use to start a new project. A very simple one basically only containing the link to the GBIF parent POM, and a struts2.1 web project one that contains many dependencies and a common GBIF css theme (the theme is currently still under construction) To generate an empty GBIF maven project simply do:

mvn archetype:create -DarchetypeGroupId=org.gbif -DarchetypeArtifactId=gbif-archetype -DarchetypeVersion=1.0-SNAPSHOT -DremoteRepositories=http://tools.gbif.org/maven/repository/ -DgroupId=org.gbif -DartifactId=myProjectName

The complete struts2.1 webapplication archetype with dependencies for struts2, hibernate3, spring2.5, lucene, hadoop and many more has archetypeArtifactId=gbif-war-archetype. The idea here is to maintain a single basic web project and to remove the dependencies you don't need from the pom. This webapp can login/logout already. I would hope to improve it over time to include a standard GBIF authentication and some generic REST / CRUD base actions instead of the REST plugin, but that hasn't been done so far. It is deployed as a snapshot and you can use it like this:

mvn archetype:create -DarchetypeGroupId=org.gbif -DarchetypeArtifactId=gbif-war-archetype -DarchetypeVersion=1.0-SNAPSHOT -DremoteRepositories=http://tools.gbif.org/maven/repository/ -DgroupId=org.gbif -DartifactId=myProjectName

Deploying to the repository

In order to deploy your project remember to have the settings.xml in place. When deploying, any existing version with the same combination of groupId, artifactId and version will be overwritten, so please follow these rules:

• only deploy when its working (ideally no tests fail)
• use x.y-SNAPSHOT in case this is a "transient" release that gets overwritten each time. Proper releases without SNAPSHOT should only be deployed once! Maven caches non snapshot releases, so they would not get updated and, a release should be a release and not touched again.

To deploy your current local copy to the repository simply issue the following command:

mvn deploy

For creating/updating the maven site do:

mvn site-deploy