* Moved maven-rar-plugin from the sandbox to maven-plugins

* MNG-854: Added javadoc and web site doco


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

maven-plugins/maven-rar-plugin/pom.xml

@@ -0,0 +1,23 @@
+<model>
+  <parent>
+    <artifactId>maven-plugin-parent</artifactId>
+    <groupId>org.apache.maven.plugins</groupId>
+    <version>2.0-beta-1</version>
+  </parent>
+  <modelVersion>4.0.0</modelVersion>
+  <artifactId>maven-rar-plugin</artifactId>
+  <packaging>maven-plugin</packaging>
+  <name>Maven Rar plugin</name>
+  <version>2.0-beta-2-SNAPSHOT</version>
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-archiver</artifactId>
+      <version>2.0-beta-1</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-project</artifactId>      
+    </dependency>    
+  </dependencies>
+</model>

maven-plugins/maven-rar-plugin/src/main/java/org/apache/maven/plugin/rar/RarMojo.java

@@ -0,0 +1,259 @@
+package org.apache.maven.plugin.rar;
+
+/*
+ * 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.
+ */
+
+import org.apache.maven.plugin.AbstractMojo;
+import org.apache.maven.plugin.MojoExecutionException;
+import org.apache.maven.archiver.MavenArchiver;
+import org.apache.maven.archiver.MavenArchiveConfiguration;
+import org.apache.maven.project.MavenProject;
+import org.apache.maven.artifact.Artifact;
+import org.codehaus.plexus.util.FileUtils;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.Iterator;
+import java.util.Set;
+
+/**
+ * Builds J2EE Resource Adapter Archive (RAR) files.
+ *
+ * @author <a href="stephane.nicoll@gmail.com">Stephane Nicoll</a>
+ * @version $Id$
+ * @goal rar
+ * @phase package
+ * @requiresDependencyResolution test
+ * @description builds a rar
+ */
+public class RarMojo
+    extends AbstractMojo
+{
+    public static final String RA_XML_URI = "META-INF/ra.xml";
+
+
+    /**
+     * Single directory for extra files to include in the RAR.
+     *
+     * @parameter expression="${basedir}/src/rar"
+     * @required
+     */
+    private String rarSourceDirectory;
+
+    /**
+     * The location of the ra.xml file to be used within the rar file.
+     *
+     * @parameter expression="${basedir}/src/rar/META-INF/ra.xml"
+     */
+    private String raXmlFile;
+
+    /**
+     * Specify if the generated jar file of this project should be
+     * included in the rar file ; default is true.
+     *
+     * @parameter
+     */
+    private Boolean includeJar = Boolean.TRUE;
+
+    /**
+     * The location of the manifest file to be used within the rar file.
+     *
+     * @parameter expression="${basedir}/src/rar/META-INF/MANIFEST.MF"
+     */
+    private String manifestFile;
+
+    /**
+     * Directory that resources are copied to during the build.
+     *
+     * @parameter expression="${project.build.directory}/${project.build.finalName}"
+     * @required
+     */
+    private String workDirectory;
+
+    /**
+     * The directory for the generated RAR.
+     *
+     * @parameter expression="${project.build.directory}"
+     * @required
+     */
+    private String outputDirectory;
+
+    /**
+     * The name of the RAR file to generate.
+     *
+     * @parameter alias="rarName" expression="${project.build.finalName}"
+     * @required
+     * @readonly
+     */
+    private String finalName;
+
+    /**
+     * The maven project.
+     *
+     * @parameter expression="${project}"
+     * @required
+     * @readonly
+     * @description "the maven project to use"
+     */
+    private MavenProject project;
+
+    /**
+     * The maven archiver to use.
+     *
+     * @parameter
+     */
+    private MavenArchiveConfiguration archive = new MavenArchiveConfiguration();
+
+
+    private File buildDir;
+
+
+    public void execute()
+        throws MojoExecutionException
+    {
+        getLog().debug( " ======= RarMojo settings =======" );
+        getLog().debug( "rarSourceDirectory[" + rarSourceDirectory + "]" );
+        getLog().debug( "manifestFile[" + manifestFile + "]" );
+        getLog().debug( "raXmlFile[" + raXmlFile + "]" );
+        getLog().debug( "workDirectory[" + workDirectory + "]" );
+        getLog().debug( "outputDirectory[" + outputDirectory + "]" );
+        getLog().debug( "finalName[" + finalName + "]" );
+
+        // Check if jar file is there and if requested, copy it
+        try
+        {
+            if (includeJar.booleanValue()) {
+                File generatedJarFile = new File( outputDirectory, finalName + ".jar" );
+                if (generatedJarFile.exists()) {
+                    getLog().info( "Including generated jar file["+generatedJarFile.getName()+"]");
+                    FileUtils.copyFileToDirectory( generatedJarFile, getBuildDir());
+                }
+            }
+        }
+        catch ( IOException e )
+        {
+            throw new MojoExecutionException( "Error copying generated Jar file", e );
+        }
+
+        // Copy dependencies
+        try
+        {
+            Set artifacts = project.getArtifacts();
+            for ( Iterator iter = artifacts.iterator(); iter.hasNext(); )
+            {
+                Artifact artifact = (Artifact) iter.next();
+                if ( !Artifact.SCOPE_TEST.equals( artifact.getScope() ) &&
+                    !Artifact.SCOPE_PROVIDED.equals( artifact.getScope() ) )
+                {
+                    getLog().info("Copying artifact[" + artifact.getGroupId() + ", " + artifact.getId() + ", " +
+                        artifact.getScope() + "]");
+                    FileUtils.copyFileToDirectory( artifact.getFile(), getBuildDir() );
+                }
+            }
+        }
+        catch ( IOException e )
+        {
+            throw new MojoExecutionException( "Error copying RAR dependencies", e );
+        }
+
+        // Copy source files
+        try
+        {
+            File rarSourceDir = new File( rarSourceDirectory );
+            if ( rarSourceDir.exists() )
+            {
+                getLog().info( "Copy rar resources to " + getBuildDir().getAbsolutePath() );
+                FileUtils.copyDirectoryStructure( rarSourceDir, getBuildDir() );
+            }
+        }
+        catch ( IOException e )
+        {
+            throw new MojoExecutionException( "Error copying RAR resources", e );
+        }
+
+        // Include custom manifest if necessary
+        try
+        {
+            includeCustomRaXmlFile();
+        }
+        catch ( IOException e )
+        {
+            throw new MojoExecutionException( "Error copying ra.xml file", e );
+        }
+
+        // Check if connector deployment descriptor is there
+        File ddFile = new File( getBuildDir(), RA_XML_URI );
+        if ( !ddFile.exists() )
+        {
+            getLog().warn(
+                "Connector deployment descriptor: " + ddFile.getAbsolutePath() + " does not exist." );
+        }
+
+        try
+        {
+            File rarFile = new File( outputDirectory, finalName + ".rar" );
+            MavenArchiver archiver = new MavenArchiver();
+            archiver.setOutputFile( rarFile );
+
+            // Include custom manifest if necessary
+            includeCustomManifestFile();
+
+            archiver.getArchiver().addDirectory( getBuildDir() );
+            archiver.createArchive( project, archive );
+        }
+        catch ( Exception e )
+        {
+            throw new MojoExecutionException( "Error assembling RAR", e );
+        }
+    }
+
+    protected File getBuildDir()
+    {
+        if ( buildDir == null )
+        {
+            buildDir = new File( workDirectory );
+        }
+        return buildDir;
+    }
+
+    private void includeCustomManifestFile()
+    {
+        File customManifestFile = new File( manifestFile );
+        if ( !customManifestFile.exists() )
+        {
+            getLog().info( "Could not find manifest file: " + manifestFile +" - Generating one");
+        }
+        else
+        {
+            getLog().info( "Including custom manifest file[" + customManifestFile + "]" );
+            archive.setManifestFile( customManifestFile );
+        }
+    }
+
+    private void includeCustomRaXmlFile()
+        throws IOException
+    {
+        if (raXmlFile == null || raXmlFile.trim().length() == 0) {
+
+        }
+        File raXml = new File(raXmlFile );
+        if (raXml.exists()) {
+            getLog().info( "Using ra.xml "+ raXmlFile);
+            File metaInfDir = new File(getBuildDir(), "META-INF");
+            FileUtils.copyFileToDirectory( raXml, metaInfDir);
+        }
+    }
+}

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

@@ -0,0 +1,53 @@
+ ------
+ Maven 2 Rar Plugin: configuration examples
+ ------
+ Stephane Nicoll
+ <snicoll@apache.org>
+ ------
+ September 25, 2005
+
+Introduction
+
+  The RAR plugin allows to package resource adapter archive. Invoking this plugin
+  will actually compile and generate an archive for the connector's compiled
+  classes.
+
+  By default, the generated JAR file is included in the RAR file. This behavior
+  is controlled by the <includeJar> property. For instance, to exclude the generated
+  JAR file from the RAR, configure your project as follows:
+
++--------
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-rar-plugin</artifactId>
+        <configuration>
+           <includeJar>false</includeJar>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
++---------
+
+
+   It is also possible to specify a custom location for the ra.xml file. For
+   instance to use the file located in src/resources/ra.xml, configure your
+   project as follows:
+
++--------
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-rar-plugin</artifactId>
+        <configuration>
+           <raXmlFile>src/resources/ra.xml</raXmlFile>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
++---------
+
+
+

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

@@ -0,0 +1,16 @@
+ ------
+ Maven 2 Rar Plugin
+ ------
+ Stephane Nicoll
+ <snicoll@apache.org>
+ ------
+ September 25, 2005
+
+Introduction
+
+  This plugin generates Resource adapter archive (RAR) file.
+
+  The full description of goals is available {{{index.html}here}}.
+
+
+

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

@@ -0,0 +1,41 @@
+<?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 Rar Plugin">
+  <bannerLeft>
+    <name>Maven Rar 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"/>
+    </menu>
+    ${reports}
+  </body>
+</project>

maven-plugins/pom.xml

@@ -166,6 +166,7 @@
     <module>maven-pmd-plugin</module>
     <module>maven-projecthelp-plugin</module>
     <module>maven-project-info-reports-plugin</module>
+    <module>maven-rar-plugin</module>
     <module>maven-release-plugin</module>
     <module>maven-resources-plugin</module>
     <module>maven-site-plugin</module>