1 package org.apache.maven.plugin.javadoc; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import java.io.File; 23 import java.util.ArrayList; 24 import java.util.Collections; 25 import java.util.LinkedList; 26 import java.util.List; 27 import java.util.Locale; 28 import java.util.ResourceBundle; 29 30 import org.apache.maven.artifact.resolver.ArtifactResolutionResult; 31 import org.apache.maven.project.MavenProject; 32 import org.apache.maven.reporting.MavenReportException; 33 import org.codehaus.plexus.util.StringUtils; 34 35 /** 36 * Generates documentation for the <code>Java Test code</code> in an <b>NON aggregator</b> project using the standard 37 * <a href="http://java.sun.com/j2se/javadoc/">Javadoc Tool</a>. 38 * 39 * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a> 40 * @version $Id$ 41 * @since 2.3 42 * @goal test-javadoc 43 * @execute phase=generate-test-sources 44 * @requiresDependencyResolution test 45 * @see <a href="http://java.sun.com/j2se/javadoc/">Javadoc Tool</a> 46 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#options">Javadoc Options </a> 47 */ 48 public class TestJavadocReport 49 extends JavadocReport 50 { 51 // ---------------------------------------------------------------------- 52 // Javadoc Options (should be inline with options defined in TestJavadocJar) 53 // ---------------------------------------------------------------------- 54 55 /** 56 * Specifies the Test title to be placed near the top of the overview summary file. 57 * <br/> 58 * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#doctitle">doctitle</a>. 59 * <br/> 60 * 61 * @parameter expression="${testDoctitle}" alias="doctitle" 62 * default-value="${project.name} ${project.version} Test API" 63 * @since 2.5 64 */ 65 private String testDoctitle; 66 67 /** 68 * Specifies that Javadoc should retrieve the text for the Test overview documentation from the "source" file 69 * specified by path/filename and place it on the Overview page (overview-summary.html). 70 * <br/> 71 * <b>Note</b>: could be in conflict with <nooverview/>. 72 * <br/> 73 * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#overview">overview</a>. 74 * <br/> 75 * 76 * @parameter expression="${testOverview}" alias="overview" 77 * default-value="${basedir}/src/test/javadoc/overview.html" 78 * @since 2.5 79 */ 80 private File testOverview; 81 82 /** 83 * Specifies the Test title to be placed in the HTML title tag. 84 * <br/> 85 * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#windowtitle">windowtitle</a>. 86 * <br/> 87 * 88 * @parameter expression="${testWindowtitle}" alias="windowtitle" 89 * default-value="${project.name} ${project.version} Test API" 90 * @since 2.5 91 */ 92 private String testWindowtitle; 93 94 // ---------------------------------------------------------------------- 95 // Mojo Parameters (should be inline with options defined in TestJavadocJar) 96 // ---------------------------------------------------------------------- 97 98 /** 99 * Specifies the destination directory where test Javadoc saves the generated HTML files. 100 * 101 * @parameter expression="${reportTestOutputDirectory}" default-value="${project.reporting.outputDirectory}/testapidocs" 102 * @required 103 */ 104 private File reportOutputDirectory; 105 106 /** 107 * The name of the destination directory. 108 * <br/> 109 * 110 * @parameter expression="${destDir}" default-value="testapidocs" 111 */ 112 private String destDir; 113 114 /** 115 * Specifies the Test Javadoc resources directory to be included in the Javadoc (i.e. package.html, images...). 116 * <br/> 117 * Could be used in addition of <code>docfilessubdirs</code> parameter. 118 * <br/> 119 * See <a href="#docfilessubdirs">docfilessubdirs</a>. 120 * 121 * @parameter expression="${basedir}/src/test/javadoc" alias="javadocDirectory" 122 * @since 2.5 123 */ 124 private File testJavadocDirectory; 125 126 // ---------------------------------------------------------------------- 127 // Report Mojo Parameters 128 // ---------------------------------------------------------------------- 129 130 /** 131 * The name of the Test Javadoc report to be displayed in the Maven Generated Reports page 132 * (i.e. <code>project-reports.html</code>). 133 * 134 * @parameter expression="${testName}" alias="name" 135 * @since 2.5 136 */ 137 private String testName; 138 139 /** 140 * The description of the Test Javadoc report to be displayed in the Maven Generated Reports page 141 * (i.e. <code>project-reports.html</code>). 142 * 143 * @parameter expression="${testDescription}" alias="description" 144 * @since 2.5 145 */ 146 private String testDescription; 147 148 // ---------------------------------------------------------------------- 149 // Report public methods 150 // ---------------------------------------------------------------------- 151 152 /** {@inheritDoc} */ 153 protected void executeReport( Locale unusedLocale ) 154 throws MavenReportException 155 { 156 addMainJavadocLink(); 157 158 super.executeReport( unusedLocale ); 159 } 160 161 /** {@inheritDoc} */ 162 public String getName( Locale locale ) 163 { 164 if ( StringUtils.isEmpty( testName ) ) 165 { 166 return getBundle( locale ).getString( "report.test-javadoc.name" ); 167 } 168 169 return testName; 170 } 171 172 /** {@inheritDoc} */ 173 public String getDescription( Locale locale ) 174 { 175 if ( StringUtils.isEmpty( testDescription ) ) 176 { 177 return getBundle( locale ).getString( "report.test-javadoc.description" ); 178 } 179 180 return testDescription; 181 } 182 183 /** {@inheritDoc} */ 184 public String getOutputName() 185 { 186 return destDir + "/index"; 187 } 188 189 /** {@inheritDoc} */ 190 public File getReportOutputDirectory() 191 { 192 if ( reportOutputDirectory == null ) 193 { 194 return outputDirectory; 195 } 196 197 return reportOutputDirectory; 198 } 199 200 /** 201 * Method to set the directory where the generated reports will be put 202 * 203 * @param reportOutputDirectory the directory file to be set 204 */ 205 public void setReportOutputDirectory( File reportOutputDirectory ) 206 { 207 updateReportOutputDirectory( reportOutputDirectory, destDir ); 208 } 209 210 public void setDestDir( String destDir ) 211 { 212 this.destDir = destDir; 213 updateReportOutputDirectory( reportOutputDirectory, destDir ); 214 } 215 216 private void updateReportOutputDirectory( File reportOutputDirectory, String destDir ) 217 { 218 if ( reportOutputDirectory != null && destDir != null 219 && !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) ) 220 { 221 this.reportOutputDirectory = new File( reportOutputDirectory, destDir ); 222 } 223 else 224 { 225 this.reportOutputDirectory = reportOutputDirectory; 226 } 227 } 228 229 // ---------------------------------------------------------------------- 230 // Protected methods 231 // Important Note: should be inline with methods defined in TestJavadocJar 232 // ---------------------------------------------------------------------- 233 234 /** {@inheritDoc} */ 235 protected List getProjectBuildOutputDirs( MavenProject p ) 236 { 237 List dirs = new ArrayList(); 238 if ( StringUtils.isNotEmpty( p.getBuild().getOutputDirectory() ) ) 239 { 240 dirs.add( p.getBuild().getOutputDirectory() ); 241 } 242 if ( StringUtils.isNotEmpty( p.getBuild().getTestOutputDirectory() ) ) 243 { 244 dirs.add( p.getBuild().getTestOutputDirectory() ); 245 } 246 247 return dirs; 248 } 249 250 /** {@inheritDoc} */ 251 protected List getProjectSourceRoots( MavenProject p ) 252 { 253 if ( "pom".equals( p.getPackaging().toLowerCase() ) ) 254 { 255 return Collections.EMPTY_LIST; 256 } 257 258 return ( p.getTestCompileSourceRoots() == null ? Collections.EMPTY_LIST 259 : new LinkedList( p.getTestCompileSourceRoots() ) ); 260 } 261 262 /** {@inheritDoc} */ 263 protected List getExecutionProjectSourceRoots( MavenProject p ) 264 { 265 if ( "pom".equals( p.getExecutionProject().getPackaging().toLowerCase() ) ) 266 { 267 return Collections.EMPTY_LIST; 268 } 269 270 return ( p.getExecutionProject().getTestCompileSourceRoots() == null ? Collections.EMPTY_LIST 271 : new LinkedList( p.getExecutionProject().getTestCompileSourceRoots() ) ); 272 } 273 274 /** {@inheritDoc} */ 275 protected List getProjectArtifacts( MavenProject p ) 276 { 277 return ( p.getTestArtifacts() == null ? Collections.EMPTY_LIST : new LinkedList( p.getTestArtifacts() ) ); 278 } 279 280 /** {@inheritDoc} */ 281 protected File getJavadocDirectory() 282 { 283 return testJavadocDirectory; 284 } 285 286 /** {@inheritDoc} */ 287 protected String getDoctitle() 288 { 289 return testDoctitle; 290 } 291 292 /** {@inheritDoc} */ 293 protected File getOverview() 294 { 295 return testOverview; 296 } 297 298 /** {@inheritDoc} */ 299 protected String getWindowtitle() 300 { 301 return testWindowtitle; 302 } 303 304 /** {@inheritDoc} */ 305 protected List getCompileArtifacts( ArtifactResolutionResult result ) 306 { 307 return JavadocUtil.getCompileArtifacts( result.getArtifacts(), true ); 308 } 309 310 /** 311 * Gets the resource bundle for the specified locale. 312 * 313 * @param locale The locale of the currently generated report. 314 * @return The resource bundle for the requested locale. 315 */ 316 private ResourceBundle getBundle( Locale locale ) 317 { 318 return ResourceBundle.getBundle( "test-javadoc-report", locale, getClass().getClassLoader() ); 319 } 320 321 /** 322 * Add the <code>../apidocs</code> to the links parameter so Test report could be linked to the Main report. 323 */ 324 private void addMainJavadocLink() 325 { 326 if ( links == null ) 327 { 328 links = new ArrayList(); 329 } 330 331 // TODO the prerequisite is that the main report is in apidocs 332 File apidocs = new File( getReportOutputDirectory().getParentFile(), "apidocs" ); 333 if ( apidocs.isDirectory() && !links.contains( "../apidocs" ) ) 334 { 335 links.add( "../apidocs" ); 336 } 337 } 338 }