Repository Management with Nexus

11.7. Artifact Bundles

11.7.1. Introduction

Artifact bundles are groups of related artifacts which are all related by the same groupId, artifactId, and version (GAV) coordinate. They are used by projects that wish to upload artifacts to the Central Repository.

Bundles must contain the following POM elements:

  • modelVersion
  • groupId
  • artifactId
  • packaging
  • name
  • version
  • description
  • url
  • licenses
  • scm

    • url
    • connection

11.7.2. Creating an Artifact Bundle from a Maven Project

Artifact bundles are created with the Maven Repository Plugin. For more information about the Maven Repository plugin, see http://maven.apache.org/plugins/maven-repository-plugin/

Sample POM Containing all Required Bundle Elements, lists a project’s POM which satisfies all of the constraints that are checked by the Maven Repository plugin. The following POM contains, a description and a URL, SCM information, and a reference to a license. All of this information is required before an artifact bundle can be published to the Maven Central repository.

Sample POM Containing all Required Bundle Elements. 

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.sonatype.sample</groupId>
  <artifactId>sample-project</artifactId>
  <packaging>jar</packaging>
  <version>1.0</version>
  <name>sample-project</name>
  <description>A Sample Project for the Nexus Book</description>
  <url>http://books.sonatype.com</url>
  <licenses>
    <license>
      <name>The Apache Software License, Version 2.0</name>
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
      <distribution>repo</distribution>
    </license>
  </licenses>
  <scm>
    <connection>
      scm:git:git://github.com/sonatype/sample-project.git
    </connection>
    <url>http://github.com/sonatype/sample-project.git</url>
    <developerConnection>
      scm:git:git://github.com/sonatype-sample-project.git
    </developerConnection>
  </scm>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

To create a bundle from a Maven project, run the repository:bundle-create goal. This goal will check the POM to see if it complies with the standards for publishing a bundle to a public repository, it will then bundle all of the artifacts are generated by a particular build. To build a bundle that only contains the standard, unclassified artifact from a project, run mvn repository:bundle-create. To generate a bundle which contains more than one artifact, run mvn javadoc:jar source:jar repository:bundle-create

~/examples/sample-project$ mvn javadoc:jar source:jar repository:bundle-create
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'javadoc'.
[INFO] ------------------------------------------------------------------------
[INFO] Building sample-project
[INFO]    task-segment: [javadoc:jar, source:jar, repository:bundle-create]
[INFO] ------------------------------------------------------------------------
[INFO] [javadoc:jar {execution: default-cli}]
Loading source files for package com.sonatype.sample...
Constructing Javadoc information...
Standard Doclet version 1.6.0_15
Building tree for all the packages and classes...
...
[INFO] Preparing source:jar
[INFO] No goals needed for project - skipping
[INFO] [source:jar {execution: default-cli}]
...

T E S T S

Running com.sonatype.sample.AppTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.03 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] [jar:jar {execution: default-jar}]
[INFO] Building jar: ~/temp/sample-project/target/sample-project-1.0.jar
[INFO] [repository:bundle-create {execution: default-cli}]
[INFO] The following files are marked for inclusion in the repository bundle:

0.) Done
1.) sample-project-1.0.jar
2.) sample-project-1.0-javadoc.jar
3.) sample-project-1.0-sources.jar

Please select the number(s) for any files you wish to exclude, or '0' when \
you're done.  Separate the numbers for multiple files with a comma (',').

Selection:
0
[INFO] Building jar: ~/temp/sample-project/target/sample-project-1.0-bundle.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 11 seconds
[INFO] Finished at: Sat Oct 10 21:24:23 CDT 2009
[INFO] Final Memory: 36M/110M
[INFO] ------------------------------------------------------------------------

Once the bundle has been created, there will be a bundle JAR in the target/ directory. As shown in the following command output, the bundle JAR contains: a POM, the project’s unclassified artifact, the javadoc artifact, and the sources artifact.

~/examples/sample-project$ cd target
~/examples/sample-project/target$ jar tvf sample-project-1.0-bundle.jar
0 Sat Oct 10 21:24:24 CDT 2009 META-INF/
98 Sat Oct 10 21:24:22 CDT 2009 META-INF/MANIFEST.MF
1206 Sat Oct 10 21:23:46 CDT 2009 pom.xml
2544 Sat Oct 10 21:24:22 CDT 2009 sample-project-1.0.jar
20779 Sat Oct 10 21:24:18 CDT 2009 sample-project-1.0-javadoc.jar
891 Sat Oct 10 21:24:18 CDT 2009 sample-project-1.0-sources.jar

11.7.3. Uploading an Artifact Bundle to Nexus

To upload an artifact bundle to Nexus Professional you have to have a repository target for the project configured as described in Section 6.14, “Managing Repository Targets”.

Once that is done, select Staging Upload from the Build Promotion section of the Nexus menu. This will load the Staging Upload tab. Choose Artifact Bundle from the Upload Mode drop-down the Staging Upload panel will switch to the form shown in Figure 11.24, “Uploading an Artifact Bundle”. Click on Select Bundle to Upload… and then select the JAR that was created with the Maven Repository plugin used in the previous sections. Once a bundle is selected, click on Upload Bundle.

figs/web/bundles-staging-upload.png

Figure 11.24. Uploading an Artifact Bundle


After a successful upload, a dialog displays the name of the created staging repository in a URL that links to the content of the repository. To view the staging repository, click on the Staging Repositories link in the Build Promotion section of the Nexus menu, and you should see that the Staging Artifact Upload created and closed a new staging repository as shown in Figure 11.25, “Staging Repository Created from Artifact Bundle Upload”. This repository contains all of the artifacts contained in the uploaded bundle. It allows you to promote or drop the artifacts contained in a bundle as a single unit.

figs/web/bundles-staged-bundle.png

Figure 11.25. Staging Repository Created from Artifact Bundle Upload


Once the staging repository is closed you can promote it to a Build Promotion Profile or release it to the target repository of the staging profile as documented in Section 11.4, “Managing Staging Repositories in Nexus”.