Creating Maven Source and Javadoc Artifacts

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

 

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

JPA Mini Book

Learn how to leverage the power of JPA in order to create robust and flexible Java applications. With this Mini Book, you will get introduced to JPA and smoothly transition to more advanced concepts.

JVM Troubleshooting Guide

The Java virtual machine is really the foundation of any Java EE platform. Learn how to master it with this advanced guide!

Given email address is already subscribed, thank you!
Oops. Something went wrong. Please try again later.
Please provide a valid email address.
Thank you, your sign-up request was successful! Please check your e-mail inbox.
Please complete the CAPTCHA.
Please fill in the required fields.

Leave a Reply


3 + = four



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy | Contact
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.
Do you want to know how to develop your skillset and become a ...
Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

Get ready to Rock!
You can download the complementary eBooks using the links below:
Close