View Javadoc
1   package org.apache.maven.plugins.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 org.apache.maven.archiver.MavenArchiveConfiguration;
23  import org.apache.maven.archiver.MavenArchiver;
24  import org.apache.maven.artifact.DependencyResolutionRequiredException;
25  import org.apache.maven.artifact.handler.ArtifactHandler;
26  import org.apache.maven.model.Resource;
27  import org.apache.maven.plugin.MojoExecutionException;
28  import org.apache.maven.plugins.annotations.Component;
29  import org.apache.maven.plugins.annotations.LifecyclePhase;
30  import org.apache.maven.plugins.annotations.Mojo;
31  import org.apache.maven.plugins.annotations.Parameter;
32  import org.apache.maven.plugins.annotations.ResolutionScope;
33  import org.apache.maven.project.MavenProjectHelper;
34  import org.apache.maven.reporting.MavenReportException;
35  import org.codehaus.plexus.archiver.Archiver;
36  import org.codehaus.plexus.archiver.ArchiverException;
37  import org.codehaus.plexus.archiver.jar.JarArchiver;
38  import org.codehaus.plexus.archiver.jar.ManifestException;
39  
40  import java.io.File;
41  import java.io.IOException;
42  import java.util.List;
43  import java.util.Locale;
44  
45  /**
46   * Bundles the Javadoc documentation for <code>main Java code</code> in an <b>NON aggregator</b> project into
47   * a jar using the standard <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/">Javadoc Tool</a>.
48   *
49   * @since 2.0
50   */
51  @Mojo( name = "jar", defaultPhase = LifecyclePhase.PACKAGE, requiresDependencyResolution = ResolutionScope.COMPILE,
52                  threadSafe = true )
53  public class JavadocJar
54      extends AbstractJavadocMojo
55  {
56      /**
57       * Includes all generated Javadoc files
58       */
59      private static final String[] DEFAULT_INCLUDES = new String[]{ "**/**" };
60  
61      /**
62       * Excludes all processing files.
63       *
64       * @see AbstractJavadocMojo#DEBUG_JAVADOC_SCRIPT_NAME
65       * @see AbstractJavadocMojo#OPTIONS_FILE_NAME
66       * @see AbstractJavadocMojo#PACKAGES_FILE_NAME
67       * @see AbstractJavadocMojo#ARGFILE_FILE_NAME
68       * @see AbstractJavadocMojo#FILES_FILE_NAME
69       */
70      private static final String[] DEFAULT_EXCLUDES =
71          new String[]{ DEBUG_JAVADOC_SCRIPT_NAME, OPTIONS_FILE_NAME, PACKAGES_FILE_NAME, ARGFILE_FILE_NAME,
72              FILES_FILE_NAME };
73  
74      // ----------------------------------------------------------------------
75      // Mojo components
76      // ----------------------------------------------------------------------
77  
78      /**
79       * Used for attaching the artifact in the project.
80       */
81      @Component
82      private MavenProjectHelper projectHelper;
83  
84      /**
85       * The Jar archiver.
86       *
87       * @since 2.5
88       */
89      @Component( role = Archiver.class, hint = "jar" )
90      private JarArchiver jarArchiver;
91  
92      // ----------------------------------------------------------------------
93      // Mojo Parameters
94      // ----------------------------------------------------------------------
95  
96      /**
97       * Specifies the destination directory where javadoc saves the generated HTML files.
98       * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#d">d</a>.
99       *
100      * @deprecated
101      */
102     @Deprecated
103     @Parameter( property = "destDir" )
104     private File destDir;
105 
106     /**
107      * Specifies the directory where the generated jar file will be put.
108      */
109     @Parameter( property = "project.build.directory" )
110     private String jarOutputDirectory;
111 
112     /**
113      * Specifies the filename that will be used for the generated jar file. Please note that <code>-javadoc</code>
114      * or <code>-test-javadoc</code> will be appended to the file name.
115      */
116     @Parameter( property = "project.build.finalName" )
117     private String finalName;
118 
119     /**
120      * Specifies whether to attach the generated artifact to the project helper.
121      * <br/>
122      */
123     @Parameter( property = "attach", defaultValue = "true" )
124     private boolean attach;
125 
126     /**
127      * The archive configuration to use.
128      * See <a href="http://maven.apache.org/shared/maven-archiver/index.html">Maven Archiver Reference</a>.
129      *
130      * @since 2.5
131      */
132     @Parameter
133     private MavenArchiveConfiguration archive = new JavadocArchiveConfiguration();
134 
135     /**
136      * Path to the default MANIFEST file to use. It will be used if
137      * <code>useDefaultManifestFile</code> is set to <code>true</code>.
138      *
139      * @since 2.5
140      */
141     @Parameter( defaultValue = "${project.build.outputDirectory}/META-INF/MANIFEST.MF", required = true,
142                 readonly = true )
143     private File defaultManifestFile;
144 
145     /**
146      * Set this to <code>true</code> to enable the use of the <code>defaultManifestFile</code>.
147      * <br/>
148      *
149      * @since 2.5
150      */
151     @Parameter( defaultValue = "false" )
152     private boolean useDefaultManifestFile;
153 
154     /**
155      * @since 2.10
156      */
157     @Parameter( property = "maven.javadoc.classifier", defaultValue = "javadoc", required = true )
158     private String classifier;
159 
160     /**
161      * Timestamp for reproducible output archive entries, either formatted as ISO 8601
162      * <code>yyyy-MM-dd'T'HH:mm:ssXXX</code> or as an int representing seconds since the epoch (like
163      * <a href="https://reproducible-builds.org/docs/source-date-epoch/">SOURCE_DATE_EPOCH</a>).
164      *
165      * @since 3.2.0
166      */
167     @Parameter( defaultValue = "${project.build.outputTimestamp}" )
168     private String outputTimestamp;
169 
170     /** {@inheritDoc} */
171     @Override
172     public void doExecute()
173         throws MojoExecutionException
174     {
175         if ( skip )
176         {
177             getLog().info( "Skipping javadoc generation" );
178             return;
179         }
180 
181         File innerDestDir = this.destDir;
182         if ( innerDestDir == null )
183         {
184             innerDestDir = new File( getOutputDirectory() );
185         }
186 
187         if ( !isAggregator() || !"pom".equalsIgnoreCase( project.getPackaging() ) )
188         {
189             ArtifactHandler artifactHandler = project.getArtifact().getArtifactHandler();
190             if ( !"java".equals( artifactHandler.getLanguage() ) )
191             {
192                 getLog().info( "Not executing Javadoc as the project is not a Java classpath-capable package" );
193                 return;
194             }
195         }
196 
197         try
198         {
199             executeReport( Locale.getDefault() );
200         }
201         catch ( MavenReportException e )
202         {
203             failOnError( "MavenReportException: Error while generating Javadoc", e );
204         }
205         catch ( RuntimeException e )
206         {
207             failOnError( "RuntimeException: Error while generating Javadoc", e );
208         }
209 
210         if ( innerDestDir.exists() )
211         {
212             try
213             {
214                 File outputFile = generateArchive( innerDestDir, finalName + "-" + getClassifier() + ".jar" );
215 
216                 if ( !attach )
217                 {
218                     getLog().info( "NOT adding javadoc to attached artifacts list." );
219                 }
220                 else
221                 {
222                     // TODO: these introduced dependencies on the project are going to become problematic - can we export it
223                     //  through metadata instead?
224                     projectHelper.attachArtifact( project, "javadoc", getClassifier(), outputFile );
225                 }
226             }
227             catch ( ArchiverException e )
228             {
229                 failOnError( "ArchiverException: Error while creating archive", e );
230             }
231             catch ( IOException e )
232             {
233                 failOnError( "IOException: Error while creating archive", e );
234             }
235             catch ( RuntimeException e )
236             {
237                 failOnError( "RuntimeException: Error while creating archive", e );
238             }
239         }
240     }
241 
242     // ----------------------------------------------------------------------
243     // Protected methods
244     // ----------------------------------------------------------------------
245 
246     /**
247      * @return the wanted classifier, i.e. <code>javadoc</code> or <code>test-javadoc</code>
248      */
249     protected String getClassifier()
250     {
251         return classifier;
252     }
253 
254     // ----------------------------------------------------------------------
255     // private methods
256     // ----------------------------------------------------------------------
257 
258     /**
259      * Method that creates the jar file
260      *
261      * @param javadocFiles the directory where the generated jar file will be put
262      * @param jarFileName the filename of the generated jar file
263      * @return a File object that contains the generated jar file
264      * @throws ArchiverException {@link ArchiverException}
265      * @throws IOException {@link IOException}
266      */
267     private File generateArchive( File javadocFiles, String jarFileName )
268         throws ArchiverException, IOException
269     {
270         File javadocJar = new File( jarOutputDirectory, jarFileName );
271 
272         if ( javadocJar.exists() )
273         {
274             javadocJar.delete();
275         }
276 
277         MavenArchiver archiver = new MavenArchiver();
278         archiver.setCreatedBy( "Maven Javadoc Plugin", "org.apache.maven.plugins", "maven-javadoc-plugin" );
279         archiver.setArchiver( jarArchiver );
280         archiver.setOutputFile( javadocJar );
281 
282         // configure for Reproducible Builds based on outputTimestamp value
283         archiver.configureReproducible( outputTimestamp );
284 
285         if ( !javadocFiles.exists() )
286         {
287             getLog().warn( "JAR will be empty - no content was marked for inclusion!" );
288         }
289         else
290         {
291             archiver.getArchiver().addDirectory( javadocFiles, DEFAULT_INCLUDES, DEFAULT_EXCLUDES );
292         }
293 
294         List<Resource> resources = project.getBuild().getResources();
295 
296         for ( Resource r : resources )
297         {
298             if ( r.getDirectory().endsWith( "maven-shared-archive-resources" ) )
299             {
300                 archiver.getArchiver().addDirectory( new File( r.getDirectory() ) );
301             }
302         }
303 
304         if ( useDefaultManifestFile && defaultManifestFile.exists() && archive.getManifestFile() == null )
305         {
306             getLog().info( "Adding existing MANIFEST to archive. Found under: " + defaultManifestFile.getPath() );
307             archive.setManifestFile( defaultManifestFile );
308         }
309 
310         try
311         {
312             archiver.createArchive( session, project, archive );
313         }
314         catch ( ManifestException e )
315         {
316             throw new ArchiverException( "ManifestException: " + e.getMessage(), e );
317         }
318         catch ( DependencyResolutionRequiredException e )
319         {
320             throw new ArchiverException( "DependencyResolutionRequiredException: " + e.getMessage(), e );
321         }
322 
323         return javadocJar;
324     }
325 }