Many people are aware of maven source and javadoc artifacts but don’t know why they would want to create them. I was definitely in this camp – I can see why people want this information but it seemed like a relatively inefficient way to get it since it requires manual navigation of the maven repository.
Then I got hit by a clue stick.
These artifacts are used by IDEs, not people. If you’re using maven dependencies the IDE is smart enough to know how to find these artifacts. The source artifact is used when you’re single-stepping through code in the debugger – you no longer have to explicitly bind source code to libraries in the IDE. The javadoc artifact is used for auto-completion and context-sensitive help in the editor.
Neither of these is required – I was happy using ‘vi’ for many years – but it definitely improves your productivity when you mostly know what you need but aren’t quite sure of the details.
Source Artifacts
The source artifacts are the easiest to create. Add a plugin that will be run automatically as part of a standard build and you’re done. Builds take slightly longer but it’s probably not enough to worry about since you’re just creating an archive of a few directories.
<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/xsd/maven-4.0.0.xsd">
<build>
<plugins>
<!-- create source jar -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>2.1.1</version>
<executions>
<execution>
<id>attach-sources</id>
<phase>verify</phase>
<goals>
<!-- produce source artifact for project main sources -->
<goal>jar-no-fork</goal>
<!-- produce test source artifact for project test sources -->
<goal>test-jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>Javadoc Artifacts
Javadoc artifacts are a little more complex since you’ll probably want to create a human-friendly site at the same time. The biggest issue there, in my experience, is that external classes were opaque since it took so much effort to create the necessary links. The maven plugin now takes care of that for us!
This artifact takes a significant amount of time to build so you probably don’t want to do it every time. There are two approaches – either specify the maven target explicitly or tie it to a custom profile, e.g., ‘javadoc’. The configuration below uses a custom profile.
<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/xsd/maven-4.0.0.xsd">
<profiles>
<!-- create javadoc -->
<profile>
<id>javadoc</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<configuration>
<detectLinks />
<includeDependencySources>true</includeDependencySources>
<dependencySourceIncludes>
<dependencySourceInclude>com.invariantproperties.project.student:*</dependencySourceInclude>
</dependencySourceIncludes>
<!-- heavily used dependencies -->
<links>
<link>http://docs.oracle.com/javase/7/docs/api/</link>
<link>http://docs.oracle.com/javaee/6/api</link>
<link>http://docs.spring.io/spring/docs/current/javadoc-api/</link>
<link>http://docs.spring.io/spring-data/commons/docs/1.6.2.RELEASE/api/</link>
<link>http://docs.spring.io/spring-data/jpa/docs/1.4.3.RELEASE/api/</link>
<link>http://docs.spring.io/spring-data/data-jpa/docs/1.4.3.RELEASE/api/</link>
<link>https://jersey.java.net/apidocs/1.17/jersey/</link>
<link>http://hamcrest.org/JavaHamcrest/javadoc/1.3/</link>
<link>http://eclipse.org/aspectj/doc/released/runtime-api/</link>
<link>http://eclipse.org/aspectj/doc/released/weaver-api</link>
<link>http://tapestry.apache.org/5.3.7/apidocs/</link>
</links>
</configuration>
<executions>
<execution>
<id>aggregate</id>
<!-- <phase>site</phase> -->
<phase>package</phase>
<goals>
<goal>aggregate</goal>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<configuration>
<!-- Default configuration for all reports -->
</configuration>
<reportSets>
<reportSet>
<id>non-aggregate</id>
<configuration>
<!-- Specific configuration for the non aggregate report -->
</configuration>
<reports>
<report>javadoc</report>
</reports>
</reportSet>
<reportSet>
<id>aggregate</id>
<configuration>
<!-- Specific configuration for the aggregate report -->
</configuration>
<reports>
<report>aggregate</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
</profile>
</profiles>
</project>package-info.java
Finally each package should have a package-info.java file. This replaces the old package-info.html file but is an improvement since it allows the use of class annotations. (It will not be compiled since it’s an invalid class name.)
I’ve found it extremely helpful to include links to resources that help me understand why the classes look the way they do. For instance the metadata package in my ‘student’ project contains links to my blog posts, other blog posts that I’ve found useful, and even the appropriate Oracle tutorial. At a company these could be links to wiki pages.
/** * Classes that support JPA Criteria Queries for persistent entities. * * @see <a href="http://invariantproperties.com/2013/12/19/project-student-persistence-with-spring-data/">Project Student: Persistence with Spring Data</a> * @see <a href="http://invariantproperties.com/2013/12/29/project-student-jpa-criteria-queries/">Project Student: JPA Criteria Queries</a> * @see <a href="http://www.petrikainulainen.net/programming/spring-framework/spring-data-jpa-tutorial-part-four-jpa-criteria-queries/">Spring Data JPA Tutorial Part Four: JPA Criteria Queries</a> [www.petrikainulainen.net] * @see <a href="http://docs.oracle.com/javaee/6/tutorial/doc/gjitv.html">JEE Tutorial</a> * * @author Bear Giles <bgiles@coyotesong.com> */ package com.invariantproperties.project.student.metamodel;
Source Code
- The source code is at https://github.com/beargiles/project-student [github] and http://beargiles.github.io/project-student/ [github pages].
