So you’re using Maven, like a smart Java developer. Wouldn’t your life be easier if your IDE was linked to your source code and JavaDocs? Maven makes publishing these very easy. Once correctly configured, a simple command (mvn publish) will automatically publish your artifacts to the repository of your choice. Let me show you how.

Why?

You may ask yourself, “Why do I need to publish binaries, source, and JavaDoc? My users already have the source code.” Here are the reasons:

1. Increase the chance of people using your code. By publishing your artifacts to a repository, particularly for secondary modules and dependencies, you save your users the trouble of doing so. At ISG, we have products that depend on in-house libraries. Before we started publishing artifacts to a standard repository, a user would have to download and build three libraries just to build one project. You want people to actually use your product, right? Make it easer and more convenient for them.
2. Increase the chance of the build executing correctly. By building the prerequisites jars for your users and pushing them to a repository, you don’t have to worry about them forgetting to update the sources of the dependencies. Many times, I have had coworkers yell out, “Hey, Product A isn’t compiling” to which an engineer would yell back, “Update your source for Module B.” Now that we have our own Maven repository, a user only has to worry about updating the module he or she is interested in building as all dependencies are published to our repo.
3. Eclipse will automatically import your source and JavaDocs. This is my favorite reason. By hitting F3, while selecting a class, variable, or method, you can view its source. By hitting Shift+F2, you can view the JavaDoc in your web browser. It makes it much more convenient to traverse through code and view documentation.  Now when you build your eclipse project using mvn eclipse:eclipse, it’ll download your source and JavaDoc jars automatically.
4. Increase the chances of your code being used correctly. As mentioned above, the easier it is for people to read your documentation, the less likely they are to ask you stupid questions or dismiss your product as defective.

You greatly increase the probability of adoption if your product is convenient to build, easy to use, and the reference documentation is readily available.

How?

So if you’re still reading than perhaps I’ve persuaded you to give it a try.  The process is simple:

1. Tell maven to assemble a JavaDoc and source jar.
2. Put a link to your repository in your project or one of it’s parents to enable automatic uploading.
3. Put your security info in .m2/setting.xml, so your credentials to your repository don’t get committed into version control

Configuring your POM

Unfortunately source and JavaDoc are not enabled by default, so you have to tell maven-javadoc-plugin and maven-source-plugin to package both into a Jar.

<build>
...
<plugins>
...
 <!-- Package source to JAR to upload to repo-->
 <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <executions>
       <execution>
          <!-- Restrict execution of source compilation to install or deploy. -->
          <!-- The default is package. -->
          <phase>install</phase>
          <goals>
             <goal>jar</goal>
          </goals>
       </execution>
    </executions>
 </plugin>
 <!-- Package JavaDocs to JAR to upload to repo -->
 <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
       <execution>
          <id>attach-javadocs</id>
          <!-- Restrict execution of source compilation to install -->
          <phase>install</phase>
          <goals>
             <goal>jar</goal>
          </goals>
       </execution>
    </executions>
 </plugin>
...
</plugins>
</build>

If you don’t already have a repository

If you’re going to share your code with users, you’ll obviously need a place to put files. For maven, this is simply a web-accessible folder where artifacts are organized using a strict directory naming convention. The bare minimum for a repository is simply a web-accessible folder with a means of remote access. Most first repos are simply a directory on an Apache HTTP server. Most users choose FTP, SSH, or WebDAV to publish their files.

Editing your POM to tell your project where to shove those files

WebDAV is the easiest method to get automatic publishing working. If your repository supoprts WebDAV, Just paste the following into your pom.xml file:

<distributionManagement>
   <repository>
      <id>mycompany.releases</id>
      <name>A friendly description of your release repo</name>
      <url>http://your.webdav.url/releases</url>
   </repository>
   <snapshotRepository>
      <id>mycompany.snapshots</id>
      <name>A friendly description of your snapshots repo</name>
      <url>http://your.webdav.url/snapshots</url>
   </snapshotRepository>
</distributionManagement>

Configuring your ~/.m2/settings.xml file to authenticate with your server.

Technically, your credentials don’t have to be in your settings.xml. You can omit credentials and Maven will prompt you for a username and password for each connection. This is quite tedious and I’d recommend using the settings.xml file. The settings.xml file is designed specifically for workstation-level settings, like security credentials.

Add the servers snippet below to your settings.xml.

<settings 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/xsd/settings-1.0.0.xsd">
...
<servers>
   <server>
      <id>mycompany.releases</id>
      <username>your.username</username>
      <password>your.password</password>
   </server>
   <server>
      <id>mycompany.snapshots</id>
      <username>your.username</username>
      <password>your.password</password>
   </server>
</servers>
...
</settings>

Additional Options:

Publish to SSH or FTP

Apache has an excellent reference at http://maven.apache.org/plugins/maven-deploy-plugin/project-deployment.html explaining how to publish using SSH and FTP. You can even deploy using SSH from Windows.

Publish to Nexus

Nexus is an open source repository manager and a powerful tool for Maven users.  It acts as a proxy and aggregator and downloads dependencies from multiple sites. This is my personal choice for managing dependencies. The main benefit is the proxy that allows me to retrieve jars from dozens of repositories, but only expose one URL to our users. It also makes uploading third party dependencies very easy for those situations where you have a great library you want to use, but no repository to download them from. By default, Nexus uses WebDAV to allow easy uploads and is easy to install. It is simply a war and can be deployed to Tomcat or run from embedded Jetty (see my previous post to learn how to enable it yourself).

Settings for Eclipse Users

If you’re using Netbeans or IntelliJ, congratulations, you’re done. Your IDE natively recognizes Maven projects. Eclipse users have one extra step.

There are presently two popular ways to use a Maven project in eclipse: maven-eclipse, the built-in plugin, and m2eclipse (http://m2eclipse.codehaus.org/).
Maven-eclipse will create eclipse .project and .classpath files for you to import into any eclipse install. M2eclipse requires you to download and eclipse plugin, but adds many powerful features, including the ability to automatically update your classpath as your POM changes as well as launch and debug Maven processes, such as Jetty or the Maven test runner.

If you use maven-eclipse (mvn eclipse:eclipse), make sure the following parameters are set in your pom.xml build section:

<build>
   <plugins>
      <!-- eclipse plugin -->
      <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-eclipse-plugin</artifactId>
         <configuration>
...
            <downloadSources />
            <downloadJavadocs />
         </configuration>
      </plugin>
   </plugins>
</build>

For our POMs, we also add WTP and Spring IDE support:

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-eclipse-plugin</artifactId>
 <configuration>
    <additionalProjectnatures>
       <projectnature>org.springframework.ide.eclipse.core.springnature</projectnature>
    </additionalProjectnatures>
    <additionalBuildcommands>
       <buildcommand>org.springframework.ide.eclipse.core.springbuilder</buildcommand>
    </additionalBuildcommands>
    <wtpversion>2.0</wtpversion>
    <downloadSources />
    <downloadJavadocs />
 </configuration>
</plugin>

If you use m2eclipse (mvn eclipse:m2eclipse), you can enable source and JavaDoc retrieval in the settings tab.

Check Download Artifact Sources and Download Artifact JavaDocs

Conclusion

It’s quick and easy to publish binaries, source, and JavaDocs using Maven.  With minimal effort, you can dramatically increase the probability of the adoption and successful use of your product.  This is just one of the many menial programmers’ tasks that can be automated using Maven, allowing you to focus your attention on pleasing your customer and not worrying about your build.

References:

• Maven Publish Command Reference
• Nexus Homepage
• Maven Eclipse Plugin Reference