commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject cvs commit: jakarta-commons/betwixt/xdocs overview.xml todo.xml
Date Mon, 23 Dec 2002 22:51:51 GMT
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 &amp;quot;demo.rss&amp;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>&lt;addDefaults&gt;</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>&lt;hide&gt;</code> element which allows
one or more properties to be 
  +    hidden. Also note that the <code>&lt;element&gt;</code> and 
  +    <code>&lt;attribute&gt;</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>&lt;info&gt;</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>&lt;element&gt;</code> or <code>&lt;attribute&gt;</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:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message