PR: MNG-926

Submitted by: Johnny R. Ruiz III
Reviewed by:  Brett Porter
assembly plugin documentation

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@290859 13f79535-47bb-0310-9956-ffa450edef68

maven-plugins/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/AbstractUnpackingMojo.java

@@ -16,6 +16,9 @@ package org.apache.maven.plugin.assembly;
  * limitations under the License.
  */
 
+import org.apache.maven.plugin.AbstractMojo;
+import org.codehaus.plexus.util.IOUtil;
+
 import java.io.File;
 import java.io.FileOutputStream;
 import java.io.IOException;
@@ -26,11 +29,8 @@ import java.util.jar.JarFile;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipFile;
 
-import org.apache.maven.plugin.AbstractMojo;
-import org.codehaus.plexus.util.IOUtil;
-
 /**
- * Base routines for assembly and unpack goals
+ * Base routines for assembly and unpack goals.
  *
  * @version $Id$
  */
@@ -40,18 +40,24 @@ public abstract class AbstractUnpackingMojo
     static protected final String[] EMPTY_STRING_ARRAY = {};
 
     /**
+     * The output directory of the assembled distribution file.
+     *
      * @parameter expression="${project.build.directory}"
      * @required
      */
     protected File outputDirectory;
 
     /**
+     * The filename of the assembled distribution file.
+     *
      * @parameter expression="${project.build.finalName}"
      * @required
      */
     protected String finalName;
 
     /**
+     * Project dependencies.
+     *
      * @parameter expression="${project.artifacts}"
      * @readonly
      */
@@ -59,12 +65,22 @@ public abstract class AbstractUnpackingMojo
 
     /**
      * Directory to unpack JARs into if needed
+     *
      * @parameter expression="${project.build.directory}/assembly/work"
      * @required
      */
     protected File workDirectory;
 
-	protected void unpack(File file, File location) throws IOException {
+    /**
+     * Unpacks the archive file.
+     *
+     * @param file File to be unpacked.
+     * @param location Location where to put the unpacked files.
+     * @throws IOException
+     */
+    protected void unpack( File file, File location )
+        throws IOException
+    {
         String fileName = file.getAbsolutePath().toLowerCase().trim();
         // Should be checking for '.' too?
         // Not doing this to be consistent with existing code
@@ -78,6 +94,13 @@ public abstract class AbstractUnpackingMojo
         }
     }
 
+    /**
+     * Unpacks the Jar file.
+     *
+     * @param file File to be unpack/unjar.
+     * @param tempLocation Location where to put the unpacked files.
+     * @throws IOException
+     */
     private void unpackJar( File file, File tempLocation )
         throws IOException
     {
@@ -101,7 +124,16 @@ public abstract class AbstractUnpackingMojo
         }
     }
 
-	private void unpackZip(File file, File tempLocation) throws IOException {
+    /**
+     * Unpacks the Zip file.
+     *
+     * @param file Zip file to be unpacked.
+     * @param tempLocation Location where to unpack the files.
+     * @throws IOException
+     */
+    private void unpackZip( File file, File tempLocation )
+        throws IOException
+    {
         if ( !file.getAbsolutePath().toLowerCase().trim().endsWith( "zip" ) )
         {
             getLog().warn( "Trying to unpack a non-zip file " + file.getAbsolutePath() + " - IGNORING" );

maven-plugins/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/AssemblyMojo.java

@@ -71,16 +71,22 @@ public class AssemblyMojo
 {
 
     /**
+     * Predefined Assembly Descriptor Id's.  You can select bin, jar-with-dependencies, or src.
+     *
      * @parameter expression="${maven.assembly.descriptorId}"
      */
     protected String descriptorId;
 
     /**
+     * Assembly XML Descriptor file.  This must be the path to your customized descriptor file.
+     *
      * @parameter expression="${maven.assembly.descriptor}"
      */
     protected File descriptor;
 
     /**
+     * Base directory of the project.
+     *
      * @parameter expression="${basedir}"
      * @required
      * @readonly
@@ -88,6 +94,8 @@ public class AssemblyMojo
     private String basedir;
 
     /**
+     * The Maven Project.
+     *
      * @parameter expression="${project}"
      * @required
      * @readonly
@@ -95,6 +103,8 @@ public class AssemblyMojo
     private MavenProject project;
 
     /**
+     * Maven ProjectHelper
+     *
      * @parameter expression="${component.org.apache.maven.project.MavenProjectHelper}"
      * @required
      * @readonly
@@ -102,13 +112,19 @@ public class AssemblyMojo
     private MavenProjectHelper projectHelper;
 
     /**
+     * Temporary directory that contain the files to be assembled.
+     *
      * @parameter expression="${project.build.directory}/archive-tmp"
      * @required
      * @readonly
      */
     private File tempRoot;
 
-
+    /**
+     * Create the binary distribution.
+     *
+     * @throws MojoExecutionException
+     */
     public void execute()
         throws MojoExecutionException
     {
@@ -123,6 +139,11 @@ public class AssemblyMojo
         }
     }
 
+    /**
+     * Create the binary distribution.
+     *
+     * @throws ArchiverException, IOException, MojoExecutionException, XmlPullParserException
+     */
     private void doExecute()
         throws ArchiverException, IOException, MojoExecutionException, XmlPullParserException
     {
@@ -183,6 +204,14 @@ public class AssemblyMojo
         }
     }
 
+    /**
+     * Processes Dependency Sets
+     *
+     * @param archiver
+     * @param dependencySets
+     * @param includeBaseDirectory
+     * @throws ArchiverException, IOException, MojoExecutionException
+     */
     private void processDependencySets( Archiver archiver, List dependencySets, boolean includeBaseDirectory )
         throws ArchiverException, IOException, MojoExecutionException
     {
@@ -192,15 +221,13 @@ public class AssemblyMojo
             String output = dependencySet.getOutputDirectory();
             output = getOutputDirectory( output, includeBaseDirectory );
 
-            archiver.setDefaultDirectoryMode( Integer.parseInt( 
+            archiver.setDefaultDirectoryMode( Integer.parseInt( dependencySet.getDirectoryMode(), 8 ) );
-                    dependencySet.getDirectoryMode(), 8 ) );
 
-            archiver.setDefaultFileMode( Integer.parseInt( 
+            archiver.setDefaultFileMode( Integer.parseInt( dependencySet.getFileMode(), 8 ) );
-                    dependencySet.getFileMode(), 8 ) );
 
-            getLog().debug("DependencySet["+output+"]" +
+            getLog().debug( "DependencySet[" + output + "]" + " dir perms: " +
-                " dir perms: " + Integer.toString( archiver.getDefaultDirectoryMode(), 8 ) +
+                Integer.toString( archiver.getDefaultDirectoryMode(), 8 ) + " file perms: " +
-                " file perms: " + Integer.toString( archiver.getDefaultFileMode(), 8 ) );
+                Integer.toString( archiver.getDefaultFileMode(), 8 ) );
 
             AndArtifactFilter filter = new AndArtifactFilter();
             filter.add( new ScopeArtifactFilter( dependencySet.getScope() ) );
@@ -257,7 +284,14 @@ public class AssemblyMojo
         }
     }
 
-
+    /**
+     * Process Files that will be included in the distribution.
+     *
+     * @param archiver
+     * @param fileSets
+     * @param includeBaseDirecetory
+     * @throws ArchiverException
+     */
     private void processFileSets( Archiver archiver, List fileSets, boolean includeBaseDirecetory )
         throws ArchiverException
     {
@@ -277,15 +311,13 @@ public class AssemblyMojo
                 tmpDir.mkdirs();
             }
 
-            archiver.setDefaultDirectoryMode( Integer.parseInt( 
+            archiver.setDefaultDirectoryMode( Integer.parseInt( fileSet.getDirectoryMode(), 8 ) );
-                    fileSet.getDirectoryMode(), 8 ) );
 
-            archiver.setDefaultFileMode( Integer.parseInt( 
+            archiver.setDefaultFileMode( Integer.parseInt( fileSet.getFileMode(), 8 ) );
-                    fileSet.getFileMode(), 8 ) );
 
-            getLog().debug("FileSet["+output+"]" +
+            getLog().debug( "FileSet[" + output + "]" + " dir perms: " +
-                " dir perms: " + Integer.toString( archiver.getDefaultDirectoryMode(), 8 ) +
+                Integer.toString( archiver.getDefaultDirectoryMode(), 8 ) + " file perms: " +
-                " file perms: " + Integer.toString( archiver.getDefaultFileMode(), 8 ) +
+                Integer.toString( archiver.getDefaultFileMode(), 8 ) +
                 ( fileSet.getLineEnding() == null ? "" : " lineEndings: " + fileSet.getLineEnding() ) );
 
             if ( directory == null )
@@ -316,7 +348,6 @@ public class AssemblyMojo
             excludesList.addAll( getDefaultExcludes() );
             String[] excludes = (String[]) excludesList.toArray( EMPTY_STRING_ARRAY );
 
-            
             File archiveBaseDir = new File( directory );
 
             if ( lineEnding != null )
@@ -330,6 +361,13 @@ public class AssemblyMojo
         }
     }
 
+    /**
+     * Evaluates Filename Mapping
+     *
+     * @param expression
+     * @param artifact
+     * @return expression
+     */
     private static String evaluateFileNameMapping( String expression, Artifact artifact )
         throws MojoExecutionException
     {
@@ -374,6 +412,11 @@ public class AssemblyMojo
         return expression;
     }
 
+    /**
+     * Get the files to be excluded and put it into list.
+     *
+     * @return l List of filename patterns to be excluded.
+     */
     private static List getJarExcludes()
     {
         List l = new ArrayList( getDefaultExcludes() );
@@ -381,6 +424,12 @@ public class AssemblyMojo
         return l;
     }
 
+    /**
+     * Get the Output Directory by parsing the String output directory.
+     *
+     * @param output The string representation of the output directory.
+     * @param includeBaseDirectory True if base directory is to be included in the assembled file.
+     */
     private String getOutputDirectory( String output, boolean includeBaseDirectory )
     {
         if ( output == null )
@@ -414,6 +463,13 @@ public class AssemblyMojo
         return output;
     }
 
+    /**
+     * Creates the necessary archiver to build the distribution file.
+     *
+     * @param format Archive format
+     * @return archiver  Archiver generated
+     * @throws ArchiverException
+     */
     private static Archiver createArchiver( String format )
         throws ArchiverException
     {
@@ -464,6 +520,11 @@ public class AssemblyMojo
         return archiver;
     }
 
+    /**
+     * Insert into the exclude list the default excludes file pattern.
+     *
+     * @return defaultExcludes List containing the default patterns of files to be excluded.
+     */
     public static List getDefaultExcludes()
     {
         List defaultExcludes = new ArrayList();
@@ -515,7 +576,8 @@ public class AssemblyMojo
     }
 
 
-    private void copySetReplacingLineEndings( File archiveBaseDir, File tmpDir, String[] includes, String[] excludes, String lineEnding )
+    private void copySetReplacingLineEndings( File archiveBaseDir, File tmpDir, String[] includes, String[] excludes,
+                                              String lineEnding )
         throws ArchiverException
     {
         DirectoryScanner scanner = new DirectoryScanner();
@@ -545,14 +607,12 @@ public class AssemblyMojo
             }
             catch ( IOException e )
             {
-                throw new ArchiverException("Error copying file '" +
+                throw new ArchiverException( "Error copying file '" + files[j] + "' to '" + targetFile + "'", e );
-                    files[j] + "' to '" + targetFile + "'", e);
             }
         }
 
     }
 
-    
     private static String getLineEndingCharacters( String lineEnding )
         throws ArchiverException
     {
@@ -572,8 +632,7 @@ public class AssemblyMojo
             }
             else
             {
-                throw new ArchiverException( "Illlegal lineEnding specified: '" +
+                throw new ArchiverException( "Illlegal lineEnding specified: '" + lineEnding + "'" );
-                    lineEnding + "'");
             }
         }
 

maven-plugins/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/UnpackMojo.java

@@ -1,11 +1,11 @@
 package org.apache.maven.plugin.assembly;
 
-import java.io.File;
-import java.util.Iterator;
-
 import org.apache.maven.artifact.Artifact;
 import org.apache.maven.plugin.MojoExecutionException;
 
+import java.io.File;
+import java.util.Iterator;
+
 /*
  * Copyright 2001-2005 The Apache Software Foundation.
  *
@@ -33,8 +33,14 @@ import org.apache.maven.plugin.MojoExecutionException;
 public class UnpackMojo
     extends AbstractUnpackingMojo
 {
-
+    /**
-	public void execute() throws MojoExecutionException {
+     * Unpacks the archive file.
+     *
+     * @throws MojoExecutionException
+     */
+    public void execute()
+        throws MojoExecutionException
+    {
         try
         {
             doExecute();
@@ -46,7 +52,14 @@ public class UnpackMojo
         }
     }
 
-	private void doExecute() throws Exception {
+    /**
+     * Unpacks the project dependencies.
+     *
+     * @throws Exception
+     */
+    private void doExecute()
+        throws Exception
+    {
 
         for ( Iterator j = dependencies.iterator(); j.hasNext(); )
         {

maven-plugins/maven-assembly-plugin/src/site/apt/descriptor.apt

@@ -0,0 +1,93 @@
+ ------
+ Maven 2 Assembly Plugin 
+ ------
+ Johnny R. Ruiz III
+ <jruiz@exist.com>
+ ------
+ September 20, 2005
+
+Pre-defined Descriptor Files
+
+*bin.xml    descriptorId:bin
+
+------
+    <assembly>
+      <id>bin</id>
+      <formats>
+        <format>tar.gz</format>
+        <format>tar.bz2</format>
+        <format>zip</format>
+      </formats>
+      <fileSets>
+        <fileSet>
+          <includes>
+            <include>README*</include>
+            <include>LICENSE*</include>
+            <include>NOTICE*</include>
+          </includes>
+        </fileSet>
+        <fileSet>
+          <directory>target</directory>
+          <outputDirectory></outputDirectory>
+          <includes>
+            <include>*.jar</include>
+          </includes>
+        </fileSet>
+      </fileSets>
+    </assembly>
+------
+
+*jar-with-dependencies.xml  descriptorId:jar-with-dependencies
+
+-----
+<assembly>
+  <id>jar-with-dependencies</id>
+  <formats>
+    <format>jar</format>
+  </formats>
+  <includeBaseDirectory>false</includeBaseDirectory>
+  <fileSets>
+    <fileSet>
+      <directory>target/classes</directory>
+      <outputDirectory>/</outputDirectory>
+    </fileSet>
+  </fileSets>
+  <dependencySets>
+    <dependencySet>
+      <outputDirectory>/</outputDirectory>
+      <unpack>true</unpack>
+      <scope>runtime</scope>
+    </dependencySet>
+  </dependencySets>
+</assembly>
+-----
+
+*src.xml   descriptorId:xml
+
+-----
+<assembly>
+  <id>src</id>
+  <formats>
+    <format>tar.gz</format>
+    <format>tar.bz2</format>
+    <format>zip</format>
+  </formats>
+  <fileSets>
+    <fileSet>
+      <includes>
+        <include>README*</include>
+        <include>LICENSE*</include>
+        <include>NOTICE*</include>
+        <include>pom.xml</include>
+      </includes>
+    </fileSet>
+    <fileSet>
+      <directory>src</directory>
+    </fileSet>
+  </fileSets>
+</assembly>
+-----
+
+
+ 
+

maven-plugins/maven-assembly-plugin/src/site/apt/howto.apt

@@ -0,0 +1,72 @@
+ ------
+ Maven 2 Assembly Plugin 
+ ------
+ Johnny R. Ruiz III
+ <jruiz@exist.com>
+ ------
+ September 20, 2005
+
+How to Use
+
+  These is a brief example on how to use the assembly:assembly goal and assembly:unpack goal.  
+  
+  To use the assembly:assembly goal, you must define the descriptor file that you are going to use or 
+  define the descriptorId from the predefined {{{descriptor.html}descriptor ids}}.  
+
+
+* How To use assembly:assembly using a customized descriptor file.  
+
+-----
+  m2 assembly:assembly -Dmaven.assembly.descriptor=path/to/descriptor.xml
+-----
+
+ 
+* How to use assembly:assembly using predefined descriptor ids.
+
+----
+
+  m2 assembly:assembly -Dmaven.assembly.descriptorId=bin      
+
+  or  m2 assembly:assembly -Dmaven.assembly.descriptorId=jar-with-dependencies
+
+  or  m2 assembly:assembly -Dmaven.assembly.descriptorId=src
+
+-----
+
+* How to configure assembly:assembly plugin in pom.xml
+
+ You can also configure this plugin inside your pom.xml.  To run use "m2 assembly:assembly".
+
+-------------------
+<project>
+   ...
+      <build>
+         ...
+        <plugins>
+            <plugin>
+                 <artifactId>maven-assembly-plugin</artifactId>
+                 <version>2.0-beta-1</version>
+                 <configuration>
+                   <descriptor>path/to/descriptor.xml</descriptor>
+                   <finalName>final_name</finalName>
+                   <outputDirectory>output/directory</outputDirectory>
+                   <workDirectory>target/assembly/work</workDirectory>
+                 </configuration>
+            </plugin>
+         </plugins>
+         ...
+      </build>
+   ...
+</project>
+-------------------
+
+* How to use assembly:unpack
+
+  After running this goal, all dependencies will be extracted at the specified "\<workDirectory\>".
+
+-----
+ m2 assembly:unpack
+-----
+
+  For full documentation, click {{{index.html}here}}.
+ 

maven-plugins/maven-assembly-plugin/src/site/apt/introduction.apt

@@ -0,0 +1,23 @@
+ ------
+ Maven 2 Assembly Plugin 
+ ------
+ Johnny R. Ruiz III
+ <jruiz@exist.com>
+ ------
+ September 20, 2005
+
+Introduction
+
+ This plugin is the Maven2 version of Maven1's Distribution Plugin.  
+ 
+ This plugin provides the capability to create a binary distribution and source distribution.  
+ Currently it can create distribution format such as: zip format, tar.bz, tar.gz2, jar format.
+ The goal to do this is "assembly:assembly".
+
+ It also provides the capability to extract all project dependencies on certain working directory.  
+ The goal to do this is "assembly:unpack".
+
+ To learn how to use the plugin, click {{{howto.html}here}}.
+
+ 
+

maven-plugins/maven-assembly-plugin/src/site/site.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!--
+/*
+ * Copyright 2001-2005 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+-->
+
+<project name="Maven Assembly Plugin">
+  <bannerLeft>
+    <name>Maven Assembly Plugin</name>
+    <src>http://maven.apache.org/images/apache-maven-project.png</src>
+    <href>http://maven.apache.org/</href>
+  </bannerLeft>
+  <bannerRight>
+    <src>http://maven.apache.org/images/maven-small.gif</src>
+  </bannerRight>
+  <body>
+    <links>
+      <item name="Maven 2" href="http://maven.apache.org/maven2/"/>
+    </links>
+
+    <menu name="Overview">
+      <item name="Introduction" href="introduction.html"/>
+      <item name="How to Use" href="howto.html"/>
+      <item name="Predefined Descriptors" href="descriptor.html"/>
+    </menu>
+    ${reports}
+  </body>
+</project>