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/23 23:51:51 UTC
cvs commit: jakarta-commons/betwixt/xdocs overview.xml todo.xml
rdonkin 2002/12/23 14:51:51
Modified: betwixt/xdocs overview.xml todo.xml
Log:
Improved presentation of main documentation and updated task list for upcoming alpha release
Revision Changes Path
1.5 +124 -108 jakarta-commons/betwixt/xdocs/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/overview.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- overview.xml 15 Dec 2002 19:58:36 -0000 1.4
+++ overview.xml 23 Dec 2002 22:51:51 -0000 1.5
@@ -11,61 +11,61 @@
<section name="Getting Started">
-<p>Probably the best way to get started is to look at some examples. The best
-example to start with is the Ant target &quot;demo.rss&quot; which runs the RSSBeanWriter
-sample program in the src/test directory. Once you've got the Jakarta Commons
-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>
-
+ <p>Probably the best way to get started is to look at some examples. The best
+ example to start with is the Ant target <code>'demo.rss'</code>
+ which runs the RSSBeanWriter sample program in the src/test directory. Once you've
+ got the Jakarta Commons 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>
+
<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
-XMLIntrospector and the BeanWriter. You should see the XML come out from the
-Channel bean which looks similar to a real RSS document.</p>
-
-<p>The next example to look at is</p>
-
+
+ <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
+ XMLIntrospector and the BeanWriter. You should see the XML come out from the
+ Channel bean which looks similar to a real RSS document.</p>
+
+ <p>The next example to look at is</p>
+
<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.
-Then the BeanWriter is used to output the beans that get created.</p>
+
+ <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.
+ Then the BeanWriter is used to output the beans that get created.</p>
</section>
<section name="Mapping beans to XML">
-
-<p>There are various ways of mapping beans to an XML structure. For example
-consider a simple bean</p>
-
+
+ <p>There are various ways of mapping beans to an XML structure. For example
+ consider a simple bean</p>
+
<source><![CDATA[public class CustomerBean {
public String getName();
public Order[] getOrders();
public String[] getEmailAddresses();
}]]></source>
+
+ <p>This could be mapped to XML as these various ways</p>
-<p>This could be mapped to XML as these various ways</p>
-
-<section name="Example 1">
-
-<p>This example uses attributes for primitive types.</p>
+<subsection name="Example 1">
+
+ <p>This example uses attributes for primitive types.</p>
<source><![CDATA[<CustomerBean name='James'>
<order id='1'>...</order>
<order id='2'>...</order>
<emailAddress>jstrachan@apache.org</emailAddress>
</CustomerBean>]]></source>
-</section>
-
-
-<section name="Example 2">
-
-<p>This example uses elements for all properties and wraps collections in an
-extra element (which can be quite common in XML schemas). Also note that some
-element names have been changed.</p>
-
+</subsection>
+
+
+ <subsection name="Example 2">
+
+ <p>This example uses elements for all properties and wraps collections in an
+ extra element (which can be quite common in XML schemas). Also note that some
+ element names have been changed.</p>
+
<source><![CDATA[<customer>
<name>James</name>
<orders>
@@ -76,113 +76,128 @@
<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
-whatever XML encoding scheme that is desired. If no particular mapping is
-provided then Betwixt will create a default mapping for you. Also the
-customization mechanism allows you to just override the parts you want to and
-let Betwixt default the rest. So if you just want to rename a property in XML
-for a certain type, thats all you need to do. No need to hand-code what Betwixt
-can deduce for itself. </p>
-</section>
+
+ <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
+ whatever XML encoding scheme that is desired. If no particular mapping is
+ provided then Betwixt will create a default mapping for you. Also the
+ customization mechanism allows you to just override the parts you want to and
+ let Betwixt default the rest. So if you just want to rename a property in XML
+ for a certain type, thats all you need to do. No need to hand-code what Betwixt
+ can deduce for itself. </p>
+</subsection>
</section>
<section name="Customizing the mapping of a bean to XML">
-
-<p>The XMLIntrospector will look for files of the form <i>className.betwixt</i>
-on the classpath using the same ClassLoader used to load the given class and use
-that document to specify the mapping to XML. If this file does not exist
-then the default introspection rules are used.</p>
-<p>The simplest possible file may just set the name of the element. e.g.</p>
-
+
+ <p>The XMLIntrospector will look for files of the form <i>className.betwixt</i>
+ on the classpath using the same ClassLoader used to load the given class and use
+ that document to specify the mapping to XML. If this file does not exist
+ then the default introspection rules are used.</p>
+ <p>The simplest possible file may just set the name of the element. e.g.</p>
+
<source><![CDATA[<?xml version='1.0' encoding='UTF-8' ?>
<info>
- <element name='channel'/>
- <addDefaults/>
+<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 <![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 <![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>
-
+
+ <p>The above means to use the name 'channel' for the outer most element for the
+ given type. The <code><addDefaults></code> 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 <code><hide></code> element which allows one or more properties to be
+ hidden. Also note that the <code><element></code> and
+ <code><attribute></code> 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>
+
<source><![CDATA[<?xml version='1.0' encoding='UTF-8' ?>
<info primitiveTypes='attribute'>
- <element name='channel'/>
+<element name='channel'/>
<element name='customerList'>
- <element name='customer' property='customers'/>
+ <element name='customer' property='customers'/>
</element>
<element name='foo'>
- <attribute name='qqq' property='ppp'/>
- <element name='bar' property='xyz'/>
+ <attribute name='qqq' property='ppp'/>
+ <element name='bar' property='xyz'/>
<hide property='something'/>
<addDefaults/>
- </element>
+</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 <![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
-<![CDATA[<element>]]> or <![CDATA[<attribute>]]> tag. e.g. to add constant attributes such
-as a version label to the
-generated XML...</p>
-
+
+ <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 <code><info></code> 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
+ <code><element></code> or <code><attribute></code> tag.
+ e.g. to add constant attributes such as a version label to the
+ generated XML...</p>
+
<source><![CDATA[<?xml version='1.0' encoding='UTF-8' ?>
<info primitiveTypes='element'>
- <element name='rss'/>
+<element name='rss'/>
<attribute name='version' value='0.91'/>
<element name='channel'/>
<addDefaults/>
- </element>
+</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 <![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>
+ <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, their
+ 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>
+
+ <p>
+ The Betwixt approach to this problem uses pluggable interfaces in the
+ <code>org.apache.commons.betwixt.strategy</code> package.
+ </p>
+
+<subsection name="Converting Type Names To Element Names">
+
+ <p>
+ Betwixt supports pluggable conversion of type names to element names.
+ </p>
+
+</subsection>
+
</section>
<section name="Using adder methods for composite properties">
-<p>This naming convention is used to indicate the singular type of some composite property.</p>
-
-<p>To use: create an add method to match the getter method for 'composite
-properties'.</p>
+ <p>This naming convention is used to indicate the singular type of some composite property.</p>
+
+ <p>To use: create an add method to match the getter method for 'composite
+ properties'.</p>
<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
-name of the getter property starts with 'Foo'. So 'Foo' is the singular name,
-the plural collection name could be Foos, FooArray, FooList, FooIterator or some
-other encoding, though the plural name should start with the singular name for
-auto-detection to work properly.</p>
+ <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
+ name of the getter property starts with 'Foo'. So 'Foo' is the singular name,
+ the plural collection name could be Foos, FooArray, FooList, FooIterator or some
+ other encoding, though the plural name should start with the singular name for
+ auto-detection to work properly.</p>
<section name="Examples">
-<p>In the RSS example from Digester there's a bean which matches this pattern.</p>
+ <p>In the RSS example from Digester there's a bean which matches this pattern.</p>
<source><![CDATA[
public class Channel
@@ -193,14 +208,15 @@
}
]]></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>
+ <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>
+
<source><![CDATA[public class Foo {
public Collection getPeople();
public void addPerson(Person person);
}]]></source>
-<p>Though these two beans do match</p>
+ <p>Though these two beans do match</p>
<source><![CDATA[public class Foo {
public Collection getPersonCollection();
@@ -212,8 +228,8 @@
}
]]></source>
-<p>The following are other valid examples of <i>composite-getter</i> methods and
-their matching <i>adder</i> methods.</p>
+ <p>The following are other valid examples of <i>composite-getter</i> methods and
+ their matching <i>adder</i> methods.</p>
<table border="1" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
<tr>
1.16 +127 -26 jakarta-commons/betwixt/xdocs/todo.xml
Index: todo.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/todo.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- todo.xml 4 Nov 2002 11:55:02 -0000 1.15
+++ todo.xml 23 Dec 2002 22:51:51 -0000 1.16
@@ -12,25 +12,54 @@
The following is a list of items that need to be completed in
Betwixt. Contributions are welcome!
</p>
-
- <section name="High priority">
+ <subsection name='For 1.0 Alpha 1 Release'>
+ <ul>
+ <li>
+ <strong>Add strategy documentation. </strong>
+ This needs to be added to the main documentation.
+ Example code needs to be created.
+ This code can also be used for more test cases.
+ </li>
+ <li>
+ <strong>Add description of digester-related limitation to FAQ</strong>
+ </li>
+ <li>
+ <strong>Create DTD for .betwixt files.</strong>
+ </li>
+ <li>
+ <strong>Add XMLIntrospector Setting Documentation. </strong>
+ Add documentation about the XMLIntrospector settings to main documentation.
+ Make sure that warnings are added about consequences of changing settings.
+ </li>
+ <li>
+ <strong>Add XMLRegistry documentation. </strong>
+ Add documentation about XMLRegistry to main documentation.
+ </li>
+ <li>
+ <strong>Improve Java Docs. </strong>
+ Go through java docs, add any which are missing, correct any mistakes etc.
+ </li>
+ <li>
+ <strong>Test Against Powered By Projects. </strong>
+ Make sure release works with maven and scarab.
+ </li>
+ </ul>
+ </subsection>
+
+ <subsection name="High priority">
<ul>
<li>
- BeanWriter is writing to sloppy (empty elements, etc). Fixing it in a clean way
+ BeanWriter is writing too sloppy (empty elements, etc). Fixing it in a clean way
is almost impossible.
Probably a refactor is best anyway to have a less "sloppy" api..
</li>
<li>
- Get an overview of what .betwxixt files should really do. Especially more complicated examples will cause very strange and unexpected results.
+ Get an overview of what .betwixt files should really do.
+ Especially more complicated examples will cause very strange and unexpected results.
</li>
<li>
- If an addFoo() method is found with no matching getFoos() then a warning should be generated.
- </li>
- <li>
- <b>Fixed.</b> digester.peek() was giving warning. Now checking if it still has something to peek.
- Currently betwixt causes digester to output a warning '[WARN] Digester - -Empty stack (returning null)'.
- We should patch the way betwixt uses digester to avoid this warning message.
+ If an addFoo() method is found with no matching getFoos() then a warning should be generated.
</li>
<li>
Consider allowing the parsing of XML to order the properties/elements in the XMLBeanInfo
@@ -45,30 +74,76 @@
More good code examples.
</li>
<li>
- Add support for IDREF's to BeanReader. At the moment, round tripping break when cycles exist.
+ Add support for IDREF's to BeanReader. At the moment, round tripping break when cycles exist.
</li>
<li>
Add testcase for the BeanReader(SAXParser) and BeanReader(XMLReader). They should behave
the same in all cases.
</li>
- </ul>
- </section>
-
- <section name="Medium priority">
- <ul>
<li>
- <b>Fixed</b>Using \n as default and now shows a warning when an invalid space character is used.<br/> Adding a check to only accept valid characters as lineEndings, so parsers actually won't choke on the output xml.
- BeanWriter should have a setEndOfLine() method to allow configurable EOL strings, defaulting to "\n"
- </li>
+ <strong>Create test cases based on real xml examples.</strong>
+ This should help to shake out any problems and help to find out how the design can be improved.
+ These should also be used as a basis for improved documentation.
+ </li>
<li>
- Create a SAXWriter class in the io package that takes a bean and writes to a SAX ContentHandler
- rather that outputting textual XML like BeanWriter does.
- This will allow Betwixt to work nicely in XML pipelining environments like Cocoon and Jelly.
- </li>
+ <strong>Improve internal design.</strong>
+ Betwixt is hard to understand and hard to create patches for.
+ An improved internal design would help more people to contribute.
+ </li>
+ <li>
+ <strong>Improve test coverage.</strong>
+ Run test coverage tool and improve coverage of key functionality.
+ </li>
+ <li>
+ <strong>Allow customization for update from .betwixt file</strong>
+ Add updater attribute that allows the updater to be specified for an elements.
+ This should also allow updaters to be ignored for certain properties.
+ </li>
</ul>
- </section>
+ </subsection>
+
+ <subsection name="Medium priority">
+ <ul>
+ <li>
+ <strong>Handle empty elements better.</strong>
+ Add option not to write empty elements. This is required to correctly write some kinds of xml.
+ The RSS full round tripping will only work with this functionality.
+ </li>
+ <li>
+ <strong>Create design documentation</strong>
+ This will help people understand the betwixt design.
+ </li>
+ <li>
+ <strong>Add verification for all xml writing tests.</strong>
+ At the moment, most of the xml writing tests do not test the output fully.
+ Need to add comparisons against reference xml documents.
+ </li>
+ <li>
+ <strong>Improve mapping for swing components</strong>
+ Swing classes have lots and lots of properties.
+ Java 1.4 does a better job of persistance than betwixt for class that have lots of properties.
+ </li>
+ <li>
+ <strong>Binary Data Elements</strong>
+ Some properties should not be treated as beans and therefore mapped to a element graph.
+ These should be converted to body text of binary data.
+ A mechanism similar to BeanUtils.ConvertUtils might work.
+ For example, if you have a colormodel that get's written (an array with a lot of
+ numbers and an xml-element per array element) betwixt will spend ages converting
+ it bit by bit.
+ </li>
+ <li>
+ <strong>Improved Support For Interfaces</strong>
+ </li>
+ <li>
+ <strong>Customizable ID/IDREF Mapping</strong>
+ Add per element customization for ID/IDREF mappings.
+ Extra attributes will be added to .betwixt file that specify the ID/IDREF names.
+ </li>
+ </ul>
+ </subsection>
- <section name="Low priority">
+ <subsection name="Low priority">
<ul>
<li>
Create a W3C DOM implementation that acts as a facade on top of beans to allow beans to
@@ -86,8 +161,34 @@
either use betwixt to do everything or you use digester to specify rules. It'd be nice
to be able to mix and match.
</li>
+ <li>
+ Create utility methods in BeanWriter to write stuff like prologs and doctype definitions to the
+ stream.
+ </li>
+ <li>
+ Create a funky image for the betwixt home page.
+ </li>
</ul>
- </section>
+ </subsection>
+
+ <subsection name='Completed (Since Last Release)'>
+ <ul>
+ <li>
+ <b>Fixed</b>Using \n as default and now shows a warning when an invalid space character is used.<br/> Adding a check to only accept valid characters as lineEndings, so parsers actually won't choke on the output xml.
+ BeanWriter should have a setEndOfLine() method to allow configurable EOL strings, defaulting to "\n"
+ </li>
+ <li>
+ Create a SAXWriter class in the io package that takes a bean and writes to a SAX ContentHandler
+ rather that outputting textual XML like BeanWriter does.
+ This will allow Betwixt to work nicely in XML pipelining environments like Cocoon and Jelly.
+ </li>
+ <li>
+ <b>Fixed.</b> digester.peek() was giving warning. Now checking if it still has something to peek.
+ Currently betwixt causes digester to output a warning '[WARN] Digester - -Empty stack (returning null)'.
+ We should patch the way betwixt uses digester to avoid this warning message.
+ </li>
+ </ul>
+ </subsection>
</section>
</body>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>