You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by vs...@apache.org on 2009/07/21 13:54:59 UTC
svn commit: r796266 - in /maven/plugins/trunk/maven-javadoc-plugin/src:
main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java
site/apt/examples/links-configuration.apt
test/java/org/apache/maven/plugin/javadoc/JavadocReportTest.java
Author: vsiveton
Date: Tue Jul 21 11:54:59 2009
New Revision: 796266
URL: http://svn.apache.org/viewvc?rev=796266&view=rev
Log:
MJAVADOC-240: Add default Javadoc link depending the values of maven-compiler-plugin configuration
o updated code/doc/test
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt
maven/plugins/trunk/maven-javadoc-plugin/src/test/java/org/apache/maven/plugin/javadoc/JavadocReportTest.java
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java?rev=796266&r1=796265&r2=796266&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java Tue Jul 21 11:54:59 2009
@@ -108,6 +108,34 @@
public abstract class AbstractJavadocMojo
extends AbstractMojo
{
+ /**
+ * The default Javadoc API urls according the
+ * <a href="http://java.sun.com/reference/api/index.html">Sun API Specifications</a>:
+ * <pre>
+ * <javaApiLinks>
+ * <property>
+ * <name>api_1.3</name>
+ * <value>http://java.sun.com/j2se/1.3/docs/api</value>
+ * </property>
+ * <property>
+ * <name>api_1.4</name>
+ * <value>http://java.sun.com/j2se/1.4.2/docs/api/</value>
+ * </property>
+ * <property>
+ * <name>api_1.5</name>
+ * <value>http://java.sun.com/j2se/1.5.0/docs/api/</value>
+ * </property>
+ * <property>
+ * <name>api_1.6</name>
+ * <value>http://java.sun.com/javase/6/docs/api/</value>
+ * </property>
+ * </javaApiLinks>
+ * </pre>
+ *
+ * @since 2.6
+ */
+ public static final Properties DEFAULT_JAVA_API_LINKS = new Properties();
+
/** The Javadoc script file name when <code>debug</code> parameter is on, i.e. javadoc.bat or javadoc.sh */
protected static final String DEBUG_JAVADOC_SCRIPT_NAME =
"javadoc." + ( SystemUtils.IS_OS_WINDOWS ? "bat" : "sh" );
@@ -414,8 +442,8 @@
protected boolean useStandardDocletOptions;
/**
- * Detect the Javadoc links for all dependencies defined in the project. The detection is based on the Maven
- * conventions, i.e.: <code>${project.url}/apidocs</code>.
+ * Detect the Javadoc links for all dependencies defined in the project. The detection is based on the default
+ * Maven conventions, i.e.: <code>${project.url}/apidocs</code>.
* <br/>
* For instance, if the project has a dependency to
* <a href="http://commons.apache.org/lang/">Apache Commons Lang</a> i.e.:
@@ -425,7 +453,7 @@
* <artifactId>commons-lang</artifactId>
* </dependency>
* </pre>
- * The added Javadoc link will be <code>http://commons.apache.org/lang/apidocs</code>.
+ * The added Javadoc <code>-link</code> parameter will be <code>http://commons.apache.org/lang/apidocs</code>.
*
* @parameter expression="${detectLinks}" default-value="false"
* @see #links
@@ -440,10 +468,11 @@
* between modules based on the defined project's urls. For instance, if a parent project has two projects
* <code>module1</code> and <code>module2</code>, the <code>-linkoffline</code> will be:
* <br/>
- * The offlineLinks for <b>module1</b> will be
+ * The added Javadoc <code>-linkoffline</code> parameter for <b>module1</b> will be
* <code>/absolute/path/to/</code><b>module2</b><code>/target/site/apidocs</code>
* <br/>
- * The offlineLinks for <b>module2</b> will be <code>/absolute/path/to/</code><b>module1</b><code>/target/site/apidocs</code>
+ * The added Javadoc <code>-linkoffline</code> parameter for <b>module2</b> will be
+ * <code>/absolute/path/to/</code><b>module1</b><code>/target/site/apidocs</code>
*
* @parameter expression="${detectOfflineLinks}" default-value="true"
* @see #offlineLinks
@@ -451,6 +480,40 @@
*/
private boolean detectOfflineLinks;
+ /**
+ * Detect the Java API link for the current build, i.e. <code>http://java.sun.com/j2se/1.4.2/docs/api</code>
+ * for Java source 1.4.
+ * <br/>
+ * By default, the goal detects the Javadoc API link depending the value of the <code>source</code>
+ * parameter in the <code>org.apache.maven.plugins:maven-compiler-plugin</code>
+ * (defined in <code>${project.build.plugins}</code> or in <code>${project.build.pluginManagement}</code>),
+ * or try to compute it from the {@link #javadocExecutable} version.
+ * <br/>
+ * See <a href="./apidocs/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.html#DEFAULT_JAVA_API_LINKS">Javadoc</a> for the default values.
+ * <br/>
+ *
+ * @parameter expression="${detectJavaApiLink}" default-value="true"
+ * @see #links
+ * @see #javaApiLinks
+ * @see #DEFAULT_JAVA_API_LINKS
+ * @since 2.6
+ */
+ private boolean detectJavaApiLink;
+
+ /**
+ * Use this parameter <b>only</b> if the <a href="http://java.sun.com/reference/api/index.html">Sun Javadoc API</a>
+ * urls have been changed or to use custom urls for Javadoc API url.
+ * <br/>
+ * See <a href="./apidocs/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.html#DEFAULT_JAVA_API_LINKS">Javadoc</a>
+ * for the default values.
+ * <br/>
+ *
+ * @parameter expression="${javaApiLinks}"
+ * @see #DEFAULT_JAVA_API_LINKS
+ * @since 2.6
+ */
+ private Properties javaApiLinks;
+
// ----------------------------------------------------------------------
// Javadoc Options - all alphabetical
// ----------------------------------------------------------------------
@@ -968,12 +1031,16 @@
* </pre>
* will be used because <code>http://java.sun.com/j2se/1.4.2/docs/api/package-list</code> exists.
* <br/>
- * <b>Note</b>: if {@link #detectLinks} is defined, the links between the project dependencies are
+ * <b>Note 1</b>: if {@link #detectLinks} is defined, the links between the project dependencies are
* automatically added.
+ * <b>Note 2</b>: if {@link #detectJavaApiLink} is defined, a Java API link, based on the Java verion of the
+ * project's sources, will be added automatically.
* <br/>
* See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#link">link</a>.
*
* @parameter expression="${links}"
+ * @see #detectLinks
+ * @see #detectJavaApiLink
*/
protected ArrayList links;
@@ -1440,6 +1507,18 @@
private String windowtitle;
// ----------------------------------------------------------------------
+ // static
+ // ----------------------------------------------------------------------
+
+ static
+ {
+ DEFAULT_JAVA_API_LINKS.put( "api_1.3", "http://java.sun.com/j2se/1.3/docs/api" );
+ DEFAULT_JAVA_API_LINKS.put( "api_1.4", "http://java.sun.com/j2se/1.4.2/docs/api/" );
+ DEFAULT_JAVA_API_LINKS.put( "api_1.5", "http://java.sun.com/j2se/1.5.0/docs/api/" );
+ DEFAULT_JAVA_API_LINKS.put( "api_1.6", "http://java.sun.com/javase/6/docs/api/" );
+ }
+
+ // ----------------------------------------------------------------------
// protected methods
// ----------------------------------------------------------------------
@@ -3125,6 +3204,12 @@
links = new ArrayList();
}
+ String javaApiLink = getDefaultJavadocApiLink();
+ if ( javaApiLink != null )
+ {
+ links.add( javaApiLink );
+ }
+
links.addAll( getDependenciesLinks() );
for ( int i = 0; i < links.size(); i++ )
@@ -3598,6 +3683,12 @@
{
throw new MavenReportException( "Option <stylesheet/> supports only \"maven\" or \"java\" value." );
}
+
+ // default java api links
+ if ( javaApiLinks == null || javaApiLinks.size() == 0 )
+ {
+ javaApiLinks = DEFAULT_JAVA_API_LINKS;
+ }
}
/**
@@ -4214,8 +4305,8 @@
}
classPath.clear();
- Plugin javadocPlugin =
- (Plugin) project.getBuild().getPluginsAsMap().get( "org.apache.maven.plugins:maven-javadoc-plugin" );
+ final String pluginId = "org.apache.maven.plugins:maven-javadoc-plugin";
+ Plugin javadocPlugin = getPlugin( project, pluginId );
if ( javadocPlugin != null && javadocPlugin.getDependencies() != null )
{
for ( Iterator it = javadocPlugin.getDependencies().iterator(); it.hasNext(); )
@@ -4480,6 +4571,79 @@
}
/**
+ * @return if {@link #detectJavaApiLink}, the Java API link based on the {@link #javaApiLinks} properties and the value of the
+ * <code>source</code> parameter in the <code>org.apache.maven.plugins:maven-compiler-plugin</code>
+ * defined in <code>${project.build.plugins}</code> or in <code>${project.build.pluginManagement}</code>,
+ * or the {@link #fJavadocVersion}, or <code>null</code> if not defined.
+ * @since 2.6
+ * @see #detectJavaApiLink
+ * @see #javaApiLinks
+ * @see #DEFAULT_JAVA_API_LINKS
+ * @see <a href="http://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#source">source parameter</a>
+ */
+ private String getDefaultJavadocApiLink()
+ {
+ if ( !detectJavaApiLink )
+ {
+ return null;
+ }
+
+ final String pluginId = "org.apache.maven.plugins:maven-compiler-plugin";
+ float source = fJavadocVersion;
+ String sourceConfigured = getPluginParameter( project, pluginId, "source" );
+ if ( sourceConfigured != null )
+ {
+ try
+ {
+ source = Float.parseFloat( sourceConfigured );
+ }
+ catch ( NumberFormatException e )
+ {
+ getLog().debug(
+ "NumberFormatException for the source parameter in the maven-compiler-plugin. "
+ + "Ignored it", e );
+ }
+ }
+ else
+ {
+ getLog().debug(
+ "No maven-compiler-plugin defined in ${build.plugins} or in "
+ + "${project.build.pluginManagement} for the " + project.getId()
+ + ". Added Javadoc API link according the javadoc executable version i.e.: "
+ + fJavadocVersion );
+ }
+
+ String javaApiLink = null;
+ if ( source >= 1.3f && source < 1.4f && javaApiLinks.getProperty( "api_1.3" ) != null )
+ {
+ javaApiLink = javaApiLinks.getProperty( "api_1.3" ).toString();
+ }
+ else if ( source >= 1.4f && source < 1.5f && javaApiLinks.getProperty( "api_1.4" ) != null )
+ {
+ javaApiLink = javaApiLinks.getProperty( "api_1.4" ).toString();
+ }
+ else if ( source >= 1.5f && source < 1.6f && javaApiLinks.getProperty( "api_1.5" ) != null )
+ {
+ javaApiLink = javaApiLinks.getProperty( "api_1.5" ).toString();
+ }
+ else if ( source >= 1.6f && javaApiLinks.getProperty( "api_1.6" ) != null )
+ {
+ javaApiLink = javaApiLinks.getProperty( "api_1.6" ).toString();
+ }
+
+ if ( StringUtils.isNotEmpty( javaApiLink ) )
+ {
+ getLog().debug( "Found Java API link: " + javaApiLink );
+ }
+ else
+ {
+ getLog().debug( "No Java API link found." );
+ }
+
+ return javaApiLink;
+ }
+
+ /**
* @param link not null
* @return <code>true</code> if the link has a <code>/package-list</code>, <code>false</code> otherwise.
* @since 2.6
@@ -4551,16 +4715,11 @@
String url = cleanUrl( p.getUrl() );
String destDir = "apidocs"; // see JavadocReport#destDir
- Plugin javadocPlugin =
- (Plugin) p.getBuild().getPluginsAsMap().get( "org.apache.maven.plugins:maven-javadoc-plugin" );
- if ( javadocPlugin != null )
- {
- Xpp3Dom xpp3Dom = (Xpp3Dom) javadocPlugin.getConfiguration();
- if ( xpp3Dom != null && xpp3Dom.getChild( "destDir" ) != null
- && StringUtils.isNotEmpty( xpp3Dom.getChild( "destDir" ).getValue() ) )
- {
- destDir = xpp3Dom.getChild( "destDir" ).getValue();
- }
+ final String pluginId = "org.apache.maven.plugins:maven-javadoc-plugin";
+ String destDirConfigured = getPluginParameter( p, pluginId, "destDir" );
+ if ( destDirConfigured != null )
+ {
+ destDir = destDirConfigured;
}
return url + "/" + destDir;
@@ -4586,4 +4745,55 @@
return url;
}
+
+ /**
+ * @param p not null
+ * @param pluginId not null key of the plugin defined in {@link org.apache.maven.model.Build#getPluginsAsMap()} or in
+ * {@link org.apache.maven.model.PluginManagement#getPluginsAsMap()}
+ * @return the Maven plugin defined in <code>${project.build.plugins}</code> or in <code>${project.build.pluginManagement}</code>,
+ * or <code>null</code> if not defined.
+ * @since 2.6
+ */
+ private static Plugin getPlugin( MavenProject p, String pluginId )
+ {
+ Plugin plugin = null;
+ if ( p.getBuild() != null && p.getBuild().getPluginsAsMap() != null )
+ {
+ plugin = (Plugin) p.getBuild().getPluginsAsMap().get( pluginId );
+ if ( plugin == null )
+ {
+ if ( p.getBuild().getPluginManagement() != null
+ && p.getBuild().getPluginManagement().getPluginsAsMap() != null )
+ {
+ plugin = (Plugin) p.getBuild().getPluginManagement().getPluginsAsMap().get( pluginId );
+ }
+ }
+ }
+
+ return plugin;
+ }
+
+ /**
+ * @param p not null
+ * @param pluginId not null
+ * @param param not null
+ * @return the simple parameter as String defined in the plugin configuration by <code>param</code> key
+ * or <code>null</code> if not found.
+ * @since 2.6
+ */
+ private static String getPluginParameter( MavenProject p, String pluginId, String param )
+ {
+ Plugin plugin = getPlugin( p, pluginId );
+ if ( plugin != null )
+ {
+ Xpp3Dom xpp3Dom = (Xpp3Dom) plugin.getConfiguration();
+ if ( xpp3Dom != null && xpp3Dom.getChild( param ) != null
+ && StringUtils.isNotEmpty( xpp3Dom.getChild( param ).getValue() ) )
+ {
+ return xpp3Dom.getChild( param ).getValue();
+ }
+ }
+
+ return null;
+ }
}
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt?rev=796266&r1=796265&r2=796266&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt Tue Jul 21 11:54:59 2009
@@ -3,7 +3,7 @@
------
Vincent Siveton
------
- 2009-07-20
+ 2009-07-21
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -26,7 +26,7 @@
~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html
-Configuring links Parameters
+Configuring <<<links>>> Parameter
You could add cross reference links to external projects. For instance:
@@ -53,11 +53,11 @@
+-----+
<<Important Note>>: according the {{{http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#package-list}Javadoc specifications}},
- all given links should have a fetchable <<</package-list>>> file.
+ all given links <<should>> have a fetchable <<</package-list>>> file.
- Since 2.6, you could try to autodetect all Javadoc links for your dependencies. You need to use the
- {{{./javadoc-mojo.html#detectLinks}detectLinks}} parameter. All detected links are based on the Maven conventions.
- For instance, if your project has a dependency to {{{http://commons.apache.org/lang/}Apache Commons Lang}} i.e.:
+ Since 2.6, you could try to detect all Javadoc links for the project's dependencies. You need to use the
+ {{{../javadoc-mojo.html#detectLinks}detectLinks}} parameter. All detected links are based on the default Maven
+ conventions. For instance, if your project has a dependency to {{{http://commons.apache.org/lang/}Apache Commons Lang}} i.e.:
+-----+
<project>
@@ -75,9 +75,28 @@
The added Javadoc link will be {{http://commons.apache.org/lang/apidocs}}.
- Refer to {{{./javadoc-mojo.html#links}links}} parameter for more information.
+ Since 2.6, a {{{http://java.sun.com/reference/api/index.html}Javadoc API}} link, depending the JDK version used by your
+ project, will be added. The version of the Javadoc API is detected from the value of the
+ <<<{{{http://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#source}source}}>>>
+ parameter in the <<<{{{http://maven.apache.org/plugins/maven-compiler-plugin}org.apache.maven.plugins:maven-compiler-plugin}}>>>
+ (defined in $\{project.build.plugins\} or in $\{project.build.pluginManagement\}), or computed via the Javadoc Tool
+ executable. If you want to skip this link, you need to configure
+ {{{../javadoc-mojo.html#detectJavaApiLink}detectJavaApiLink}} to <<<false>>>.
+
+ <<Note>>: if you are using an unsupported JDK like 7.0, you could add its Javadoc API url using the
+ {{{../javadoc-mojo.html#javaApiLinks}javaApiLinks}} parameter, i.e.:
+
+ <javaApiLinks>
+ ...
+ <property>
+ <name>api_1.7</name>
+ <value>http://download.java.net/jdk7/docs/api/</value>
+ </property>
+ </javaApiLinks>
-Configuring offlineLinks Parameters
+ Refer to {{{../javadoc-mojo.html#links}links}} parameter for more information.
+
+Configuring <<<offlineLinks>>> Parameter
If your project has modules, you could add cross reference links to your modules when your goals are not aggregator goals.
For instance, if your project has two modules i.e.:
@@ -96,9 +115,9 @@
The offlineLinks for <<module1>> will be <<</absolute/path/to/>>><<module2>><<</target/site/apidocs>>> and
the offlineLinks for <<module2>> will be <<</absolute/path/to/>>><<module1>><<</target/site/apidocs>>>.
- <<Important Note>>: all offlinelinks are based on the \${project.url}.
+ <<Important Note>>: all offlinelinks are based on the $\{project.url\}.
- Since 2.6, you could not allowing the cross reference offlinelinks with
- {{{./javadoc-mojo.html#detectOfflineLinks}detectOfflineLinks}} parameter.
+ Since 2.6, you could not disable the cross reference for <<<offlineLinks>>> using the
+ {{{../javadoc-mojo.html#detectOfflineLinks}detectOfflineLinks}} parameter.
- Refer to {{{./javadoc-mojo.html#offlineLinks}offlineLinks}} parameter for more information.
+ Refer to {{{../javadoc-mojo.html#offlineLinks}offlineLinks}} parameter for more information.
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/test/java/org/apache/maven/plugin/javadoc/JavadocReportTest.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/test/java/org/apache/maven/plugin/javadoc/JavadocReportTest.java?rev=796266&r1=796265&r2=796266&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/test/java/org/apache/maven/plugin/javadoc/JavadocReportTest.java (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/test/java/org/apache/maven/plugin/javadoc/JavadocReportTest.java Tue Jul 21 11:54:59 2009
@@ -23,6 +23,7 @@
import java.io.File;
import java.io.FileReader;
import java.io.IOException;
+import java.io.Reader;
import java.util.Iterator;
import java.util.List;
@@ -30,9 +31,13 @@
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.testing.AbstractMojoTestCase;
import org.codehaus.plexus.util.FileUtils;
+import org.codehaus.plexus.util.IOUtil;
+import org.codehaus.plexus.util.ReaderFactory;
import org.codehaus.plexus.util.StringUtils;
/**
+ * Test {@link org.apache.maven.plugin.javadoc.JavadocReport} class.
+ *
* @author <a href="mailto:oching@apache.org">Maria Odea Ching</a>
* @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
*/
@@ -402,6 +407,26 @@
generatedFile = new File( getBasedir(),
"target/test/unit/custom-configuration/target/site/apidocs/custom/configuration/exclude2/Exclude2App.html" );
assertTrue( !FileUtils.fileExists( generatedFile.getAbsolutePath() ) );
+
+ File options =
+ new File( getBasedir(), "target/test/unit/custom-configuration/target/site/apidocs/options" );
+ assertTrue( options.isFile() );
+ String contentOptions = null;
+ Reader reader = null;
+ try
+ {
+ reader = ReaderFactory.newPlatformReader( options );
+ contentOptions = IOUtil.toString( reader );
+ }
+ finally
+ {
+ IOUtil.close( reader );
+ }
+
+ assertTrue( contentOptions != null );
+ assertTrue( contentOptions.indexOf( "-link" ) != -1 );
+ assertTrue( contentOptions.indexOf( "http://java.sun.com/j2se/" ) != -1
+ || contentOptions.indexOf( "http://java.sun.com/javase/" ) != -1 );
}
/**