You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jaxme-dev@ws.apache.org by rd...@apache.org on 2004/07/06 22:10:27 UTC
cvs commit: ws-jaxme/src/documentation/manual xjctask.xml
rdonkin 2004/07/06 13:10:27
Modified: src/documentation/manual Tag: Branch_R0_3 xjctask.xml
Log:
Small improvements to documentation
Revision Changes Path
No revision
No revision
1.2.6.2 +39 -37 ws-jaxme/src/documentation/manual/xjctask.xml
Index: xjctask.xml
===================================================================
RCS file: /home/cvs/ws-jaxme/src/documentation/manual/xjctask.xml,v
retrieving revision 1.2.6.1
retrieving revision 1.2.6.2
diff -u -r1.2.6.1 -r1.2.6.2
--- xjctask.xml 27 Jun 2004 20:27:17 -0000 1.2.6.1
+++ xjctask.xml 6 Jul 2004 20:10:27 -0000 1.2.6.2
@@ -16,11 +16,11 @@
limitations under the License.
-->
-<sect1><title>The JaxMe Ant task</title>
-<para>The JaxMe Ant task was written with the following in mind:
+<sect1><title>The JaxMe Ant Task</title>
+<para>The JaxMe Ant task was written with the following goals in mind:
<itemizedlist>
- <listitem>Preserve as much compatibility as possible to the JAXB xjc task</listitem>
- <listitem>Provide access to the JaxMe extensions</listitem>
+ <listitem>To preserve as much compatibility as possible with the JAXB xjc task</listitem>
+ <listitem>To provide access to JaxMe extensions</listitem>
</itemizedlist>
In other words, if you have existing build scripts using JAXB's xjc, you should
be able to convert them to JaxMe with a single switch (by exchanging the
@@ -41,9 +41,10 @@
</target>
]]></programlisting>
</para>
-<para>In other words: Typically you define a target like "taskdef", which loads the
- ant task under a given name ("xjc" in the above example, or "jaxme"). The task is
- actually used in another target.</para>
+<para>A target (called "taskdef" above) defines the
+ ant task under a given name ("xjc" in the above example). It is important to remember
+ to include the JaxMe jars in the classpath when defining the task.
+ This task is then called by the source generation target.</para>
<para>The ant task supports the following attributes:
<table><title>Attributes of the JaxMe ant task</title>
<tgroup cols="3" colsep="1" rowsep="1" tocentry="1">
@@ -58,8 +59,8 @@
<tbody>
<row>
<entry>binding</entry>
- <entry><para>Name of an external binding file being applied to the schema file; this
- attribute and the nested <binding> element are mutually exclusive.</para>
+ <entry><para>Name of an external binding file being applied to the schema file.
+ This attribute and the nested <binding> element are mutually exclusive.</para>
<para>As of this writing, external schema bindings are unsupported by JaxMe.
A BuildException is thrown, if you use this attribute anyways.</para></entry>
<entry>JAXB XJC</entry>
@@ -69,39 +70,40 @@
<entry>extension</entry>
<entry><para>If this attribute has the value "true", then the XJC binding compiler
will run in the extension mode. Otherwise, it will run in the strict conformance mode.</para>
- <para>Extension mode indicates that the proprietary "xjc" tags are accepted, which are
- specified by the JAXB binding compiler.</para></entry>
+ <para>Extension mode indicates that the proprietary "xjc" tags
+ (specific to the JAXB binding compiler) are accepted.</para></entry>
<entry>JAXB XJC</entry>
<entry>No, defaults to "false"</entry>
</row>
<row>
<entry>force</entry>
- <entry><para>Setting this option to "true" forces the up-to-date check to fail, in
- which case the nested <produces> elements are ignored.</para>
- <para>This attribute isn't of much use for the JaxMe user. It is mainly designed
- for JaxMe developers who want to specify a value from the command line, because
- they have updated the schema compiler and want to run the new version.</para></entry>
+ <entry><para>Setting this option to "true" forces the up-to-date check to fail
+ (and so the nested <produces> elements are ignored).</para>
+ <para>This attribute isn't of much use to the JaxMe user. It is mainly intended
+ for JaxMe developers who want to specify a value from the command line.
+ This is useful when they have updated the schema compiler
+ and want to run against the old schema with the new version.</para></entry>
<entry>JaxMe</entry>
<entry>No, defaults to "false"</entry>
</row>
<row>
<entry>package</entry>
<entry>Specifies the package name of the generated sources. If this attribute is
- specified, then it overrides values specified in the schema bindings, if any.</entry>
+ specified, then it overrides any values specified in the schema bindings.</entry>
<entry>JAXB XJC</entry>
<entry>No, defaults to values specified in the schema bindings or to a package name
derived from the target namespace URI.</entry>
</row>
<row>
<entry>schema</entry>
- <entry>Name of a schema file being compiled; this attribute and the nested
+ <entry>Name of a schema file being compiled. This attribute and the nested
<schema> element are mutually exclusive.</entry>
<entry>JAXB XJC</entry>
<entry>Yes, unless a nested <schema> element is present</entry>
</row>
<row>
<entry>readonly</entry>
- <entry>If this attribute has the value "true", then the generated source files
+ <entry>If this attribute has the value "true" then the generated source files
will have read-only mode.</entry>
<entry>JAXB XJC</entry>
<entry>No, defaults to "false"</entry>
@@ -122,9 +124,9 @@
<entry>schemaReader</entry>
<entry>Configures the schema reader to use. Defaults to
"org.apache.ws.jaxme.generator.sg.impl.JAXBSchemaReader", which is the JAXB compliant
- schema reader. An alternative schema readers is, for example,
- "org.apache.ws.jaxme.generator.sg.impl.JaxMeSchemaReader" (a subclass of JAXBSchemaReader
- with JaxMe specific extensions).</entry>
+ schema reader. An alternative schema reader is, for example,
+ "org.apache.ws.jaxme.generator.sg.impl.JaxMeSchemaReader"
+ (a subclass of JAXBSchemaReader with JaxMe specific extensions).</entry>
<entry>JaxMe</entry>
<entry>No, defaults to "org.apache.ws.jaxme.generator.sg.impl.JAXBSchemaReader"</entry>
</row>
@@ -176,8 +178,8 @@
<row>
<entry>arg</entry>
<entry><para>This nested element is ignored by the JaxMe ant task and exists for
- compatibility to the JAXB ant task only. A warning is logged, if you use it
- anyways.</para>
+ JAXB compatibility only. If this element is present, a warning
+ will be logged.</para>
<para>In the case of JAXB it specifies additional command line arguments being
passed to the XJC. For details about the syntax, see the relevant section in
the Ant manual.</para>
@@ -201,7 +203,7 @@
to a nested <fileset>. Use of a nested <binding> element is
mutually exclusive with the use of a "binding" attribute.</para>
<para>As of this writing, external schema bindings are unsupported by JaxMe.
- A BuildException is thrown, if you use this attribute anyways.</para></entry>
+ A BuildException is thrown if this attribute is used.</para></entry>
<entry>JAXB XJC</entry>
<entry>0..Unbounded</entry>
</row>
@@ -210,18 +212,19 @@
<entry><para>This nested element specifies the classpath for loading user defined classes.
For example, the schema reader specified by the "schemaReader" attribute may be such
a type.</para>
- <para>The JAXB binding compiler is using this classpath for loading user defined types,
+ <para>The JAXB binding compiler uses this classpath when loading user defined types,
as specified by the <javaType> customization. This is currently not the case
for JaxMe: The type names are simply compiled in without an attempt to actually load
- them. This has the advantage, that user defined classes may refer generated sources.
+ them. This has the advantage that user defined classes may refer to sources which will
+ generated.
</para></entry>
<entry>JAXB XJC</entry>
<entry>0..Unbounded</entry>
</row>
<row>
<entry>depends</entry>
- <entry><para>By default the JaxMe Ant tasks up-to-date check considers the specified
- schema and binding files only. This is insufficient, if other schema files are included,
+ <entry><para>By default the up-to-date check (used by the JaxMe task) considers the specified
+ schema and binding files only. This is insufficient when auxiliary schema files are included,
imported or redefined.</para>
<para>The nested <depends> element allows to specify additional files to consider
for the up-to-date check. Typically these are the additional schema files.</para>
@@ -232,7 +235,7 @@
</row>
<row>
<entry>produces</entry>
- <entry>Specifies the set of files being created by the JaxMe ant task. These
+ <entry>Specifies the set of files to be created by the JaxMe ant task. These
files are considered as targets for the up-to-date check. The syntax of the <produces>
element is equivalent to a nested <fileset>. However, you typically do not
need to set the "dir" attribute, because it defaults to the target directory.
@@ -242,8 +245,8 @@
</row>
<row>
<entry>property</entry>
- <entry>Sets a property value. These properties may be used by the various source
- generators to configure the behaviour. For example, the JDBC schema reader uses
+ <entry>Sets a property value. These properties may be used to pass configuration
+ information to the various source generators. For example, the JDBC schema reader uses
the options "jdbc.driver", "jdbc.url", "jdbc.user", and "jdbc.password" to
configure the database connection. Each property must have attributes "name" (the
property name) and "value" (the property value).</entry>
@@ -276,11 +279,10 @@
</para>
<sect2><title>The Up-to-date check</title>
- <para>By default, the JaxMe ant task will always run the generator and create new files. This
- is typically inappropriate for an ant script where your desire is to have as little
- modifications as possible, because new files also need to be recompiled, which is slow
- and time consuming.</para>
- <para>To achieve a better behaviour, use the nested <produces> and <depends> elements.
+ <para>By default, the JaxMe ant task will always run the generator and create new files.
+ When this task is part of a general ant build script, this behaviour will result
+ in new files being generated and recompiled each time the build is run.</para>
+ <para>To achieve greater efficiency, use the nested <produces> and <depends> elements.
If one or more <produces> element is specified, then an up-to-date check is performed
as follows:
<orderedlist>
---------------------------------------------------------------------
To unsubscribe, e-mail: jaxme-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: jaxme-dev-help@ws.apache.org