Author: vsiveton
Date: Sat May 12 05:30:17 2007
New Revision: 537398
URL: http://svn.apache.org/viewvc?view=rev&rev=537398
Log:
MJAVADOC-98: Add support for Javadoc version different from JAVA_HOME
Submitted by: Wayne Fay
Reviewed by: Vincent Siveton
o applied with some changes
o added isJavadocVersionAtLeast()
o provided mechanism to auto-detect javadoc version
o added documentation
Added:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt
(with props)
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/index.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml
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?view=diff&rev=537398&r1=537397&r2=537398
==============================================================================
---
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
Sat May 12 05:30:17 2007
@@ -67,7 +67,7 @@
import org.codehaus.plexus.util.cli.DefaultConsumer;
/**
- * Base class with majority of Javadoc functionality.
+ * Base class with majority of Javadoc functionalities.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Brett Porter</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Vincent Siveton</a>
@@ -215,6 +215,22 @@
*/
private boolean debug;
+ /**
+ * Sets the path of the Javadoc Tool executable to use.
+ *
+ * @parameter expression="${javadocExecutable}"
+ */
+ private String javadocExecutable;
+
+ /**
+ * Version of the Javadoc Tool executable to use, ex. "1.3", "1.5".
+ *
+ * @parameter expression="${javadocVersion}"
+ */
+ private String javadocVersion;
+
+ private float fJavadocVersion = 0.0f;
+
// ----------------------------------------------------------------------
// Javadoc Options
// ----------------------------------------------------------------------
@@ -952,6 +968,54 @@
return;
}
+ //
----------------------------------------------------------------------
+ // Find the javadoc executable and version
+ //
----------------------------------------------------------------------
+
+ String jExecutable;
+ try
+ {
+ jExecutable = getJavadocExecutable();
+ }
+ catch ( IOException e )
+ {
+ throw new MavenReportException( "Unable to find javadoc command: "
+ e.getMessage(), e );
+ }
+
+ float jVersion;
+ try
+ {
+ jVersion = getJavadocVersion( new File( jExecutable ) );
+ }
+ catch ( IOException e )
+ {
+ throw new MavenReportException( "Unable to find javadoc version: "
+ e.getMessage(), e );
+ }
+ catch ( CommandLineException e )
+ {
+ throw new MavenReportException( "Unable to find javadoc version: "
+ e.getMessage(), e );
+ }
+ if ( StringUtils.isNotEmpty( javadocVersion ) )
+ {
+ try
+ {
+ fJavadocVersion = Float.parseFloat( javadocVersion );
+ }
+ catch ( NumberFormatException e )
+ {
+ throw new MavenReportException( "Unable to parse javadoc
version: " + e.getMessage(), e );
+ }
+
+ if ( fJavadocVersion != jVersion )
+ {
+ getLog().warn( "Are you sure about the <javadocVersion/>
parameter? It seems to be " + jVersion );
+ }
+ }
+ else
+ {
+ fJavadocVersion = jVersion;
+ }
+
File javadocOutputDirectory = new File( getOutputDirectory() );
javadocOutputDirectory.mkdirs();
@@ -1025,14 +1089,7 @@
List arguments = new ArrayList();
cmd.setWorkingDirectory( javadocOutputDirectory.getAbsolutePath() );
- try
- {
- cmd.setExecutable( getJavadocPath() );
- }
- catch ( IOException e )
- {
- throw new MavenReportException( "Unable to find javadoc command: "
+ e.getMessage(), e );
- }
+ cmd.setExecutable( jExecutable );
// General javadoc arguments
addArgIf( arguments, breakiterator, "-breakiterator",
SINCE_JAVADOC_1_4 );
@@ -1044,7 +1101,7 @@
addArgIfNotEmpty( arguments, "-encoding", quotedArgument( encoding ) );
addArgIfNotEmpty( arguments, "-extdirs", quotedPathArgument( extdirs )
);
- if ( old && SystemUtils.isJavaVersionAtLeast( SINCE_JAVADOC_1_4 ) )
+ if ( old && isJavaDocVersionAtLeast( SINCE_JAVADOC_1_4 ) )
{
getLog().warn( "Javadoc 1.4 doesn't support the -1.1 switch
anymore. Ignore this option." );
}
@@ -1084,7 +1141,8 @@
if ( StringUtils.isEmpty( doclet ) )
{
addArgIf( arguments, author, "-author" );
- addArgIfNotEmpty( arguments, "-bottom", quotedArgument(
getBottomText( project.getInceptionYear() ) ), false, false );
+ addArgIfNotEmpty( arguments, "-bottom", quotedArgument(
getBottomText( project.getInceptionYear() ) ),
+ false, false );
addArgIf( arguments, breakiterator, "-breakiterator",
SINCE_JAVADOC_1_4 );
addArgIfNotEmpty( arguments, "-charset", quotedArgument( charset )
);
addArgIfNotEmpty( arguments, "-d", quotedPathArgument(
javadocOutputDirectory.toString() ) );
@@ -1283,7 +1341,7 @@
for ( Iterator i = sourcePaths.iterator(); i.hasNext(); )
{
- File sourceDirectory = new File((String) i.next());
+ File sourceDirectory = new File( (String) i.next() );
addFilesFromSource( files, sourceDirectory, excludedPackages );
}
}
@@ -1876,13 +1934,13 @@
}
/**
- * Get the path of Javadoc tool depending the OS, the
<code>java.home</code> system property and the
- * <code>JAVA_HOME</code> environment variable
+ * Get the path of the Javadoc tool executable depending the user entry or
try to find it depending the OS
+ * or the <code>java.home</code> system property or the
<code>JAVA_HOME</code> environment variable.
*
* @return the path of the Javadoc tool
* @throws IOException if not found
*/
- private String getJavadocPath()
+ private String getJavadocExecutable()
throws IOException
{
String javadocCommand = "javadoc" + ( SystemUtils.IS_OS_WINDOWS ?
".exe" : "" );
@@ -1890,11 +1948,26 @@
File javadocExe;
//
----------------------------------------------------------------------
+ // The javadoc executable is defined by the user
+ //
----------------------------------------------------------------------
+ if ( StringUtils.isNotEmpty( javadocExecutable ) )
+ {
+ javadocExe = new File( javadocExecutable );
+
+ if ( !javadocExe.exists() || !javadocExe.isFile() )
+ {
+ throw new IOException( "The javadoc executable '" + javadocExe
+ "' doesn't exist or is not a file. "
+ + "Verify the <javadocExecutable/> parameter." );
+ }
+
+ return javadocExe.getAbsolutePath();
+ }
+
+ //
----------------------------------------------------------------------
// Try to find javadocExe from System.getProperty( "java.home" )
// By default, System.getProperty( "java.home" ) = JRE_HOME and
JRE_HOME
// should be in the JDK_HOME
//
----------------------------------------------------------------------
-
// For IBM's JDK 1.2
if ( SystemUtils.IS_OS_AIX )
{
@@ -1914,7 +1987,6 @@
//
----------------------------------------------------------------------
// Try to find javadocExe from JAVA_HOME environment variable
//
----------------------------------------------------------------------
-
if ( !javadocExe.exists() || !javadocExe.isFile() )
{
Properties env = CommandLineUtils.getSystemEnvVars();
@@ -1942,6 +2014,70 @@
}
/**
+ * Call the javadoc tool to have its version
+ *
+ * @param javadocExe
+ * @return the javadoc version as float
+ * @throws IOException if any
+ * @throws CommandLineException if any
+ */
+ private static float getJavadocVersion( File javadocExe )
+ throws IOException, CommandLineException
+ {
+ if ( !javadocExe.exists() || !javadocExe.isFile() )
+ {
+ throw new IOException( "The javadoc executable '" + javadocExe +
"' doesn't exist or is not a file. " );
+ }
+
+ Commandline cmd = new Commandline();
+ cmd.setExecutable( javadocExe.getAbsolutePath() );
+ cmd.setWorkingDirectory( javadocExe.getParentFile() );
+ cmd.createArgument().setValue( "-J-fullversion" );
+
+ CommandLineUtils.StringStreamConsumer out = new
CommandLineUtils.StringStreamConsumer();
+ CommandLineUtils.StringStreamConsumer err = new
CommandLineUtils.StringStreamConsumer();
+
+ int exitCode = CommandLineUtils.executeCommandLine( cmd, out, err );
+
+ if ( exitCode != 0 )
+ {
+ StringBuffer msg = new StringBuffer( "Exit code: " + exitCode + "
- " + err.getOutput() );
+ msg.append( '\n' );
+ msg.append( "Command line was:" + Commandline.toString(
cmd.getCommandline() ) );
+ throw new CommandLineException( msg.toString() );
+ }
+
+ /*
+ * Exemple: java full version "1.5.0_11-b03"
+ *
+ * @see com.sun.tools.javac.main.JavaCompiler#fullVersion()
+ */
+ StringTokenizer token = new StringTokenizer( err.getOutput(), "\"" );
+ token.nextToken();
+
+ String version = token.nextToken();
+ String str = version.substring( 0, 3 );
+ if ( version.length() >= 5 )
+ {
+ str = str + version.substring( 4, 5 );
+ }
+
+ return Float.parseFloat( str );
+ }
+
+ /**
+ * Is the Java or Javadoc version at least the requested version.
+ *
+ * @param requiredVersion the required version, for example 1.5f
+ * @return <code>true</code> if the java version or the javadoc version is
equal or greater than the
+ * required version
+ */
+ private boolean isJavaDocVersionAtLeast( float requiredVersion )
+ {
+ return ( SystemUtils.isJavaVersionAtLeast( requiredVersion ) ||
fJavadocVersion >= requiredVersion );
+ }
+
+ /**
* Convenience method to add an argument to the <code>command line</code>
* conditionally based on the given flag.
*
@@ -1970,7 +2106,7 @@
*/
private void addArgIf( List arguments, boolean b, String value, float
requiredJavaVersion )
{
- if ( SystemUtils.isJavaVersionAtLeast( requiredJavaVersion ) )
+ if ( isJavaDocVersionAtLeast( requiredJavaVersion ) )
{
addArgIf( arguments, b, value );
}
@@ -2008,8 +2144,7 @@
* @param repeatKey repeat or not the key in the command line
* @param splitValue if <code>true</code> given value will be tokenized
by comma
*/
- private void addArgIfNotEmpty( List arguments, String key, String value,
- boolean repeatKey, boolean splitValue )
+ private void addArgIfNotEmpty( List arguments, String key, String value,
boolean repeatKey, boolean splitValue )
{
if ( StringUtils.isNotEmpty( value ) )
{
@@ -2018,7 +2153,8 @@
arguments.add( key );
}
- if (splitValue) {
+ if ( splitValue )
+ {
StringTokenizer token = new StringTokenizer( value, "," );
while ( token.hasMoreTokens() )
{
@@ -2034,7 +2170,9 @@
}
}
}
- } else {
+ }
+ else
+ {
arguments.add( value );
}
}
@@ -2051,11 +2189,11 @@
* @param value the argument value to be added.
* @param repeatKey repeat or not the key in the command line
*/
- private void addArgIfNotEmpty( List arguments, String key, String value,
boolean repeatKey ) {
- addArgIfNotEmpty(arguments, key, value, repeatKey, true);
+ private void addArgIfNotEmpty( List arguments, String key, String value,
boolean repeatKey )
+ {
+ addArgIfNotEmpty( arguments, key, value, repeatKey, true );
}
-
/**
* Convenience method to add an argument to the <code>command line</code>
* regarding the requested Java version.
@@ -2084,9 +2222,9 @@
* @see <a
href="http://jakarta.apache.org/commons/lang/api/org/apache/commons/lang/SystemUtils.html#isJavaVersionAtLeast(float)">SystemUtils.html#isJavaVersionAtLeast(float)</a>
*/
private void addArgIfNotEmpty( List arguments, String key, String value,
float requiredJavaVersion,
- boolean repeatKey )
+ boolean repeatKey )
{
- if ( SystemUtils.isJavaVersionAtLeast( requiredJavaVersion ) )
+ if ( isJavaDocVersionAtLeast( requiredJavaVersion ) )
{
addArgIfNotEmpty( arguments, key, value, repeatKey );
}
@@ -2250,7 +2388,8 @@
* @param outputDirectory the output directory
* @throws java.io.IOException if any
*/
- private void copyJavadocResources( File outputDirectory ) throws
IOException
+ private void copyJavadocResources( File outputDirectory )
+ throws IOException
{
if ( outputDirectory == null || !outputDirectory.exists() )
{
@@ -2285,7 +2424,8 @@
* @param javadocDir the javadoc directory
* @throws java.io.IOException if any
*/
- private static void copyJavadocResources( File outputDirectory, File
javadocDir ) throws IOException
+ private static void copyJavadocResources( File outputDirectory, File
javadocDir )
+ throws IOException
{
if ( javadocDir.exists() && javadocDir.isDirectory() )
{
@@ -2361,9 +2501,9 @@
{
int i = fileList[j].lastIndexOf(
File.separatorChar );
String packageName = fileList[j].substring( 0, i +
1 );
- File currentPackage = new File(packageName);
- File excludedPackage = new File(sourceDirectory,
excludeName[0]);
- if ( currentPackage.equals( excludedPackage )
+ File currentPackage = new File( packageName );
+ File excludedPackage = new File( sourceDirectory,
excludeName[0] );
+ if ( currentPackage.equals( excludedPackage )
&& fileList[j].substring( i ).indexOf( ".java"
) != -1 )
{
include = true;
@@ -2544,7 +2684,7 @@
* @throws MavenReportException if any
*/
private void addCommandLineOptions( Commandline cmd, StringBuffer options,
List arguments,
- File javadocOutputDirectory )
+ File javadocOutputDirectory )
throws MavenReportException
{
File optionsFile = new File( javadocOutputDirectory, "options" );
@@ -2590,7 +2730,7 @@
throws MavenReportException
{
File argfileFile;
- if ( SystemUtils.isJavaVersionAtLeast( SINCE_JAVADOC_1_4 ) )
+ if ( isJavaDocVersionAtLeast( SINCE_JAVADOC_1_4 ) )
{
argfileFile = new File( javadocOutputDirectory, "argfile" );
}
@@ -2610,7 +2750,7 @@
+ "' temporary file for command execution", e );
}
- if ( SystemUtils.isJavaVersionAtLeast( SINCE_JAVADOC_1_4 ) )
+ if ( isJavaDocVersionAtLeast( SINCE_JAVADOC_1_4 ) )
{
cmd.createArgument().setValue( "@argfile" );
}
Added:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt?view=auto&rev=537398
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt
(added)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt
Sat May 12 05:30:17 2007
@@ -0,0 +1,85 @@
+ ------
+ Using Alternate Javadoc Tool
+ ------
+ Vincent Siveton
+ ------
+ May 2007
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+Using Alternate Javadoc Tool
+
+* Using Alternate Javadoc Executable
+
+ By default, the Maven Javadoc Plugin tries to auto-detect the Javadoc Tool
executable from the Java property
+ <java.home> or from the environment variable <JAVA_HOME>.
+
+ You could also specify the executable of the Javadoc Tool to use. For example:
+
++-----+
+<project>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <configuration>
+
<javadocExecutable>C:\jdk1.6.0\bin\javadoc.exe</javadocExecutable>
+ ...
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </reporting>
+ ...
+</project>
++-----+
+
+* Using Alternate Javadoc Version
+
+ In the same way, the Maven Javadoc Plugin tries to auto-detect the Javadoc
Tool version by calling
+ <javadoc -J-fullversion>.
+
+ You could also specify the version of the Javadoc Tool executable. For
example:
+
++-----+
+<project>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <configuration>
+ <javadocVersion>1.5</javadocVersion>
+ ...
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </reporting>
+ ...
+</project>
++-----+
+
+ <<Note>>: You could have a warning if the <javadocVersion> specified is not
the same that the Javadoc Tool executable.
Propchange:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt?view=diff&rev=537398&r1=537397&r2=537398
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt Sat May 12
05:30:17 2007
@@ -69,6 +69,8 @@
* {{{examples/alternate-doclet.html}Using Alternate Doclet}}
+ * {{{examples/alternate-javadoc-tool.html}Using Alternate Javadoc Tool}}
+
* {{{examples/exclude-package-names.html}Excluding Packages}}
* {{{examples/group-configuration.html}Grouping Packages}}
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml?view=diff&rev=537398&r1=537397&r2=537398
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml Sat May 12
05:30:17 2007
@@ -34,6 +34,7 @@
<menu name="Examples">
<item name="Aggregating Javadocs" href="/examples/aggregate.html"/>
<item name="Using Alternate Doclets"
href="/examples/alternate-doclet.html"/>
+ <item name="Using Alternate Javadoc Tool"
href="/examples/alternate-javadoc-tool.html"/>
<item name="Excluding Packages"
href="/examples/exclude-package-names.html"/>
<item name="Grouping Packages"
href="/examples/group-configuration.html"/>
<item name="Configuring Stylesheets"
href="/examples/stylesheet-configuration.html"/>
