DPML Notify

[mcconnell at BerliOS <mcconnell AT mail.berlios.de>]

Author: mcconnell
Date: 2006-07-20 20:21:46 +0200 (Thu, 20 Jul 2006)
New Revision: 1620

Added:
   trunk/tutorials/tooling/simple/alias/
   trunk/tutorials/tooling/simple/alias/build.xml
   trunk/tutorials/tooling/simple/alias/index.xml
   trunk/tutorials/tooling/simple/alias/src/
   trunk/tutorials/tooling/simple/alias/src/main/
   trunk/tutorials/tooling/simple/alias/src/main/org/
   trunk/tutorials/tooling/simple/alias/src/main/org/acme/
   trunk/tutorials/tooling/simple/alias/src/main/org/acme/Demo.java
Modified:
   trunk/central/site/src/docs/depot/tutorials/simple/alias.xml
Log:
add alias tutorial

Modified: trunk/central/site/src/docs/depot/tutorials/simple/alias.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/simple/alias.xml        
2006-07-20 18:00:07 UTC (rev 1619)
+++ trunk/central/site/src/docs/depot/tutorials/simple/alias.xml        
2006-07-20 18:21:46 UTC (rev 1620)
@@ -10,102 +10,76 @@
 
     <section name="Using alias statements">
 
-        <p>
-        In our previouse example dealing with the creation of a module 
suitable
-        for external project reference - we have introduced an issue 
concerning
-        references SNAPSHOT versions.  One should keep in mind that it is 
bad practive
-        to reference SNAPSHOT versions and it is considered very bad 
practive 
-        to publish SNAPSHOT artifacts.
-        </p>
-        
-        <p>
-        A solution to this problem is to publish a platform independent 
symbolic link 
-        to the artifact (a.k.a. an alias).
-        </p>
-
+      <p>
+      In the previouse example we created a jar file and based on the 
standard
+      naming convensions the generated artifact was named 
<tt>demo-SNAPSHOT.jar</tt>.
+      This naming convension is based on the 
<tt>[name]-[VERSION].[TYPE]</tt> 
+      pattern.  In some situations we want to reference artifact using a 
logical version
+      (or no version).  This can be achived though the declaration of an 
alias under the 
+      type production element.
+      </p>
+      
       <subsection name="Adding an Alias">
 
         <p>
         To simplify local management of modules we can use the 
<tt>alias</tt> attribuite
-        on a type declaration.  This request the creation of a link which is 
an artifact
+        on a type declaration declaration.  This request the creation of a 
link which is an artifact
         that references another artifact.  The following example 
demonstrates the addition
-        of an <tt>alias</tt> attribute to the type production statement in 
our module 
-        definition.
+        of an <tt>alias</tt> attribute to the type production statement in 
demo project.
         </p>
 
 <source>
-&lt;library&gt;
+&lt;index xmlns="link:xsd:dpml/lang/dpml-module#1.0"&gt;
 
-  &lt;imports&gt;
-    &lt;import uri="link:module:ant"/&gt;
-  &lt;/imports&gt;
+  &lt;project name="demo" basedir="."&gt;
+    &lt;properties&gt;
+      &lt;property name="location" value="New York"/&gt;
+      &lt;property name="message" value="Hello from ${user.name} in 
${location}"/&gt;
+    &lt;/properties&gt;
+    &lt;types&gt;
+      <font color="darkred">&lt;type id="jar" alias="true"/&gt;</font>
+    &lt;/types&gt;
+    &lt;filters&gt;
+      &lt;filter token="MESSAGE" value="${message}"/&gt;
+    &lt;/filters&gt;
+  &lt;/project&gt;
 
-  &lt;modules&gt;
-
-    &lt;module name="acme" basedir="."&gt;
-
-      &lt;types&gt;
-        &lt;type id="module" <font color="darkred">alias="true"</font>/&gt;
-      &lt;/types&gt;
-
-      ...
-      
-    &lt;/module&gt;
-
-  &lt;/modules&gt;
-
-&lt;/library&gt;
+&lt;/index&gt;
 </source>
 
         <p>
-        After executing the module build you will find an artifact named 
-        <tt>acme.module.link</tt> in the <tt>target/deliverables/modules</tt>
-        directory.  The link datastructure can be referenced using Transit's 
-        link protocol as show in the following example import statement.
+        The alias attribute is recognized by the Depot antlib and will result
+        in the automatic production of an unversioned symbolic link (a.ka. 
alias).
+        The link definition is created in the target/deliverables/jars 
directly 
+        under the name <tt>demo.jar.link</tt>.  This file contains an 
artifact 
+        uri refernecing the real artifact.
         </p>
-
-<source>
-&lt;library&gt;
-
-  &lt;imports&gt;
-    &lt;import uri="<font color="darkred">link:module:acme</font>"/&gt;
-  &lt;/imports&gt;
-
-   &lt;modules&gt;
-
-    ...
-
-  &lt;/modules&gt;
-
-&lt;/library>
-</source>
-
+        
+        <p><i>Contents of 
<tt>${basedir}/target/deliverables/jars/demo.jar.link</tt></i></p>
+        
+<source>artifact:jar:demo#SNAPSHOT</source>
+        
       </subsection>
 
       <subsection name="Summary">
 
-
         <p>
         The link datastructure is simply a reference to a 
         versioned artifact (similar to a unix symlink for artifacts).  This 
tutorial
         has covered the creation of a simple non-versioned alias associated 
with the 
-        produced module definition. Alias attributes may be used on any 
resource type
-        production statement.  Also, an alternative form of versioned alias 
production
-        is available using the <tt>version</tt> attribute a value in place 
of <tt>alias</tt>.
+        produced jar file. Alias attributes may be used on any resource type
+        production statement.  An alternative form of versioned alias 
production
+        is available using the <tt>version</tt> attribute in place of 
<tt>alias</tt>.
         For example - the following statement would result in the generation 
of a alias
-        artifact associated with the version 1.0.
+        artifact referencing version 1.0.
         </p>
         
 <source>
-  &lt;types&gt;
-    &lt;type id="module" <font color="darkred">version="1.0"</font>/&gt;
-  &lt;/types&gt;
+&lt;types&gt;
+  &lt;type id="jar" <font color="darkred">version="1.0"</font>/&gt;
+&lt;/types&gt;
 </source>
 
-        <p>
-        Our next subject deals with <a href="versioned.html">versioned 
builds</a>.
-        </p>
-
       </subsection>
 
     </section>

Added: trunk/tutorials/tooling/simple/alias/build.xml
===================================================================
--- trunk/tutorials/tooling/simple/alias/build.xml      2006-07-20 18:00:07 
UTC (rev 1619)
+++ trunk/tutorials/tooling/simple/alias/build.xml      2006-07-20 18:21:46 
UTC (rev 1620)
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<project name="demo" default="install"
+    xmlns:transit="antlib:net.dpml.transit">
+
+  <transit:import uri="local:template:dpml/tools/standard"/>
+
+</project>

Added: trunk/tutorials/tooling/simple/alias/index.xml
===================================================================
--- trunk/tutorials/tooling/simple/alias/index.xml      2006-07-20 18:00:07 
UTC (rev 1619)
+++ trunk/tutorials/tooling/simple/alias/index.xml      2006-07-20 18:21:46 
UTC (rev 1620)
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<index xmlns="link:xsd:dpml/lang/dpml-module#1.0">
+
+  <project name="demo" basedir=".">
+    <properties>
+      <property name="location" value="New York"/>
+      <property name="message" value="Hello from ${user.name} in 
${location}"/>
+    </properties>
+    <types>
+      <type id="jar" alias="true"/>
+    </types>
+    <filters>
+      <filter token="MESSAGE" value="${message}"/>
+    </filters>
+  </project>
+
+</index>

Added: trunk/tutorials/tooling/simple/alias/src/main/org/acme/Demo.java
===================================================================
--- trunk/tutorials/tooling/simple/alias/src/main/org/acme/Demo.java    
2006-07-20 18:00:07 UTC (rev 1619)
+++ trunk/tutorials/tooling/simple/alias/src/main/org/acme/Demo.java    
2006-07-20 18:21:46 UTC (rev 1620)
@@ -0,0 +1,47 @@
+/*
+ * Copyright 2006 Stephen J. McConnell.
+ *
+ * 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.
+ */
+
+package org.acme;
+
+import java.util.logging.Logger;
+import java.util.logging.Level;
+
+/**
+ * A simple class.
+ * 
+ * @author <a href="@PUBLISHER-URL@">@PUBLISHER-NAME@</a>
+ * @version @PROJECT-VERSION@
+ */
+public class Demo
+{
+    //------------------------------------------------------------------
+    // constructor
+    //------------------------------------------------------------------
+    
+   /**
+    * Creation of a new demo instance.
+    */
+    public Demo()
+    {
+        Logger logger = Logger.getLogger( "demo" );
+        if( logger.isLoggable( Level.INFO ) )
+        {
+            logger.info( "@MESSAGE@" );
+        }
+    }
+}