<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 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.
 */
 -->

<document>

  <properties>
    <title>Tags</title>
    <author email="michal.maczka@dimatics.com">Michal Maczka</author>
  </properties>

  <body>
    <section name="Overview">
      <p>
        This document describes the
        <a href="http://jakarta.apache.org/commons/jelly/tags.html">tags</a>
        that are available when using the Artifact Plug-in with Maven.
      </p>      
    </section>

    <section name="Tags">
      <table>
        <tr><th>Name</th><th>Description</th></tr>
        <tr>
          <td><a href="#artifact:deploy">artifact:deploy</a></td>
          <td>Deploy artifact to remote repository(ies)</td>
        </tr>
        <tr>
          <td><a href="#artifact:deploy-snapshot">artifact:deploy-snapshot</a></td>
          <td>Deploy snapshot version of artifact to remote repository</td>
        </tr>
        <tr>
          <td><a href="#artifact:install">artifact:install</a></td>
          <td>Install artifact in local repository</td>
        </tr>
        <tr>
          <td><a href="#artifact:deploy-snapshot">artifact:install-snapshot</a></td>
          <td>Install snapshot version of artifact in local repository</td>
        </tr>
      </table>
      
      <subsection name="artifact:deploy">
        <p>
          Deploy an artifact to the set of remote repositories.
          <br/>
          Following files will be deployed to remote repository:
           <ol>
              <li>Artifact file</li>
              <li>MD5 checksum file of this artifact</li>
           </ol>         
        </p>
        <table>
          <tr>
            <th>Attribute Name</th><th>Description</th><th>Optional?</th>
          </tr>
          <tr>
            <td>artifact</td>
            <td>The path to the artifact file</td>
            <td>No</td>
          </tr>
          <tr>
            <td>type</td>
            <td>The type of the artifact 
              (like <i>jar</i> or <i>war</i> or <i>plugin</i>). Type is used for
              computing a detination path in repository.            
            </td>
            <td>No</td>
          </tr>
          <tr>
            <td>project</td>
            <td>
               The project (POM) which produced artifact which will be deployed.
               <br/>
               The POM contains settings (variables and context properties) 
               that must be consulted in order to deploy artifact to a repository.
               These settings include:
               <ol> 
                  <li>List of remote repositories where artifact will be deployed</li>
                  <li>artifactId, groupId, version</li>
                  <li>Individual settings for each repository</li>
                  <li>Proxy server settings</li>
                  <li>...</li>
               </ol>
            </td>
            <td>NO</td>           
          </tr>
        </table>
      </subsection>
      
      <subsection name="artifact:deploy-snapshot">
        <p>
          Deploy a snapshot version of the artifact to a set of remote repositories.
          <br/>
          During deloyment following files are put to remote repository:
           <ul>
              <li>Timestamped Artifact file</li>
              <li>MD5 checksum file of timestamped artifact file</li>
              <li>Artifact file with version marked as <i>SNAPSHOT</i></li>
              <li>MD5 checksum file of this file</li>
              <li>${artifactId}-snapshot-version</li>
           </ul>
           For example for artifact with artifactId = <i>foo</i>
           the following files will be transferred to the remote repository:
           <ul>  
              <li>foo-20030620.124616.jar</li> 
              <li>foo-20030620.124616.jar.md5</li>
              <li>foo-SNAPSHOT.jar</li>
              <li>foo-SNAPSHOT.jar.md5</li>
              <li>foo-snapshot-version</li>          
           </ul>   
           
           File <i>foo-snapshot-version</i> 
           contains the version number (20030620.124616) 
           that the snapshot is linked to, 
           so that 
           <a href="http://maven.apache.org/reference/user-guide.html#Resolving SNAPSHOT Dependencies">'convert-snapshots'</a>
             can correctly update dependencies in projects that will use this artifact. 
           <br/>
           <b>artifact:deploy-snapshot</b> tag uses the same set of attributes 
           as <a href="artifact:deloy">artifact:deploy</a> tag                      
        </p>
      </subsection>
      <subsection name="artifact:install">
        <p>
          Install an artifact in the local repository
          <br/>
          Following files will be copied to the local repository:
           <ol>
              <li>Artifact file</li>
              <li>MD5 checksum file of this artifact</li>
           </ol>         
        </p>
        <p>
          <i>Why should I use <b>artifact:install</b> when it is so easy
          to copy a file inside my plugin?
          </i>
          <br/>
          There are few good reason for that:
           <ul>             
             <li>
                Although simple now, it will not necessarily remain that way 
				in the future.
                e.g. When Maven runs in client-server mode
                information about repository content can be cached
                and some files from the repository can be cached in memory
                (e.g. POMS). Using a centralized "proxy" which copies
                files to the repository can play important role in this
                process.               
             </li>
             <li>
               It is as simple to use as ant:copy task, but does not require
               usage of Ant.
             </li>
           </ul>
        </p>
        <table>
          <tr>
            <th>Attribute Name</th><th>Description</th><th>Optional?</th>
          </tr>
          <tr>
            <td>artifact</td>
            <td>The path to the artifact file</td>
            <td>No</td>
          </tr>
          <tr>
            <td>type</td>
            <td>The type of the artifact 
              (like <i>jar</i> or <i>war</i>). Type is used for
              computing a detination path in repository.            
            </td>
            <td>No</td>
          </tr>
          <tr>
            <td>project</td>
            <td>
                Information  kept in the POM included following bits
                used for controling:
                <ul>
                  <li>artifactId, groupId, version</li>
                  <li>Location of the local repository</li>
                </ul>
            </td>
            <td>NO</td>           
          </tr>
        </table>
      </subsection>
      
      <subsection name="artifact:install-snapshot">
        <p>
          Install a snapshot version of the artifact in the local repository
          <br/>
           Following files are copied to the local repository:
           <ul>
              <li>Timestamped Artifact file</li>
              <li>Artifact file with version marked as <i>SNAPSHOT</i></li>
           </ul>
           For exaple for artifact with artifactId foo
           following files will be transfered to local repository:
           <ul>  
              <li>foo-20030620.124616.jar</li> 
              <li>foo-SNAPSHOT.jar</li>      
           </ul>                         
           <br/>
           <b>artifact:install-snapshot</b> tag uses the same set of attributes 
           as <a href="#artifact:install">artifact:install</a> tag                      
        </p>
      </subsection>
    </section>
  </body>
</document>
