<chapter id='java_plugin' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The Java Plugin</title>

    <para>The Java Plugin adds Java compilation, testing and bundling capabilities to a project. It serves as the basis
        for most of the other Gradle plugins.
    </para>
    
    <section>
        <title>Tasks</title>
        <para>The Java plugin adds the tasks shown in <xref linkend='javatasks'/> to a project.
            These tasks constitute a lifecycle for Java builds.
        </para>

        <table id='javatasks'>
            <title>Java plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>clean</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.Clean"/></td>
            </tr>
            <tr>
                <td>
                    <literal>processResources</literal>
                </td>
                <td>
                    <literal>-</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.Copy"/></td>
            </tr>
            <tr>
                <td>
                    <literal>compile</literal>
                </td>
                <td>
                    <literal>-</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.compile.Compile"/></td>
            </tr>
            <tr>
                <td>
                    <literal>processTestResources</literal>
                </td>
                <td>
                    <literal>-</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.Copy"/></td>
            </tr>
            <tr>
                <td>
                    <literal>compileTests</literal>
                </td>
                <td>
                    <literal>compile</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.compile.Compile"/></td>
            </tr>
            <tr>
                <td>
                    <literal>test</literal>
                </td>
                <td>
                    <literal>compile</literal>,
                    <literal>compileTests</literal>,
                    <literal>processResources</literal>,
                    <literal>processTestResources</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.testing.Test"/></td>
            </tr>
            <tr>
                <td>
                    <literal>javadoc</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.javadoc.Javadoc"/></td>
            </tr>
            <tr>
                <td>
                    <literal>jar</literal>
                </td>
                <td>
                    <literal>compile</literal>,
                    <literal>processResources</literal>,
                    <literal>test</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.bundling.Jar" lang="groovy"/></td>
            </tr>
            <tr>
                <td>
                    <literal>libs</literal>
                </td>
                <td>
                    All <literal>Jar</literal> and <literal>War</literal> tasks in the project.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
            </tr>
            <tr>
                <td>
                    <literal>dists</literal>
                </td>
                <td>
                    <literal>libs</literal> and all <literal>Zip</literal> and <literal>Tar</literal> tasks in the project.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
            </tr>
            <tr>
                <td>
                    <literal>build<replaceable>ConfigurationName</replaceable></literal>
                </td>
                <td>
                    The tasks which produce the artifacts in configuration <replaceable>ConfigurationName</replaceable>.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
            </tr>
            <tr>
                <td>
                    <literal>upload<replaceable>ConfigurationName</replaceable></literal>
                </td>
                <td>
                    The tasks which uploads the artifacts in configuration <replaceable>ConfigurationName</replaceable>.
                </td>
                <td><apilink class="org.gradle.api.tasks.Upload"/></td>
            </tr>
        </table>
    </section>

    <section>
        <title>Project layout</title>
        <para>The Java plugin assumes the project layout shown in <xref linkend='javalayout'/>. This is configurable
            using the convention properties listed in the next section.
        </para>

        <table id='javalayout'>
            <title>Java plugin - default project layout</title>
            <thead>
                <tr>
                    <td>Directory</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <filename>src/main/java</filename>
                </td>
                <td>Application/Library Java source</td>
            </tr>
            <tr>
                <td>
                    <filename>src/main/resources</filename>
                </td>
                <td>Application/Library resources</td>
            </tr>
            <tr>
                <td>
                    <filename>src/test/java</filename>
                </td>
                <td>Test Java source</td>
            </tr>
            <tr>
                <td>
                    <filename>src/test/resources</filename>
                </td>
                <td>Test resources</td>
            </tr>
        </table>

    </section>

    <section id="sec:java_plugin_and_dependency_management">
        <title>Dependency management</title>
        <para>The Java plugin adds a number of dependency configurations to your project, as shown in
            <xref linkend="tab:configurations"/>. It assigns those configurations to tasks such as
            <literal>compile</literal> and <literal>test</literal>.
            To learn more about configurations see <xref linkend="sub:configurations"/> and
            <xref linkend="artifacts_and_configurations"/>
        </para>
        <table id='tab:configurations'>
            <title>Java plugin - dependency configurations</title>
            <thead>
                <tr>
                    <td>Name</td>
                    <td>Extends</td>
                    <td>Used by tasks</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>compile</td>
                <td>-</td>
                <td>compile</td>
                <td>Compile time dependencies</td>
            </tr>
            <tr>
                <td>runtime</td>
                <td>compile</td>
                <td>-</td>
                <td>Runtime dependencies</td>
            </tr>
            <tr>
                <td>testCompile</td>
                <td>compile</td>
                <td>compileTests</td>
                <td>Additional dependencies for compiling tests.</td>
            </tr>
            <tr>
                <td>testRuntime</td>
                <td>runtime, testCompile</td>
                <td>test</td>
                <td>Additional dependencies for running tests only.</td>
            </tr>
            <tr>
                <td>archives</td>
                <td>-</td>
                <td>uploadArchives</td>
                <td>Artifacts (e.g. jars) produced by this project.</td>
            </tr>
            <tr>
                <td>default</td>
                <td>runtime, archives</td>
                <td>-</td>
                <td>Artifacts produced <literal>and</literal> dependencies required by this project.
                </td>
            </tr>
        </table>
    </section>

    <section>
        <title>Convention properties</title>
        <para>
            The Java plugin adds the convention properties shown in <xref linkend='javaconventionDir'/> and
            <xref linkend='javaconventionNonDir'/>.
            <footnote>
                <para>The <emphasis>buildDir</emphasis> property is a property of the project object. It defaults to
                    <literal>build</literal>.
                </para>
            </footnote>
            Gradle's conventions contain a convention for the directory hierarchy as well as conventions for the element
            names of the hierarchy. For example the <literal>srcDirs</literal> are relative to the
            <literal>srcRoot</literal>. Therefore <literal>srcDirs</literal> is a read-only property. If you want to
            change the name of the source dirs you need to do this via the <literal>srcDirNames</literal> property. But
            the paths you specify here are <emphasis>relative</emphasis> to the <literal>srcRoot</literal>. This has the
            advantage to make bulk changes easy. If you change <literal>srcRoot</literal> from <literal>src</literal>
            to <literal>source</literal>, this automatically applies to all directory properties which are relative to
            <literal>srcRoot</literal>. As this also introduces an inflexibility, we have additional floating dirs,
            which are not bound to any hierarchy (see <xref linkend='javaconventionFloatingDir'/>). For example code
            generation tool could make use of this, by adding a source dir which is located in the build folder.
        </para>

        <table id='javaconventionDir'>
            <title>Java plugin - directory properties</title>
            <thead>
                <tr>
                    <td>Directory Name Property</td>
                    <td>Directory File Property</td>
                    <td>Default Name</td>
                    <td>Default File</td>
                </tr>
            </thead>
            <tr>
                <td>srcRootName</td>
                <td>srcRoot</td>
                <td>
                    <literal>src</literal>
                </td>
                <td>
                    <literal><replaceable>projectDir</replaceable>/src</literal>
                </td>
            </tr>
            <tr>
                <td>srcDirNames</td>
                <td>srcDirs</td>
                <td>
                    [<literal>main/java</literal>]
                </td>
                <td>
                    [<literal><replaceable>srcRoot</replaceable>/main/java</literal>]
                </td>
            </tr>
            <tr>
                <td>resourceDirNames</td>
                <td>resourceDirs</td>
                <td>
                    [<literal>main/resources</literal>]
                </td>
                <td>
                    [<literal><replaceable>srcRoot</replaceable>/main/resources</literal>]
                </td>
            </tr>
            <tr>
                <td>testSrcDirNames</td>
                <td>testSrcDirs</td>
                <td>
                    [<literal>test/java</literal>]
                </td>
                <td>
                    [<literal><replaceable>srcRoot</replaceable>/test/java</literal>]
                </td>
            </tr>
            <tr>
                <td>testResourceDirNames</td>
                <td>testResourceDirs</td>
                <td>
                    <literal>test/resources</literal>
                </td>
                <td>
                    [<literal><replaceable>srcRoot</replaceable>/test/resources</literal>]
                </td>
            </tr>
            <tr>
                <td>classesDirName</td>
                <td>classesDir</td>
                <td>
                    <literal>classes</literal>
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/classes</literal>
                </td>
            </tr>
            <tr>
                <td>testClassesDirName</td>
                <td>testClassesDir</td>
                <td>
                    <literal>test-classes</literal>
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/test-classes</literal>
                </td>
            </tr>
            <tr>
                <td>testResultsDirName</td>
                <td>testResultsDir</td>
                <td>
                    <literal>test-results</literal>
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/test-results</literal>
                </td>
            </tr>
            <tr>
                <td>testReportDirName</td>
                <td>testReportDir</td>
                <td>
                    <literal>tests</literal>
                </td>
                <td>
                    <literal><replaceable>reportsDir</replaceable>/test</literal>
                </td>
            </tr>
            <tr>
                <td>libsDirName</td>
                <td>libsDir</td>
                <td>
                    <literal>libs</literal>
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/libs</literal>
                </td>
            </tr>
            <tr>
                <td>distsDirName</td>
                <td>distsDir</td>
                <td>
                    <literal>dists</literal>
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/dists</literal>
                </td>
            </tr>
            <tr>
                <td>docsDirName</td>
                <td>docsDir</td>
                <td>
                    <literal>docs</literal>
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/docs</literal>
                </td>
            </tr>
            <tr>
                <td>javadocDirName</td>
                <td>javadocDir</td>
                <td>
                    <literal>javadoc</literal>
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/javadoc</literal>
                </td>
            </tr>
            <xi:include href="reportingBasePluginProperties.xml"/>
        </table>

        <table id='javaconventionFloatingDir'>
            <title>Java plugin - floating directory properties</title>
            <thead>
                <tr>
                    <td>Property</td>
                    <td>Type</td>
                    <td>Default Value</td>
                </tr>
            </thead>
            <tr>
                <td>floatingSrcDirs</td>
                <td>List</td>
                <td>empty</td>
            </tr>
            <tr>
                <td>floatingResourceDirs</td>
                <td>List</td>
                <td>empty</td>
            </tr>
            <tr>
                <td>floatingTestSrcDirs</td>
                <td>List</td>
                <td>empty</td>
            </tr>
            <tr>
                <td>floatingTestResourceDirs</td>
                <td>List</td>
                <td>empty</td>
            </tr>
        </table>

        <table id='javaconventionNonDir'>
            <title>Java plugin - other properties</title>
            <thead>
                <tr>
                    <td>Property</td>
                    <td>Type</td>
                    <td>Default Value</td>
                </tr>
            </thead>
            <tr>
                <td>sourceCompatibility</td>
                <td><apilink class="org.gradle.api.JavaVersion"/>. Can also set using a String or a Number, eg
                    <literal>'1.5'</literal> or <literal>1.5</literal>.
                </td>
                <td>
                    <literal>1.5</literal>
                </td>
            </tr>
            <tr>
                <td>targetCompatibility</td>
                <td><apilink class="org.gradle.api.JavaVersion"/>. Can also set using a String or Number, eg
                    <literal>'1.5'</literal> or <literal>1.5</literal>.
                </td>
                <td>
                    <literal><replaceable>sourceCompatibility</replaceable></literal>
                </td>
            </tr>
            <tr>
                <td>archivesBaseName</td>
                <td>String</td>
                <td><literal><replaceable>projectName</replaceable></literal></td>
            </tr>
            <tr>
                <td>manifest</td>
                <td><apilink class="org.gradle.api.tasks.bundling.GradleManifest" lang="groovy"/></td>
                <td>empty</td>
            </tr>
            <tr>
                <td>metaInf</td>
                <td>List</td>
                <td>empty</td>
            </tr>
        </table>

    </section>

    <section id='sec:javadoc'>
        <title>Javadoc</title>
        <para>The
            <literal>javadoc</literal>
            task has no default association with any other task. It has no prerequisites on the actions of other tasks,
            as it operates on the source. We support the core javadoc options and the options of the standard doclet
            described in the <ulink url='http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#referenceguide'>reference documentation</ulink>
            of the Javadoc executable.
        </para>
        <para>
            For some of the Javadoc options we provide defaults these defaults are only used when they are not set explicitly.
            Except for the sourcepath and classpath option for these options you can in addition to setting your custom values
            also make it so that the defaults get appended to these paths with the (alwaysAppendDefaultSourcepath and
            alwaysAppendDefaultClasspath toggles).
        </para>
        <table>
            <title>Javadoc options</title>
            <thead>
                <tr>
                    <td>Javadoc option</td>
                    <td>Default value</td>
                    <td>When is the default used</td>
                </tr>
            </thead>
            <tr>
                <td>destination directory</td>
                <td>[javadocDir]</td>
                <td>When the destination directory is not set explicitly</td>
            </tr>
            <tr>
                <td>sourcepath</td>
                <td>The java or groovy source directories</td>
                <td>When the sourcepath is empty or when you set the alwaysAppendDefaultSourcepath to true</td>
            </tr>
            <tr>
                <td>classpath</td>
                <td>The dependencies from the compile configuration + the classesDir</td>
                <td>When the classpath is empty or when you set the alwaysAppendDefaultClasspath to true</td>
            </tr>
            <tr>
                <td>windowTitle</td>
                <td>project name + version</td>
                <td>When the window title is not set explicitly</td>
            </tr>
            <tr>
                <td>subPackages</td>
                <td>All first level sub directories in the srcDirs</td>
                <td>When the following options are all empty: packageNames, sourceNames and subPackages</td>
            </tr>
        </table>
        <para>
            For a complete list of supported Javadoc options consult the API documentation of the following classes:
            <apilink class="org.gradle.external.javadoc.CoreJavadocOptions"/> and <apilink class="org.gradle.external.javadoc.StandardJavadocDocletOptions"/>. 
        </para>
        <table>
            <title>Java plugin - Javadoc properties</title>
            <thead>
                <tr>
                    <td>Task Property</td>
                    <td>Convention Property</td>
                </tr>
            </thead>
            <tr>
                <td>srcDirs</td>
                <td>srcDirs</td>
            </tr>
            <tr>
                <td>classesDir</td>
                <td>classesDir</td>
            </tr>
            <tr>
                <td>destinationDir</td>
                <td>[javadocDir]</td>
            </tr>

        </table>
    </section>

    <section id='sec:clean'>
        <title>Clean</title>
        <para>The
            <literal>clean</literal>
            task simply removes the directory denoted by its
            <literal>dir</literal>
            property. This property is mapped to the
            <literal>buildDir</literal>
            property of the project. In future releases there will be more control of what gets deleted. If you need
            more control now, you can use the <emphasis>Ant delete task</emphasis>.
        </para>
    </section>

    <section id='sec:resources'>
        <title>Resources</title>
        <para>Gradle uses the
            <emphasis>Copy</emphasis>
            task for resource handling. It has two instances,
            <literal>processResources</literal>
            and <literal>processTestResources</literal>.
        </para>
        <table>
            <title>Java plugin - processResource properties</title>
            <thead>
                <tr>
                    <td>Task Instance</td>
                    <td>Task Property</td>
                    <td>Convention Property</td>
                </tr>
            </thead>
            <tr>
                <td>processResources</td>
                <td>sourceDirs</td>
                <td>resourceDirs</td>
            </tr>
            <tr>
                <td>processResources</td>
                <td>destinationDir</td>
                <td>classesDir</td>
            </tr>
            <tr>
                <td>processTestResources</td>
                <td>sourceDirs</td>
                <td>testResourceDirs</td>
            </tr>
            <tr>
                <td>processTestResources</td>
                <td>destinationDir</td>
                <td>testClassesDir</td>
            </tr>

        </table>
        <para>The
            <literal>processResources</literal>
            task offers include and exclude directives as well as filters. Have a look at
            <apilink class="org.gradle.api.tasks.Copy"/> to learn about the details.
        </para>
    </section>

    <section id='sec:compile'>
        <title>Compile</title>
        <para>The
            <emphasis>Compile</emphasis>
            task has two instances,
            <literal>compile</literal>
            and <literal>compileTests</literal>.
        </para>
        <table>
            <title>Java plugin - compile properties</title>
            <thead>
                <tr>
                    <td>Task Instance</td>
                    <td>Task Property</td>
                    <td>Convention Property</td>
                </tr>
            </thead>
            <tr>
                <td>compile</td>
                <td>srcDirs</td>
                <td>srcDirs</td>
            </tr>
            <tr>
                <td>compile</td>
                <td>destinationDir</td>
                <td>classesDir</td>
            </tr>
            <tr>
                <td>compile</td>
                <td>sourceCompatibility</td>
                <td>sourceCompatibility</td>
            </tr>
            <tr>
                <td>compile</td>
                <td>targetCompatibility</td>
                <td>targetCompatibility</td>
            </tr>
            <tr>
                <td>compileTests</td>
                <td>srcDirs</td>
                <td>testSrcDirs</td>
            </tr>
            <tr>
                <td>compileTests</td>
                <td>destinationDir</td>
                <td>testClassesDir</td>
            </tr>
            <tr>
                <td>compileTests</td>
                <td>sourceCompatibility</td>
                <td>sourceCompatibility</td>
            </tr>
            <tr>
                <td>compileTests</td>
                <td>targetCompatibility</td>
                <td>targetCompatibility</td>
            </tr>

        </table>
        <para>Have a look at <apilink class="org.gradle.api.tasks.compile.Compile"/>
            to learn about the details. The compile task delegates to Ant's javac task to do the compile. You can set most
            of the properties of the Ant javac task.
        </para>
    </section>

    <section id='sec:java_test'>
        <title>Test</title>
        <para>The
            <literal>test</literal>
            task executes the unit tests which have been compiled by the
            <literal>compileTests</literal>
            task.
        </para>
        <table>
            <title>Java plugin - test properties</title>
            <thead>
                <tr>
                    <td>Task Property</td>
                    <td>Convention Property</td>
                </tr>
            </thead>
            <tr>
                <td>testClassesDir</td>
                <td>testClassesDir</td>
            </tr>
            <tr>
                <td>testResultsDir</td>
                <td>testResultsDir</td>
            </tr>
            <tr>
                <td>unmanagedClasspath</td>
                <td>[classesDir]</td>
            </tr>

        </table>
        <para>Have a look at <apilink class="org.gradle.api.tasks.testing.Test"/>
            for its complete API. Right now the test results are always in XML-format. The task has a
            <literal>stopAtFailuresOrErrors</literal>
            property to control the behavior when tests are failing. Test
            <emphasis>always</emphasis>
            executes all tests. It stops the build afterwards if
            <literal>stopAtFailuresOrErrors</literal>
            is true and there are failing tests or tests that have thrown an uncaught exception.
        </para>
        <para>Per default the tests are run in a forked JVM and the fork is done per test. You can modify this behavior
            by setting forking to false or set the forkmode to once.
        </para>
        <para>The Test task detects which classes are test classes by inspecting the compiled test classes.
            By default it scans all <emphasis>.class</emphasis> files. You can set custom includes / excludes, only those
            classes will be scanned. Depending on the Test framework used (JUnit / TestNG) the test class detection uses different criteria.
        </para>
        <para>
            When using JUnit, we scan for both JUnit 3 and 4 test classes. If any of the following criteria match, the
            class is considered to be a JUnit test class. Extend TestCase or GroovyTestCase, Class annotated with RunWith or
            contain a method annotated with Test (inherited test methods are detected).
        </para>
        <para>
            When using TestNG, we scan for methods annotated with Test (inherited test methods are detected).
        </para>
        <para>
            Since 0.6.1 we scan up the inheritance tree into jar files on the test classpath.
        </para>
        <para>
            In case you don't want to use the test class detection, you can disable it by setting scanForTestClasses to false.
            This will make the test task only use the includes / excludes to find test classes.

            If <code>scanForTestClasses</code> is disabled and no include or exclude patterns are specified, the
            respective defaults are used. For include this is <literal>"**/*Tests.class", "**/*Test.class"</literal>
            and the for exclude it is <literal>"**/Abstract*.class"</literal>.
        </para>
        <para>Both JUnit and TestNG are supported through their Ant tasks.</para>
    </section>

    <section>
        <title>Jar</title>
        <para>The <literal>jar</literal> task creates a JAR file containing the class files and resources of the
            project. The JAR file is declared as an artifact in the <literal>archives</literal> dependency
            configuration. This means that the JAR is available in the classpath of a dependent project. If you upload
            your project into a repository, this JAR is declared as part of the dependency descriptor. To learn
            more about how to work with archives and artifact configurations see <xref linkend="artifact_management"/>.
        </para>
    </section>

    <section>
        <title>Adding archives</title>
        <para>If you come from Maven you can have only one library JAR per project. With Gradle you can have as many as
            you want. You can also add WAR, ZIP and TAR archives to your project. They are all added the same way, so
            let's look at how you add a ZIP file.
        </para>
        <sample id="zip" dir="userguide/tutorial/zipProject" title="Creation of ZIP archive">
            <sourcefile file="build.gradle"/>
            <output args="-q myZip"/>
        </sample>
        <para>This adds a Zip archive task with the name <literal>myZip</literal> which produces ZIP file
            <filename>zipProject-1.0.zip</filename>. It is important to distinguish between the name of the archive task
            and the name of the archive generated by the archive task. The name of the generated archive file is by
            default the name of the project with the project version appended. The default name for archives can be
            changed with the <literal>archivesBaseName</literal> project property. The name of the archive can also be
            changed at any time later on.</para>
        <para>There are a number of properties which you can set on an archive task. You can, for example, change the
            name of the archive:
        </para>
        <sample id="zipWithCustomName" dir="userguide/tutorial/zipWithCustomName" title="Configuration of archive task - custom archive name">
            <sourcefile file="build.gradle"/>
            <output args="-q myZip"/>
        </sample>
        <para>You can further customize the archive names:</para>
        <sample id="zipWithArguments" dir="userguide/tutorial/zipWithArguments" title="Configuration of archive task - appendix &amp; classifier">
            <sourcefile file="build.gradle"/>
            <output args="-q myZip"/>
        </sample>
        <para>Often you will want to publish an archive, so that it is usable from another project. This process is
            described in <xref linkend="artifact_management"/>
        </para>

    <section id='sec:archive_tasks'>
        <title>Archive tasks</title>
        <para>An archive task is a task which produces an archive at execution time. The following archive tasks are
            available:
        </para>
        <table>
            <title>Archive tasks</title>
            <thead>
                <tr>
                    <td>Type</td>
                    <td>Accepted file container</td>
                    <td>Extends</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Zip" lang="groovy"/>
                </td>
                <td>fileSet, fileCollection, zipFileSet</td>
                <td>AbstractArchiveTask</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Tar" lang="groovy"/>
                </td>
                <td>fileSet, fileCollection, zipFileSet, tarFileSet</td>
                <td>Zip</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Jar" lang="groovy"/>
                </td>
                <td>fileSet, fileCollection, zipFileSet</td>
                <td>Zip</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.War" lang="groovy"/>
                </td>
                <td>fileSet, fileCollection, zipFileSet</td>
                <td>Jar</td>
            </tr>

        </table>
        <para>The following file containers are available:
        </para>
        <table id='filecontainer'>
            <title>File container for archives</title>
            <thead>
                <tr>
                    <td>Type</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.util.FileSet" lang="groovy"/>
                </td>
                <td>A set of files defined by a common baseDir and include/exclude patterns.</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.util.ZipFileSet" lang="groovy"/>
                </td>
                <td>Extends FileSet with additional properties known from Ant's zipfileset task.</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.util.TarFileSet" lang="groovy"/>
                </td>
                <td>Extends ZipFileSet with additional properties known from Ant's tarfileset task.</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.artifacts.FileCollection"/>
                </td>
                <td>An arbitrary collection of files to include in the archive. In contrast to a
                    <literal>FileSet</literal> they don't need to have a common basedir. There are a number of ways
                    of creating a <literal>FileCollection</literal>. For example, the <literal>Configuration</literal>
                    objects of a project implement <literal>FileCollection</literal>. You can also obtain a
                    <literal>FileCollection</literal> using the <literal>Project.files()</literal> method.
                </td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.util.AntDirective" lang="groovy"/>
                </td>
                <td>An arbitrary Ant resource declaration.</td>
            </tr>

        </table>
        <para>To learn about all the details have a look at the javadoc of the archive task class or the file container
            class itself.
        </para>
        <section id='sub:common_properties'>
            <title>Common properties</title>
            <para>The name of the generated archive is assembled from the task properties <literal>baseName</literal>,
                <literal>appendix</literal>, <literal>version</literal>, <literal>classifier</literal> and
                <literal>extension</literal> into
                <literal><replaceable>baseName</replaceable>-<replaceable>appendix</replaceable>-<replaceable>version</replaceable>-<replaceable>classifier</replaceable>.<replaceable>extension</replaceable></literal>.
                <footnote>
                    <para>If any of these properties is empty the trailing <literal>-</literal> is not added to the name.
                    </para>
                </footnote>
                The assembled name is accessible via the <literal>archiveName</literal> property. The
                <literal>name</literal> property denotes the name of the task, not the generated archive. An archive
                task has also a <literal>customName</literal> property. If this property is set, the
                <literal>archiveName</literal> property returns its value instead of assembling a name out of the
                properties mentioned above.
            </para>
            <para>Archives have a <literal>destinationDir</literal> property to specify where the generated archive
                should be placed. It has also an <literal>archivePath</literal> property, which returns a File object
                with the absolute path of the generated archive.
            </para>
        </section>
        <section id='sub:adding_content'>
            <title>Adding content</title>
            <para>To add content to an archive you must add file container to an archive (see
                <xref linkend='filecontainer'/>). You can add as many file containers as you like. They behave pretty much
                the same as the Ant resources with similar names.
            </para>
            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - include &amp; exclude">
                <sourcefile file="build.gradle" snippet="file-set"/>
            </sample>
            <para>You can add arbitrary files to an archive:
            </para>
            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - arbitrary files">
                <sourcefile file="build.gradle" snippet="files"/>
            </sample>
            <para>Other examples:
            </para>
            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - zipFileSet">
                <sourcefile file="build.gradle" snippet="zip-file-set"/>
            </sample>
            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Creation of TAR archive">
                <sourcefile file="build.gradle" snippet="tar-file-set"/>
            </sample>
            <para>There is also the option to add an arbitrary Ant expression describing an Ant resource.
            </para>
            <programlisting><![CDATA[
myZipTask.antDirective {        
   zipgroupfileset(dir: new File(rootDir, 'lib'))    
}
]]></programlisting>
            <para>This is for rather exotic use cases. Usually you should be fine with the file container provided by
                Gradle.
            </para>
        </section>
        <section id='sub:merging'>
            <title>Merging</title>
            <para>If you want to merge the content of other archives into the archive to be generated Gradle offers you
                two methods. One is <literal>merge</literal>:
            </para>
            <programlisting><![CDATA[
myZipTask.merge('path1/otherArchive1.zip', 'path2/otherArchive.tar.gz')
]]></programlisting>
            <para>This merges the whole content of the archive passed to the merge method into the generated archive. If
                you need more control which content of the archive should be merged and to what path, you can pass a
                closure to the merge method:
            </para>
            <programlisting><![CDATA[
myZipTask.merge('path1/otherArchive1.zip', 'path2/otherArchive.tar.gz') {
	include('**/*.txt')
	exclude('**/*.gif')
	prefix = 'myprefix'
}
]]></programlisting>
            <para>Under the hood Gradle scans the extension of the archives to be merged. According to the extension, it
                creates a
                <literal>ZipFileSet</literal>
                or <literal>TarFileSet</literal>. The closure is applied to this newly created file container. There
                is another method for merging called <literal>mergeGroup</literal>.
            </para>
            <programlisting><![CDATA[
myZipTask.mergeGroup('path_to_dir_with_archives') {
	include('**/*.zip')
	exclude('**/*.tar.gz')
}
]]></programlisting>
            <para>With this method you can assign a set of archives to be merged. Those archives have to be located
                under the directory you pass as an argument. You can define filters what archives should be included.
                They are always included fully and you can't specify a path. If you need this features, you must use the
                <literal>merge</literal> method.
            </para>
        </section>
        <section id='sub:manifest'>
            <title>Manifest</title>
            <para>The convention object of the Java Plugin has a <literal>manifest</literal>
                property pointing to an instance of <apilink class="org.gradle.api.tasks.bundling.GradleManifest" lang="groovy"/>.
                With this <classname>GradleManifest</classname> object you can define the content of the
                <filename>MANIFEST.MF</filename> file for all the jar or a war archives in your project.
            </para>
            <sample id="manifest" dir="userguide/tutorial/manifest" title="Customization of MANIFEST.MF">
                <sourcefile file="build.gradle" snippet="main-attributes"/>
            </sample>
            <para>You can also define sections of a manifest file.
            </para>
            <para>If a particular archive needs unique entries in its manifest you have to create your own
                <classname>GradleManifest</classname> instance for it.
            </para>
            <sample id="manifest" dir="userguide/tutorial/manifest" title="Customization of MANIFEST.MF for a particular archive">
                <sourcefile file="build.gradle" snippet="custom-manifest"/>
            </sample>
            <para>Passing the common manifest object to the constructor of <classname>GradleManifest</classname>
                add the common manifest values to the task specific manifest instance.
            </para>
        </section>
        <section id='sub:metainf'>
            <title>MetaInf</title>
            <para>The convention object of the Java Plugin has a <literal>metaInf</literal> property pointing to a list of
                <classname>FileSet</classname> objects. With these file sets you can define which files should be in the
                <filename>META-INF</filename> directory of a JAR or a WAR archive.
            </para>
            <programlisting><![CDATA[
metaInf << new FileSet(someDir)
]]></programlisting>
        </section>
    </section>
    </section>

    <section id='sec:upload'>
        <title>Uploading</title>
        <para>How to upload your archives is described in <xref linkend="artifact_management"/>.
        </para>
    </section>
    
    <section id='sec:eclipse'>
        <title>Eclipse</title>
        <para>Gradle comes with a number of tasks for generating eclipse files for your projects.
        </para>
        <section id='sub:eclipse_classpath'>
            <title>Eclipse classpath</title>
            <para>
                <apilink class="org.gradle.api.tasks.ide.eclipse.EclipseClasspath"/>
                has a default instance with the name <literal>eclipseCp</literal>. It generates a
                <literal>.classpath</literal> file.
            </para>
            <table>
                <title>Java plugin - Eclipse properties</title>
                <thead>
                    <tr>
                        <td>Task Property</td>
                        <td>Convention Property</td>
                    </tr>
                </thead>
                <tr>
                    <td>srcDirs</td>
                    <td>srcDirs + resourcesDirs</td>
                </tr>
                <tr>
                    <td>testSrcDirs</td>
                    <td>testSrcDirs + testResourcesDirs</td>
                </tr>
                <tr>
                    <td>outputDirectory</td>
                    <td>classesDir</td>
                </tr>
                <tr>
                    <td>testOutputDirectory</td>
                    <td>testClassesDir</td>
                </tr>
                <tr>
                    <td>classpathLibs</td>
                    <td>the resolve result for
                        <literal>testRuntime</literal>
                    </td>
                </tr>

            </table>
        </section>
        <section id='sub:eclipse_project'>
            <title>Eclipse project</title>
            <para>
                <apilink class="org.gradle.api.tasks.ide.eclipse.EclipseProject"/>
                has a default instance with the name <literal>eclipseProject</literal>. It generates a
                <literal>.project</literal> file.
            </para>
            <table>
                <title>Java plugin - Eclipse project properties</title>
                <thead>
                    <tr>
                        <td>Task Property</td>
                        <td>Convention Property</td>
                    </tr>
                </thead>
                <tr>
                    <td>name</td>
                    <td>project.name</td>
                </tr>
                <tr>
                    <td>projectType</td>
                    <td>ProjectType.JAVA</td>
                </tr>

            </table>
            <para>The java plugin also provides a task called
                <literal>eclipse</literal>
                which generates both of the eclipse tasks mentioned above. If you are using the war plugin,
                <literal>eclipse</literal>
                also leads to the execution of the
                <literal>eclipseWtp</literal>
                task.
            </para>
        </section>
    </section>
</chapter>
