You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rd...@apache.org on 2002/12/15 20:58:36 UTC
cvs commit: jakarta-commons/betwixt/xdocs overview.xml
rdonkin 2002/12/15 11:58:36
Modified: betwixt project.xml
betwixt/xdocs overview.xml
Log:
Changed example documentation so that it works better with latest version of maven
Revision Changes Path
1.19 +4 -0 jakarta-commons/betwixt/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/project.xml,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- project.xml 15 Dec 2002 17:11:57 -0000 1.18
+++ project.xml 15 Dec 2002 19:58:36 -0000 1.19
@@ -62,21 +62,25 @@
<dependency>
<id>commons-logging</id>
<version>1.0</version>
+ <url>http://jakarta.apache.org/commons/logging.html</url>
</dependency>
<dependency>
<id>commons-beanutils</id>
<version>1.3</version>
+ <url>http://jakarta.apache.org/commons/beanutils.html</url>
</dependency>
<dependency>
<id>commons-collections</id>
<version>2.0</version>
+ <url>http://jakarta.apache.org/commons/collections.html</url>
</dependency>
<dependency>
<id>commons-digester</id>
<version>1.2</version>
+ <url>http://jakarta.apache.org/commons/digester.html</url>
</dependency>
<!-- runtime dependencies only required for testing and sample programs -->
1.4 +63 -63 jakarta-commons/betwixt/xdocs/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/overview.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- overview.xml 28 Oct 2002 21:13:34 -0000 1.3
+++ overview.xml 15 Dec 2002 19:58:36 -0000 1.4
@@ -17,7 +17,7 @@
build system working, by installing Ant and creating your own build.properties
to point to the required JARs type the following at a command line</p>
-<pre>ant demo.rss</pre>
+<source><![CDATA[ant demo.rss]]></source>
<p>This uses the Commons Digester RSSDigester example to parse an RSS document,
create a Channel bean and then write it out again as XML using the default
@@ -26,7 +26,7 @@
<p>The next example to look at is</p>
-<pre>ant demo.rss2</pre>
+<source><![CDATA[ant demo.rss2]]></source>
<p>This is similar to the above but uses a BeanReader to parse the RSS file. So
this is Betwixt defaulting the Digester rules required to parse the XML document.
@@ -39,11 +39,11 @@
<p>There are various ways of mapping beans to an XML structure. For example
consider a simple bean</p>
-<pre>public class CustomerBean {
+<source><![CDATA[public class CustomerBean {
public String getName();
public Order[] getOrders();
public String[] getEmailAddresses();
-}</pre>
+}]]></source>
<p>This could be mapped to XML as these various ways</p>
@@ -52,11 +52,11 @@
<p>This example uses attributes for primitive types.</p>
-<pre>&lt;CustomerBean name=&quot;James&quot;&gt;
- &lt;order id=&quot;1&quot;&gt;...&lt;/order&gt;
- &lt;order id=&quot;2&quot;&gt;...&lt;/order&gt;
- &lt;emailAddress&gt;jstrachan@apache.org&lt;/emailAddress&gt;
-&lt;/CustomerBean&gt;</pre>
+<source><![CDATA[<CustomerBean name='James'>
+ <order id='1'>...</order>
+ <order id='2'>...</order>
+ <emailAddress>jstrachan@apache.org</emailAddress>
+</CustomerBean>]]></source>
</section>
@@ -66,16 +66,16 @@
extra element (which can be quite common in XML schemas). Also note that some
element names have been changed.</p>
-<pre>&lt;customer&gt;
- &lt;name&gt;James&lt;/name&gt;
- &lt;orders&gt;
- &lt;order id=&quot;1&quot;&gt;...&lt;/order&gt;
- &lt;order id=&quot;2&quot;&gt;...&lt;/order&gt;
- &lt;/orders&gt;
- &lt;email-addresses&gt;
- &lt;email-address&gt;jstrachan@apache.org&lt;/email-address&gt;
- &lt;/email-addresses&gt;
-&lt;/customer&gt; </pre>
+<source><![CDATA[<customer>
+ <name>James</name>
+ <orders>
+ <order id='1'>...</order>
+ <order id='2'>...</order>
+ </orders>
+ <email-addresses>
+ <email-address>jstrachan@apache.org</email-address>
+ </email-addresses>
+</customer> ]]></source>
<p>Betwixt aims to provide a diversity of possible mappings such that the
developer can choose, if they wish, how their beans appear as XML to support
@@ -97,65 +97,65 @@
then the default introspection rules are used.</p>
<p>The simplest possible file may just set the name of the element. e.g.</p>
-<pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?&gt;
-&lt;info&gt;
- &lt;element name=&quot;channel&quot;/&gt;
- &lt;addDefaults/&gt;
-&lt;/info&gt;</pre>
+<source><![CDATA[<?xml version='1.0' encoding='UTF-8' ?>
+<info>
+ <element name='channel'/>
+ <addDefaults/>
+</info>]]></source>
<p>The above means to use the name 'channel' for the outer most element for the
-given type. The &lt;addDefaults&gt; means to add the defaults from the introspector.
+given type. The <![CDATA[<addDefaults>]]> means to add the defaults from the introspector.
This allows you to just rename a few properties then let the introspector do the
-rest. There is also a &lt;hide&gt; element which allows one or more properties to be
-hidden. Also note that the &lt;element&gt; and &lt;attribute&gt; tags can be
+rest. There is also a <![CDATA[<hide>]]> element which allows one or more properties to be
+hidden. Also note that the <![CDATA[<element>]]> and <![CDATA[<attribute>]]> tags can be
nested to any
kind of depth allowing whatever XML structure you wish. This can be useful if
you wish to wrap collections in some arbitrary collection tags or to group
properties of a bean together in some XML structure. e.g.</p>
-<pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?&gt;
-&lt;info primitiveTypes=&quot;attribute&quot;&gt;
- &lt;element name=&quot;channel&quot;/&gt;
- &lt;element name=&quot;customerList&quot;&gt;
- &lt;element name=&quot;customer&quot; property=&quot;customers&quot;/&gt;
- &lt;/element&gt;
- &lt;element name=&quot;foo&quot;&gt;
- &lt;attribute name=&quot;qqq&quot; property=&quot;ppp&quot;/&gt;
- &lt;element name=&quot;bar&quot; property=&quot;xyz&quot;/&gt;
- &lt;hide property=&quot;something&quot;/&gt;
- &lt;addDefaults/&gt;
- &lt;/element&gt;
-&lt;/info&gt;
-</pre>
+<source><![CDATA[<?xml version='1.0' encoding='UTF-8' ?>
+<info primitiveTypes='attribute'>
+ <element name='channel'/>
+ <element name='customerList'>
+ <element name='customer' property='customers'/>
+ </element>
+ <element name='foo'>
+ <attribute name='qqq' property='ppp'/>
+ <element name='bar' property='xyz'/>
+ <hide property='something'/>
+ <addDefaults/>
+ </element>
+</info>
+]]></source>
<p>Note that the <code>.betwixt</code> file specifies the mapping for a single bean.
So, whilst you can add extra elements (as above), it can't be used to specify
to names for child beans through nesting <code>element</code> elements.</p>
-<p>The primitiveTypes attribute in the &lt;info&gt; element is optional and can be
+<p>The primitiveTypes attribute in the <![CDATA[<info>]]> element is optional and can be
used to specify whether primitive java types (strings, numbers, dates etc) are
specified as attributes or elements by default.</p>
<p>Finally static text can be specified using a value attribute inside an
-&lt;element&gt; or &lt;attribute&gt; tag. e.g. to add constant attributes such
+<![CDATA[<element>]]> or <![CDATA[<attribute>]]> tag. e.g. to add constant attributes such
as a version label to the
generated XML...</p>
-<pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?&gt;
-&lt;info primitiveTypes=&quot;element&quot;&gt;
- &lt;element name=&quot;rss&quot;/&gt;
- &lt;attribute name=&quot;version&quot; value=&quot;0.91&quot;/&gt;
- &lt;element name=&quot;channel&quot;/&gt;
- &lt;addDefaults/&gt;
- &lt;/element&gt;
-&lt;/info&gt;
-</pre>
+<source><![CDATA[<?xml version='1.0' encoding='UTF-8' ?>
+<info primitiveTypes='element'>
+ <element name='rss'/>
+ <attribute name='version' value='0.91'/>
+ <element name='channel'/>
+ <addDefaults/>
+ </element>
+</info>
+]]></source>
</section>
<section name="Bean naming conventions">
<p>The Java Beans specification contains various naming conventions that should
be used when writing beans that will allow the beans introspector to
-automatically guess the properties in a bean and their getters &amp; setter methods
+automatically guess the properties in a bean and their getters <![CDATA[&]]> setter methods
etc. Betwixt will use these same naming conventions to deduce how to make the
beans appear as XML. There are some other naming conventions that you can use to
make your beans easier to output as XML or parse.</p>
@@ -168,10 +168,10 @@
<p>To use: create an add method to match the getter method for 'composite
properties'.</p>
-<pre>public class SomeBean {
- public &lt;CollectionType&gt; getFoo*();
- public void addFoo(&lt;SingularType&gt; foo);
-}</pre>
+<source><![CDATA[public class SomeBean {
+ public <CollectionType> getFoo*();
+ public void addFoo(<SingularType> foo);
+}]]></source>
<p>Where CollectionType can be an array, a Collection, Enumeration, Iterator,
Map. The [SinglularType] refers to the type of an item in the collection. The
@@ -184,25 +184,25 @@
<p>In the RSS example from Digester there's a bean which matches this pattern.</p>
-<pre>
+<source><![CDATA[
public class Channel
public Item[] getItems();
public void addItem(Item item);
}
-</pre>
+]]></source>
<p>This means that the following bean does not match this naming convention,
since the plural property name does not start with the singular name..</p>
-<pre>public class Foo {
+<source><![CDATA[public class Foo {
public Collection getPeople();
public void addPerson(Person person);
-}</pre>
+}]]></source>
<p>Though these two beans do match</p>
-<pre>public class Foo {
+<source><![CDATA[public class Foo {
public Collection getPersonCollection();
public void addPerson(Person person);
}
@@ -210,7 +210,7 @@
public Iterator getPersonIterator();
public void addPerson(Person person);
}
-</pre>
+]]></source>
<p>The following are other valid examples of <i>composite-getter</i> methods and
their matching <i>adder</i> methods.</p>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>