<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
    <name>grobo-rezip: GroboCoverage Ant Tasks</name>
    <doc-version>$Date: 2004/05/13 00:15:47 $</doc-version>
    <author>Matt Albrecht</author>
</head>
<body>

<P>
<link name="v2_antdoc">All Tasks</link>
</P>

<anttask name="grobo-rezip">
    <description>
    Alters zip and zip-like files to contain new files.  Also, alters
    zips within zips.  Used for modifying deployment archives (such as EAR
    files) to include coverage-compiled classes and the GroboCoverage
    runtime library.
    <P>
    The task is really a container for many alteration sub-tasks.  Each
    top-level sub-task takes a source, and outputs a destination to
    a file.  They may each have their own alteration sub-tasks, but these
    will output the altered zip file to the owning sub-task's zip file.
    </P>
    </description>
    <ant-nested-element name="alterZip">
        <description>
        The primary alteration sub-task.  All other
        alter sub-tasks are based on this one, and so have the same
        attributes and nested elements as this one (plus a few more).
        <P>
        All alter sub-tasks can include other alter sub-tasks inside them.
        This means that a zip file inside another zip file will be
        altered.
        </P>
        </description>
        <ant-nested-element name="fileset">
            <description>
            <EM>(aliased as <code>zipfileset</code>)</EM>
            the <ant-link href="CoreTypes/zipfileset.html">ZipFileSet</ant-link>
            to define new entries to put into the modified zip file.
            This will overwrite any existing file in the modified zip file
            with the same name and path.
            </description>
            <ant-parameter>
                <attribute>replaceOnly</attribute>
                <description>If set to "true", then only the files in this
                fileset that are already in the original zip file will
                be included.  Default is "false".  Useful for including
                covered classes that are in the original, but no others.
                </description>
                <required>No</required>
            </ant-parameter>
        </ant-nested-element>
        <ant-parameter>
            <attribute>src</attribute>
            <description>For top-level alter sub-tasks, this refers to
            the location of the original source zip file.  For inner alter
            sub-tasks, this refers to the zip file location inside the owning
            zip file's directory structure.</description>
            <required>Yes</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>dest</attribute>
            <description>For top-level alter sub-tasks, this refers to the
            output location of the modified zip file; this defaults to the
            <code>src</code> parameter, overwriting the original.
            This isn't used for inner alter sub-tasks.</description>
            <required>No</required>
        </ant-parameter>
    </ant-nested-element>
    <ant-nested-element name="alterWar">
        <description>
        A variation of the <code>alterZip</code> sub-task, designed for
        use with <code>.war</code> files.
        <P>
        It has the same parameters and nested elements as <code>alterZip</code>,
        except for:
        </P>
        </description>
        <ant-nested-element name="classes">
            <description>
            A short-hand for a
            <ant-link href="CoreTypes/zipfileset.html">ZipFileSet</ant-link>
            that presets the path prefix to <code>WEB-INF/classes/</code>.
            By default, the "replaceOnly" attribute is set to "true", but this
            can be altered.
            </description>
        </ant-nested-element>
        <ant-nested-element name="lib">
            <description>
            A short-hand for a
            <ant-link href="CoreTypes/zipfileset.html">ZipFileSet</ant-link>
            that presets the path prefix to <code>WEB-INF/lib/</code>.
            </description>
        </ant-nested-element>
    </ant-nested-element>
    <ant-nested-element name="alterJar">
        <description>
        A variation of the <code>alterZip</code> sub-task, designed for
        use with <code>.jar</code> files.
        <P>
        Currently, there is no difference between this nested element
        and the <code>alterZip</code> element.  Eventually,
        <code>alterJar</code> will allow for modifications to the
        <code>META-INF/MANIFEST.MF</code> file (for jobs such as
        appending to the classpath list, and so on).
        </P>
        </description>
    </ant-nested-element>
    <ant-nested-element name="alterEar">
        <description>
        A variation of the <code>alterZip</code> sub-task, designed for
        use with <code>.ear</code> files.
        <P>
        Currently, there is no difference between this nested element
        and the <code>alterZip</code> element.  Eventually,
        <code>alterEar</code> will allow for modifications to the
        <code>application.xml</code> file (for jobs such as
        appending to the classpath list, and so on).
        </P>
        </description>
    </ant-nested-element>

    <ant-example>
        <source>
&lt;grobo-rezip&gt;
    &lt;alterEar src="${outdir}/myapp.ear"&gt;
        &lt;alterWar src="web1.war"&gt;
            &lt;lib file="${3rdparty}/GroboCoverage-1.1.0-runtime.jar" /&gt;
            &lt;classes dir="${coverage.classes}" /&gt;
            
            &lt;alterJar src="WEB-INF/lib/myfiles.jar"&gt;
                &lt;fileset dir="${coverage.classes}"&gt;
                    &lt;includes name="com/my/files/**" /&gt;
                &lt;/fileset&gt;
            &lt;/alterJar&gt;
        &lt;/alterWar&gt;
        
        &lt;fileset file="${testdir}/9cactus.war" /&gt;
    &lt;/alterEar&gt;
&lt;/grobo-rezip&gt;
        </source>
        <description>
        This task alters the contents of <code>${outdir}/myapp.ear</code>,
        and replaces the original when complete.
        <p>
        The contents of the <code>.ear</code> file remain the same, except
        for <code>web1.war</code>, which gets modified, and a new file,
        <code>9cactus.war</code>, gets added to the root of the EAR
        directory structure.
        </p>
        <p>
        <code>web1.war</code> gets modified to reference the code-coverage
        enabled files.  The contents remain the same, except for the
        following:
        <ul>
            <li>
            the required runtime library for GroboCoverage coverage-enabled
            class files gets included in the WAR file lib directory structure;
            </li>
            <li>
            the coverage-enabled class files replace the originals, but any
            original class file not coverage-enabled will remain in place
            (since the non-coverage-enabled files do not exist in
            <code>${coverage.classes}</code>);
            </li>
            <li>
            the inner jar file, <code>WEB-INF/lib/myfiles.jar</code>
            gets modified, by replacing the <code>com.my.files</code>
            package and sub-package classes with the coverage-enabled
            versions.
            </li>
        </ul>
        </p>
        </description>
    </ant-example>
    
</anttask>

<P>
<link name="v2_antdoc">All Tasks</link>
</P>

</body>
</document>

