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