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