From 2b78519c603439d946086722aaa378c598ed4dcd Mon Sep 17 00:00:00 2001
From: jvanzyl <jvanzyl@13f79535-47bb-0310-9956-ffa450edef68>
Date: Tue, 27 May 2003 13:39:56 +0000
Subject: [PATCH] o Applying Tim Anderson's patches for the castor plugin.

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@113444 13f79535-47bb-0310-9956-ffa450edef68
---
 castor/plugin.jelly         | 77 +++++++++++++++++++++++++++++----
 castor/plugin.properties    |  4 +-
 castor/project.xml          |  2 +-
 castor/xdocs/examples.xml   | 44 +++++++++++++++++++
 castor/xdocs/goals.xml      | 25 ++++++-----
 castor/xdocs/index.xml      | 39 +++++++++++++++--
 castor/xdocs/navigation.xml |  2 +
 castor/xdocs/properties.xml | 40 +++++++++++++++--
 castor/xdocs/tags.xml       | 86 +++++++++++++++++++++++++++++++++++++
 9 files changed, 290 insertions(+), 29 deletions(-)
 create mode 100644 castor/xdocs/examples.xml
 create mode 100644 castor/xdocs/tags.xml

diff --git a/castor/plugin.jelly b/castor/plugin.jelly
index 24989fab..6648e526 100644
--- a/castor/plugin.jelly
+++ b/castor/plugin.jelly
@@ -1,16 +1,74 @@
-<project 
-  xmlns:j="jelly:core" 
-  xmlns:ant="jelly:ant" 
-  xmlns:define="jelly:define"
-  xmlns:castor="castor">
+<?xml version="1.0"?>
+
+<project xmlns:j="jelly:core" 
+         xmlns:ant="jelly:ant" 
+         xmlns:define="jelly:define"
+         xmlns:castor="castor"
+         xmlns:maven="jelly:maven">
   
   <!-- ================================================================== -->
   <!-- C A S T O R                                                        -->
   <!-- ================================================================== -->
 
-    <define:taglib uri="castor">
-      <define:tag name="srcgen">
-        <ant:java
+  <goal name="castor:prepare-filesystem"
+        description="Make any necessary directories for castor processing">
+    <ant:mkdir dir="${maven.castor.dest}"/>
+    <ant:mkdir dir="${maven.castor.tstamp}"/>
+
+    <ant:path id="maven.castor.compile.src.set"
+              location="${maven.castor.dest}"/>
+    <maven:addPath id="maven.compile.src.set"
+                   refid="maven.castor.compile.src.set"/>
+  </goal>
+
+  <define:taglib uri="castor">
+    <define:tag name="generate">
+      <j:set var="fileVar" value="${schema}.filename"/>
+      <j:set var="uptodateVar" value="${schema}.uptodate"/>
+      <ant:basename property="${fileVar}" file="${schema}"/>
+      <j:set var="filename" value="${pom.getContext().getVariable(fileVar)}"/>
+      <j:set var="context" 
+             value="${pom.getPluginContext('maven-castor-plugin')}"/>
+      <j:set var="log" value="${context.getVariable('maven.castor.tstamp')}"/>
+      <j:set var="gen" value="${context.getVariable('maven.castor.dest')}"/>
+
+      <ant:uptodate property="${uptodateVar}" targetfile="${log}/${filename}">
+        <ant:srcfiles dir="${basedir}" includes="${schema}"/>
+      </ant:uptodate>
+
+      <j:set var="uptodate" 
+             value="${pom.getContext().getVariable(uptodateVar)}"/>
+
+      <j:if test="${uptodate == null}">
+        <ant:echo message="Generating sources for ${schema}"/>
+
+        <ant:java className="org.exolab.castor.builder.SourceGenerator"
+                  failonerror="true">
+          <ant:arg value="-i"/>
+          <ant:arg value="${schema}"/>
+          <ant:arg value="-f"/>
+          <j:if test="${!empty(package)}">
+            <ant:arg value="-package"/>
+            <ant:arg value="${package}"/>
+          </j:if>
+          <j:if test="${!empty(types)}">
+            <ant:arg value="-types"/>
+            <ant:arg value="${types}"/>
+          </j:if>
+          <j:if test="${!empty(marshal) and !marshal.trim().equals('true')}">
+            <ant:arg value="-nomarshall"/>
+          </j:if>
+          <ant:arg value="-dest"/>
+          <ant:arg value="${gen}"/>
+        </ant:java>
+        <ant:touch file="${log}/${filename}"/>
+      </j:if>
+
+    </define:tag>
+
+    <!-- needs to be deprecated -->
+    <define:tag name="srcgen">
+      <ant:java
           className="org.exolab.castor.builder.SourceGenerator"
           failonerror="true">
 
@@ -22,6 +80,7 @@
           <ant:arg value="-dest${generationDirectory}"/>
         </ant:java>
       </define:tag>
-    </define:taglib>
+
+  </define:taglib>
 
 </project>
diff --git a/castor/plugin.properties b/castor/plugin.properties
index a30b79f2..893cc7c5 100644
--- a/castor/plugin.properties
+++ b/castor/plugin.properties
@@ -1,7 +1,9 @@
 # -------------------------------------------------------------------
-# Default Maven properties for the VDoclet plugin.
+# Default Maven properties for the Castor plugin.
 # -------------------------------------------------------------------
 # These are the properties that we believe are immutable so we
 # keep them apart from the project specific properties.
 # -------------------------------------------------------------------
 
+maven.castor.dest=${maven.build.dir}/castor/src
+maven.castor.tstamp=${maven.build.dir}/castor/tstamp
diff --git a/castor/project.xml b/castor/project.xml
index 1488532e..0be423af 100644
--- a/castor/project.xml
+++ b/castor/project.xml
@@ -29,7 +29,7 @@
   <dependencies>
     <dependency>
       <id>castor</id>
-      <version>0.9.4</version>
+      <version>0.9.4.3</version>
       <properties>
         <classloader>root</classloader>
       </properties>
diff --git a/castor/xdocs/examples.xml b/castor/xdocs/examples.xml
new file mode 100644
index 00000000..0c69e8df
--- /dev/null
+++ b/castor/xdocs/examples.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0"?>
+<document>
+
+  <properties>
+    <title>Maven Castor Plug-in Examples</title>
+    <author email="tma@netspace.net.au">Tim Anderson</author>
+  </properties>
+
+  <body>
+    <section name="Examples">
+      <p>
+        The following generates java sources for the foo.xsd' schema,
+        in the 'com.foo.bar' package. The sources will use Java 2 collection
+        types.
+       
+<source><![CDATA[
+
+  <preGoal name="java:compile">
+    <attainGoal name="castor:prepare-filesystem"/>
+    <castor:generate schema="src/schemas/foo.xsd"
+                     package="com.foo.bar"
+                     types="j2"/>
+  </preGoal>
+
+]]></source>
+      </p>
+      <p>
+        The following generates java sources for the 'bar.xsd' schema.
+        The sources will not included marshalling support (marshal,
+        unmarshal, validate).
+               
+<source><![CDATA[
+
+  <preGoal name="java:compile">
+    <attainGoal name="castor:prepare-filesystem"/>
+    <castor:generate schema="src/schemas/types.xsd"
+                     marshal="false"/>
+  </preGoal>
+
+]]></source>
+      </p>
+    </section>
+  </body>
+</document>
diff --git a/castor/xdocs/goals.xml b/castor/xdocs/goals.xml
index 75b2c1cc..163572b7 100644
--- a/castor/xdocs/goals.xml
+++ b/castor/xdocs/goals.xml
@@ -4,17 +4,22 @@
   <properties>
     <title>Maven Castor Plug-in Goals</title>
     <author email="jason@zenplex.com">Jason van Zyl</author>
+    <author email="tma@netspace.net.au">Tim Anderson</author>
   </properties>
 
   <body>
-    <goals>
-      <goal>
-        <name>castor:srcgen</name>
-        <description>
-          For a given project generate a plexus runtime using the required
-          components.
-        </description>
-      </goal>
-    </goals>
- </body>
+    <section name="Goals">
+      <table>
+        <tr><th>Goal</th><th>Description</th></tr>
+        <tr>
+          <td>castor:prepare-filesystem</td>
+          <td>
+            Creates the directories specified by the 
+            <a href="properties.html">${maven.castor.dest}</a> and 
+            <a href="properties.html">${maven.castor.tstamp}</a> properties.
+          </td>
+        </tr>
+      </table>
+    </section>
+  </body>
 </document>
diff --git a/castor/xdocs/index.xml b/castor/xdocs/index.xml
index d737b075..f3ac88d6 100644
--- a/castor/xdocs/index.xml
+++ b/castor/xdocs/index.xml
@@ -4,13 +4,44 @@
   <properties>
     <title>Maven Castor Plug-in</title>
     <author email="jason@zenplex.com">Jason van Zyl</author>
+    <author email="tma@netspace.net.au">Tim Anderson</author>
   </properties>
 
   <body>
     <section name="Maven Castor Plug-in">
-      <p>
-       A plugin that currently just sets up castor for use in Jelly
-      </p>
+      <subsection name="Overview of the Castor Plug-in Reference Documentation">       <p>
+          This plugin generates java sources from schemas using Castor.
+        </p>
+        <table>
+          <tr><th>Document</th><th>Description</th></tr>
+          <tr><td><a href="goals.html">Goals</a></td>
+            <td>
+              This document provides detailed information on the various
+              goals that are available as part of the Maven Castor Plug-in.
+            </td>
+          </tr>
+          <tr><td><a href="properties.html">Properties</a></td>
+            <td>
+              The behavior of the Maven Castor Plug-in can be altered via
+              several properties.  This document describes each property
+              available, and the default used.
+            </td>
+          </tr>
+          <tr><td><a href="tags.html">Tags</a></td>
+            <td>
+              The Castor plugin defines Jelly tags to generate java
+              sources. This document describes the tags and their
+              arguments.
+            </td>
+          </tr>
+          <tr><td><a href="examples.html">Examples</a></td>
+            <td>
+              This document provides examples on how to use the Maven Castor 
+              plugin.
+            </td>
+          </tr>
+        </table>
+      </subsection>
     </section>
- </body>
+  </body>
 </document>
diff --git a/castor/xdocs/navigation.xml b/castor/xdocs/navigation.xml
index a610b692..e5335258 100644
--- a/castor/xdocs/navigation.xml
+++ b/castor/xdocs/navigation.xml
@@ -11,6 +11,8 @@
     <menu name="Overview">
       <item name="Goals"      href="/goals.html" />
       <item name="Properties" href="/properties.html" />
+      <item name="Tags" href="/tags.html" />
+      <item name="Examples" href="/examples.html" />
     </menu>
   </body>
 </project>
diff --git a/castor/xdocs/properties.xml b/castor/xdocs/properties.xml
index e6db8607..217342bf 100644
--- a/castor/xdocs/properties.xml
+++ b/castor/xdocs/properties.xml
@@ -4,6 +4,7 @@
   <properties>
     <title>Maven Castor Plugin Properties</title>
     <author email="jason@zenplex.com">Jason van Zyl</author>
+    <author email="tma@netspace.net.au">Tim Anderson</author>
   </properties>
 
   <body>
@@ -11,13 +12,44 @@
       <table>
         <tr>
           <th>Property name</th>
-          <th>Optional?</th>
           <th>Description</th>
+          <th>Optional?</th>
         </tr>
         <tr>
-          <td></td>
-          <td></td>
-          <td></td>
+          <td>maven.castor.dest</td>
+          <td>
+            Specifies the directory to place generated sources.<br/>
+            Defaults value is ${maven.build.dir}/castor/src
+          </td>
+          <td>Yes</td>
+        </tr>
+        <tr>
+          <td>maven.castor.tstamp</td>
+          <td>
+             Specifies the directory to output timestamp files.
+             These are used to track source modifications against the
+             generated files, to avoid unecessary generation.<br/>
+             Default value is ${maven.build.dir}/castor/tstamp
+          </td>
+          <td>Yes</td>
+        </tr>
+      </table>
+    </section>
+    <section name="Other properties used">
+      <table>
+        <tr>
+          <th>Property name</th>
+          <th>Description</th>
+          <th>Optional?</th>
+        </tr>
+        <tr>
+          <td>maven.compile.src.set</td>
+          <td>
+            The source directories maven uses to compile java code.
+            The Castor plugin adds the directory it generates code to
+            this path, so that generated code is compiled seamlessly
+          </td>
+          <td>Yes</td>
         </tr>
       </table>
     </section>
diff --git a/castor/xdocs/tags.xml b/castor/xdocs/tags.xml
new file mode 100644
index 00000000..a31321a6
--- /dev/null
+++ b/castor/xdocs/tags.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0"?>
+<document>
+
+  <properties>
+    <title>Maven Castor Plug-in Tags</title>
+    <author email="tma@netspace.net.au">Tim Anderson</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 Castor Plug-in with Maven.
+      </p>
+      <p>
+        Please refer to the 
+        <a href="../../start/integrate.html">Integration</a> document for
+        more information on how to integrate these tags into
+        your project.
+      </p>
+    </section>
+
+    <section name="Tags">
+      <table>
+        <tr><th>Goal</th><th>Description</th></tr>
+        <tr>
+          <td><a href="#castor:generate">castor:generate</a></td>
+          <td>Generate java sources from an XML Schema.</td>
+        </tr>
+        <tr>
+          <td>castor:srcgen</td>
+          <td><strong>DEPRECATED</strong>. Use castor:generate instead</td>
+        </tr>
+      </table>
+      
+      <subsection name="castor:generate">
+        <p>
+          The <code>castor:generate</code> target generates java sources
+          from an XML Schema (<code>XSD</code> file). <br/>
+          Sources are generated in the 
+          <a href="properties.html">${maven.castor.dest}</a> directory.<br/>
+          Sources are only generated if the input schema is newer than any
+          existing generated source.
+        </p>
+        <table>
+          <tr>
+            <th>Attribute Name</th><th>Description</th><th>Optional?</th>
+          </tr>
+          <tr>
+            <td>schema</td>
+            <td>The path to the XML schema</td>
+            <td>No</td>
+          </tr>
+          <tr>
+            <td>package</td>
+            <td>The package for the generated source</td>
+            <td>Yes</td>
+          </tr>
+          <tr>
+            <td>types</td>
+            <td>Sets which type factory to use. This is useful if you want 
+                JDK 1.2 collections instead of JDK 1.1, or if you want to pass 
+                in your own FieldInfoFactory.<br/>
+                If not specified, java.util.Vector will be used for 
+                collections.<br/>
+                See 
+                <a href="http://castor.exolab.org/sourcegen.html#Collection-Types">Collection Types</a> 
+                for valid values.
+            </td>
+            <td>Yes</td>           
+          </tr>
+          <tr>
+            <td>marshal</td>
+            <td>
+              If 'false', disables generation of the marshalling framework 
+              methods (marshal, unmarshal, validate).<br/>
+              Defaults to 'true'.
+            </td>
+            <td>Yes</td>
+          </tr>
+        </table>
+      </subsection>
+    </section>
+  </body>
+</document>
\ No newline at end of file