How do I generate and deploy a javadoc jar file for my project?
Author: Deron Eriksson
Description: This maven tutorial describes how to generate a javadoc jar file for a project using the maven-javadoc-plugin plugin.
Tutorial created using: Windows Vista || JDK 1.6.0_04 || Eclipse Web Tools Platform 2.0.1 (Eclipse 3.3.1)


Page:    1 2 >

The maven-javadoc-plugin can be used to generate a javadoc jarW file for a project that can then be deployed to a remote mavenSW repository so that other developers can download the javadocs for the project. Setup to do this is very easy. We can simple add an entry in pom.xml for the "maven-javadoc-plugin" and specify the "jar" goal, which is the goal responsible for building the javadoc jar file. An example of this is shown here:

pom.xml maven-javadoc-plugin entry

...
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-javadoc-plugin</artifactId>
			<executions>
				<execution>
					<id>attach-javadocs</id>
					<goals>
						<goal>jar</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
...

Here is the full pom.xml file for a project called "aproject" that utilizes the maven-javadoc-plugin. Notice that it will also generate a source jar file via the maven-source-plugin plugin.

pom.xml

<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.maventest</groupId>
	<artifactId>aproject</artifactId>
	<packaging>jar</packaging>
	<version>1.2</version>
	<name>aproject</name>
	<url>http://maven.apache.org</url>
	<dependencies>
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>3.8.1</version>
			<scope>test</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-source-plugin</artifactId>
				<executions>
					<execution>
						<id>attach-sources</id>
						<goals>
							<goal>jar</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-javadoc-plugin</artifactId>
				<executions>
					<execution>
						<id>attach-javadocs</id>
						<goals>
							<goal>jar</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
		<extensions>
			<!-- begin - needed for deploying to repository using webdav -->
			<extension>
				<groupId>org.apache.maven.wagon</groupId>
				<artifactId>wagon-webdav</artifactId>
				<version>1.0-beta-2</version>
			</extension>
			<!-- end - needed for deploying to repository using webdav -->
		</extensions>
	</build>
	<distributionManagement>
		<repository>
			<id>archiva.internal</id>
			<name>Internal Release Repository</name>
			<url>dav:http://192.168.1.7:8081/archiva/repository/internal</url>
		</repository>
		<snapshotRepository>
			<id>archiva.snapshots</id>
			<name>Internal Snapshot Repository</name>
			<url>dav:http://192.168.1.7:8081/archiva/repository/snapshots</url>
		</snapshotRepository>
	</distributionManagement>
</project>

I'll perform a "mvn clean package" on "aproject" to generate the normal jar artifact, the source jar, and the javadoc jar.

Executing 'mvn clean package' on 'aproject'

The console output is shown here:

Console output for 'mvn clean package' on 'aproject' project

[INFO] Scanning for projects...
WAGON_VERSION: 1.0-beta-2
[INFO] ------------------------------------------------------------------------
[INFO] Building aproject
[INFO]    task-segment: [clean, package]
[INFO] ------------------------------------------------------------------------
[INFO] [clean:clean]
[INFO] Deleting directory C:\dev\workspace\aproject\target
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 1 source file to C:\dev\workspace\aproject\target\classes
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:testCompile]
[INFO] Compiling 1 source file to C:\dev\workspace\aproject\target\test-classes
[INFO] [surefire:test]
[INFO] Surefire report directory: C:\dev\workspace\aproject\target\surefire-reports

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.maventest.AppTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.039 sec

Results :

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

[INFO] [jar:jar]
[INFO] Building jar: C:\dev\workspace\aproject\target\aproject-1.2.jar
[INFO] Preparing source:jar
[WARNING] Removing: jar from forked lifecycle, to prevent recursive invocation.
[INFO] No goals needed for project - skipping
[INFO] [source:jar {execution: attach-sources}]
[INFO] Building jar: C:\dev\workspace\aproject\target\aproject-1.2-sources.jar
[INFO] Preparing javadoc:jar
[INFO] ------------------------------------------------------------------------
[INFO] Building aproject
[INFO] ------------------------------------------------------------------------
[WARNING] Removing: jar from forked lifecycle, to prevent recursive invocation.
[WARNING] Removing: jar from forked lifecycle, to prevent recursive invocation.
[INFO] No goals needed for project - skipping
[INFO] [javadoc:jar {execution: attach-javadocs}]
Loading source files for package com.maventest...
Constructing Javadoc information...
Standard Doclet version 1.6.0_04
Building tree for all the packages and classes...
Generating C:/dev/workspace/aproject/target/apidocs\com/maventest/\App.html...
Generating C:/dev/workspace/aproject/target/apidocs\com/maventest/\package-frame.html...
Generating C:/dev/workspace/aproject/target/apidocs\com/maventest/\package-summary.html...
Generating C:/dev/workspace/aproject/target/apidocs\com/maventest/\package-tree.html...
Generating C:/dev/workspace/aproject/target/apidocs\constant-values.html...
Generating C:/dev/workspace/aproject/target/apidocs\com/maventest/\class-use\App.html...
Generating C:/dev/workspace/aproject/target/apidocs\com/maventest/\package-use.html...
Building index for all the packages and classes...
Generating C:/dev/workspace/aproject/target/apidocs\overview-tree.html...
Generating C:/dev/workspace/aproject/target/apidocs\index-all.html...
Generating C:/dev/workspace/aproject/target/apidocs\deprecated-list.html...
Building index for all classes...
Generating C:/dev/workspace/aproject/target/apidocs\allclasses-frame.html...
Generating C:/dev/workspace/aproject/target/apidocs\allclasses-noframe.html...
Generating C:/dev/workspace/aproject/target/apidocs\index.html...
Generating C:/dev/workspace/aproject/target/apidocs\help-doc.html...
Generating C:/dev/workspace/aproject/target/apidocs\stylesheet.css...
[INFO] Building jar: C:\dev\workspace\aproject\target\aproject-1.2-javadoc.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 8 seconds
[INFO] Finished at: Tue Feb 19 21:21:47 PST 2008
[INFO] Final Memory: 15M/27M
[INFO] ------------------------------------------------------------------------

After the command has finished, we can see that the target directory contains the normal jar artifact (aproject-1.2.jar), the source jar (aproject-1.2-sources.jar), and the javadoc jar (aproject-1.2-javadoc.jar).

javadoc jar has been generated

(Continued on page 2)

Page:    1 2 >