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 946897 2015-04-09 14:21:33Z 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         catch ( MavenReportException e )
191         {
192             failOnError( "MavenReportException: Error while generating Javadoc", e );
193         }
194         catch ( RuntimeException e )
195         {
196             failOnError( "RuntimeException: Error while generating Javadoc", e );
197         }
198 
199         if ( innerDestDir.exists() )
200         {
201             try
202             {
203                 File outputFile = generateArchive( innerDestDir, finalName + "-" + getClassifier() + ".jar" );
204 
205                 if ( !attach )
206                 {
207                     getLog().info( "NOT adding javadoc to attached artifacts list." );
208                 }
209                 else
210                 {
211                     // TODO: these introduced dependencies on the project are going to become problematic - can we export it
212                     //  through metadata instead?
213                     projectHelper.attachArtifact( project, "javadoc", getClassifier(), outputFile );
214                 }
215             }
216             catch ( ArchiverException e )
217             {
218                 failOnError( "ArchiverException: Error while creating archive", e );
219             }
220             catch ( IOException e )
221             {
222                 failOnError( "IOException: Error while creating archive", e );
223             }
224             catch ( RuntimeException e )
225             {
226                 failOnError( "RuntimeException: Error while creating archive", e );
227             }
228         }
229     }
230 
231     // ----------------------------------------------------------------------
232     // Protected methods
233     // ----------------------------------------------------------------------
234 
235     /**
236      * @return the wanted classifier, i.e. <code>javadoc</code> or <code>test-javadoc</code>
237      */
238     protected String getClassifier()
239     {
240         return classifier;
241     }
242 
243     // ----------------------------------------------------------------------
244     // private methods
245     // ----------------------------------------------------------------------
246 
247     /**
248      * Method that creates the jar file
249      *
250      * @param javadocFiles the directory where the generated jar file will be put
251      * @param jarFileName the filename of the generated jar file
252      * @return a File object that contains the generated jar file
253      * @throws ArchiverException {@link ArchiverException}
254      * @throws IOException {@link IOException}
255      */
256     private File generateArchive( File javadocFiles, String jarFileName )
257         throws ArchiverException, IOException
258     {
259         File javadocJar = new File( jarOutputDirectory, jarFileName );
260 
261         if ( javadocJar.exists() )
262         {
263             javadocJar.delete();
264         }
265 
266         MavenArchiver archiver = new MavenArchiver();
267         archiver.setArchiver( jarArchiver );
268         archiver.setOutputFile( javadocJar );
269 
270         File contentDirectory = javadocFiles;
271         if ( !contentDirectory.exists() )
272         {
273             getLog().warn( "JAR will be empty - no content was marked for inclusion!" );
274         }
275         else
276         {
277             archiver.getArchiver().addDirectory( contentDirectory, DEFAULT_INCLUDES, DEFAULT_EXCLUDES );
278         }
279 
280         List<Resource> resources = project.getBuild().getResources();
281 
282         for ( Resource r : resources )
283         {
284             if ( r.getDirectory().endsWith( "maven-shared-archive-resources" ) )
285             {
286                 archiver.getArchiver().addDirectory( new File( r.getDirectory() ) );
287             }
288         }
289 
290         if ( useDefaultManifestFile && defaultManifestFile.exists() && archive.getManifestFile() == null )
291         {
292             getLog().info( "Adding existing MANIFEST to archive. Found under: " + defaultManifestFile.getPath() );
293             archive.setManifestFile( defaultManifestFile );
294         }
295 
296         try
297         {
298             // we don't want Maven stuff
299             archive.setAddMavenDescriptor( false );
300             archiver.createArchive( session, project, archive );
301         }
302         catch ( ManifestException e )
303         {
304             throw new ArchiverException( "ManifestException: " + e.getMessage(), e );
305         }
306         catch ( DependencyResolutionRequiredException e )
307         {
308             throw new ArchiverException( "DependencyResolutionRequiredException: " + e.getMessage(), e );
309         }
310 
311         return javadocJar;
312     }
313 }