View Javadoc
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 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   * @version $Id: JavadocJar.html 943732 2015-03-14 00:06:30Z khmarbaise $
50   * @since 2.0
51   */
52  @Mojo( name = "jar", defaultPhase = LifecyclePhase.PACKAGE, requiresDependencyResolution = ResolutionScope.COMPILE,
53                  threadSafe = true )
54  public class JavadocJar
55      extends AbstractJavadocMojo
56  {
57      /**
58       * Includes all generated Javadoc files
59       */
60      private static final String[] DEFAULT_INCLUDES = new String[]{ "**/**" };
61  
62      /**
63       * Excludes all processing files.
64       *
65       * @see AbstractJavadocMojo#DEBUG_JAVADOC_SCRIPT_NAME
66       * @see AbstractJavadocMojo#OPTIONS_FILE_NAME
67       * @see AbstractJavadocMojo#PACKAGES_FILE_NAME
68       * @see AbstractJavadocMojo#ARGFILE_FILE_NAME
69       * @see AbstractJavadocMojo#FILES_FILE_NAME
70       */
71      private static final String[] DEFAULT_EXCLUDES =
72          new String[]{ DEBUG_JAVADOC_SCRIPT_NAME, OPTIONS_FILE_NAME, PACKAGES_FILE_NAME, ARGFILE_FILE_NAME,
73              FILES_FILE_NAME };
74  
75      // ----------------------------------------------------------------------
76      // Mojo components
77      // ----------------------------------------------------------------------
78  
79      /**
80       * Used for attaching the artifact in the project.
81       */
82      @Component
83      private MavenProjectHelper projectHelper;
84  
85      /**
86       * The Jar archiver.
87       *
88       * @since 2.5
89       */
90      @Component( role = Archiver.class, hint = "jar" )
91      private JarArchiver jarArchiver;
92  
93      // ----------------------------------------------------------------------
94      // Mojo Parameters
95      // ----------------------------------------------------------------------
96  
97      /**
98       * Specifies the destination directory where javadoc saves the generated HTML files.
99       * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#d">d</a>.
100      *
101      * @deprecated
102      */
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 MavenArchiveConfiguration();
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     /** {@inheritDoc} */
161     public void execute()
162         throws MojoExecutionException
163     {
164         if ( skip )
165         {
166             getLog().info( "Skipping javadoc generation" );
167             return;
168         }
169 
170         File innerDestDir = this.destDir;
171         if ( innerDestDir == null )
172         {
173             innerDestDir = new File( getOutputDirectory() );
174         }
175 
176         if ( !( "pom".equalsIgnoreCase( project.getPackaging() ) && isAggregator() ) )
177         {
178             ArtifactHandler artifactHandler = project.getArtifact().getArtifactHandler();
179             if ( !"java".equals( artifactHandler.getLanguage() ) )
180             {
181                 getLog().info( "Not executing Javadoc as the project is not a Java classpath-capable package" );
182                 return;
183             }
184         }
185 
186         try
187         {
188             executeReport( Locale.getDefault() );
189 
190             if ( innerDestDir.exists() )
191             {
192                 File outputFile = generateArchive( innerDestDir, finalName + "-" + getClassifier() + ".jar" );
193 
194                 if ( !attach )
195                 {
196                     getLog().info( "NOT adding javadoc to attached artifacts list." );
197                 }
198                 else
199                 {
200                     // TODO: these introduced dependencies on the project are going to become problematic - can we export it
201                     //  through metadata instead?
202                     projectHelper.attachArtifact( project, "javadoc", getClassifier(), outputFile );
203                 }
204             }
205         }
206         catch ( ArchiverException e )
207         {
208             failOnError( "ArchiverException: Error while creating archive", e );
209         }
210         catch ( IOException e )
211         {
212             failOnError( "IOException: Error while creating archive", e );
213         }
214         catch ( MavenReportException e )
215         {
216             failOnError( "MavenReportException: Error while creating archive", e );
217         }
218         catch ( RuntimeException e )
219         {
220             failOnError( "RuntimeException: Error while creating archive", e );
221         }
222     }
223 
224     // ----------------------------------------------------------------------
225     // Protected methods
226     // ----------------------------------------------------------------------
227 
228     /**
229      * @return the wanted classifier, i.e. <code>javadoc</code> or <code>test-javadoc</code>
230      */
231     protected String getClassifier()
232     {
233         return classifier;
234     }
235 
236     // ----------------------------------------------------------------------
237     // private methods
238     // ----------------------------------------------------------------------
239 
240     /**
241      * Method that creates the jar file
242      *
243      * @param javadocFiles the directory where the generated jar file will be put
244      * @param jarFileName the filename of the generated jar file
245      * @return a File object that contains the generated jar file
246      * @throws ArchiverException if any
247      * @throws IOException if any
248      */
249     private File generateArchive( File javadocFiles, String jarFileName )
250         throws ArchiverException, IOException
251     {
252         File javadocJar = new File( jarOutputDirectory, jarFileName );
253 
254         if ( javadocJar.exists() )
255         {
256             javadocJar.delete();
257         }
258 
259         MavenArchiver archiver = new MavenArchiver();
260         archiver.setArchiver( jarArchiver );
261         archiver.setOutputFile( javadocJar );
262 
263         File contentDirectory = javadocFiles;
264         if ( !contentDirectory.exists() )
265         {
266             getLog().warn( "JAR will be empty - no content was marked for inclusion!" );
267         }
268         else
269         {
270             archiver.getArchiver().addDirectory( contentDirectory, DEFAULT_INCLUDES, DEFAULT_EXCLUDES );
271         }
272 
273         List<Resource> resources = project.getBuild().getResources();
274 
275         for ( Resource r : resources )
276         {
277             if ( r.getDirectory().endsWith( "maven-shared-archive-resources" ) )
278             {
279                 archiver.getArchiver().addDirectory( new File( r.getDirectory() ) );
280             }
281         }
282 
283         if ( useDefaultManifestFile && defaultManifestFile.exists() && archive.getManifestFile() == null )
284         {
285             getLog().info( "Adding existing MANIFEST to archive. Found under: " + defaultManifestFile.getPath() );
286             archive.setManifestFile( defaultManifestFile );
287         }
288 
289         try
290         {
291             // we don't want Maven stuff
292             archive.setAddMavenDescriptor( false );
293             archiver.createArchive( session, project, archive );
294         }
295         catch ( ManifestException e )
296         {
297             throw new ArchiverException( "ManifestException: " + e.getMessage(), e );
298         }
299         catch ( DependencyResolutionRequiredException e )
300         {
301             throw new ArchiverException( "DependencyResolutionRequiredException: " + e.getMessage(), e );
302         }
303 
304         return javadocJar;
305     }
306 }