maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From vsive...@apache.org
Subject 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
Date Tue, 21 Jul 2009 11:54:59 GMT
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>
+     * &lt;javaApiLinks&gt;
+     *   &lt;property&gt;
+     *     &lt;name&gt;api_1.3&lt;/name&gt;
+     *     &lt;value&gt;http://java.sun.com/j2se/1.3/docs/api&lt;/value&gt;
+     *   &lt;/property&gt;
+     *   &lt;property&gt;
+     *     &lt;name&gt;api_1.4&lt;/name&gt;
+     *     &lt;value&gt;http://java.sun.com/j2se/1.4.2/docs/api/&lt;/value&gt;
+     *   &lt;/property&gt;
+     *   &lt;property&gt;
+     *     &lt;name&gt;api_1.5&lt;/name&gt;
+     *     &lt;value&gt;http://java.sun.com/j2se/1.5.0/docs/api/&lt;/value&gt;
+     *   &lt;/property&gt;
+     *   &lt;property&gt;
+     *     &lt;name&gt;api_1.6&lt;/name&gt;
+     *     &lt;value&gt;http://java.sun.com/javase/6/docs/api/&lt;/value&gt;
+     *   &lt;/property&gt;
+     * &lt;/javaApiLinks&gt;
+     * </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 @@
      *   &lt;artifactId&gt;commons-lang&lt;/artifactId&gt;
      * &lt;/dependency&gt;
      * </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 );
     }
 
     /**



Mime
View raw message