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 Wed, 01 Jan 2003 20:15:26 GMT
rdonkin     2003/01/01 12:15:26

  Modified:    betwixt/xdocs overview.xml todo.xml
  Log:
  RSS example instructions in the main documentation no longer work properly. They would need
reworking anyway for a release distribution as well as some improvements. So, I'm going to
remove the instructions from the main documentation and add a task to the to do list. Added
some simple read and write examples to the main documentation.
  
  Revision  Changes    Path
  1.7       +153 -22   jakarta-commons/betwixt/xdocs/overview.xml
  
  Index: overview.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/overview.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- overview.xml	30 Dec 2002 19:12:25 -0000	1.6
  +++ overview.xml	1 Jan 2003 20:15:26 -0000	1.7
  @@ -10,32 +10,15 @@
   <body>
   
   <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 <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>
  -    
  -<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>
  +    Probably the best way to get started is to look at some examples. 
  +    <a href='#simple-example'>Here</a> is some simple example code that reads
and writes a bean (together
  +    with some comments). It's a good place to start. 
  +    </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>
       
  @@ -198,6 +181,154 @@
   </section>
   
   <section name="Examples">
  +<a name="simple-example"/>
  +<subsection name='A Simple Example'>
  +    <p>
  +    This is a simple example to help those new to betwixt. It shows how a simple bean can
be converted to
  +    xml and back again. A round trip, no less!
  +    </p>
  +    <p>
  +    In order to run these simple examples, the classpath needs to contain Betwixt and all
it's 
  +    <a href='dependencies'>dependencies</a>. Note that any 
  +    <a href='http://java.sun.com/xml/jaxp/index.html'>JAXP (1.1 or later)</a>
compliant parser 
  +    can be used to replace xerces and xml-apis. JUnit is not required to run betwixt (but
is needed
  +    if you want to run the unit tests in CVS).
  +    </p>
  +    <p>
  +    This example is based around a very simple bean representing a person:
  +    
  +<source><![CDATA[
  +public class PersonBean {
  +    
  +    private String name;
  +    private int age;
  +    
  +    /** Need to allow bean to be created via reflection */
  +    public PersonBean() {}
  +    
  +    public PersonBean(String name, int age) {
  +        this.name = name;
  +        this.age = age;
  +    }
  +    
  +    public String getName() {
  +        return name;
  +    }
  +    
  +    public void setName(String name) {
  +        this.name = name;
  +    }	
  +    
  +    public int getAge() {
  +        return age;
  +    }
  +    
  +    public void setAge(int age) {
  +        this.age = age;
  +    }
  +    
  +    public String toString() {
  +        return "PersonBean[name='" + name + "',age='" + age + "']";
  +    }
  +}
  +]]></source>
  +    </p>
  +    <p>
  +    The basic usage pattern for writing beans using Betwixt is to create a BeanWriter,
configure it 
  +    and then pass a bean into the <code>write</code> method. Pretty easy. 
  +    </p>
  +    <p>
  +    Here's a simple application which converts a person bean to xml which is then sent
to <code>System.out</code>:
  +    
  +<source><![CDATA[
  +import java.io.StringWriter;
  +
  +import org.apache.commons.betwixt.io.BeanWriter;
  +
  +public class WriteExampleApp {
  +
  +    /** 
  +     * Create an example bean and then convert it to xml.
  +     */
  +    public static final void main(String [] args) throws Exception {
  +        
  +        // Start by preparing the writer
  +        // We'll write to a string 
  +        StringWriter outputWriter = new StringWriter(); 
  +        
  +        // Betwixt just writes out the bean as a fragment
  +        // So if we want well-formed xml, we need to add the prolog
  +        outputWriter.write("<?xml version='1.0' ?>");
  +        
  +        // Create a BeanWriter which writes to our prepared stream
  +        BeanWriter beanWriter = new BeanWriter(outputWriter);
  +        
  +        // Configure betwixt
  +        // For more details see java docs or later in the main documentation
  +        beanWriter.getXMLIntrospector().setAttributesForPrimitives(false);
  +        beanWriter.setWriteIDs(false);
  +        beanWriter.enablePrettyPrint();
  +        
  +        // Write example bean as base element 'person'
  +        beanWriter.write("person", new PersonBean("John Smith", 21));
  +        
  +        // Write to System.out
  +        // (We could have used the empty constructor for BeanWriter 
  +        // but this way is more instructive)
  +        System.out.println(outputWriter.toString());
  +    }
  +}
  +
  +]]></source>
  +    </p>
  +    <p>
  +    Ths basic usage pattern for reading beans is only a little more complex. This time,
you need to
  +    create a BeanReader, configure it, register the bean classes that the xml will be mapped
to and 
  +    then parse should be called.
  +    </p>
  +    <p>
  +    Here's a simple application that converts some xml to a person bean. The bean is then
converted
  +    to string and the result sent to <code>System.out</code>:
  +    
  +<source><![CDATA[
  +import java.io.StringReader;
  +
  +import org.apache.commons.betwixt.io.BeanReader;
  +
  +public class ReadExampleApp {
  +    
  +    public static final void main(String args[]) throws Exception{
  +        
  +        // First construct the xml which will be read in
  +        // For this example, read in from a hard coded string
  +        StringReader xmlReader = new StringReader(
  +                    "<?xml version='1.0' ?><person><age>25</age><name>James
Smith</name></person>");
  +        
  +        // Now convert this to a bean using betwixt
  +        // Create BeanReader
  +        BeanReader beanReader  = new BeanReader();
  +        
  +        // Configure the reader
  +        // If you're round-tripping, make sure that the configurations are compatible!
  +        beanReader.getXMLIntrospector().setAttributesForPrimitives(false);
  +        beanReader.setMatchIDs(false);
  +        
  +        // Register beans so that betwixt knows what the xml is to be converted to
  +        // Since the element mapped to a PersonBean isn't called the same, 
  +        // need to register the path as well
  +        beanReader.registerBeanClass("person", PersonBean.class);
  +        
  +        // Now we parse the xml
  +        PersonBean person = (PersonBean) beanReader.parse(xmlReader);
  +        
  +        // send bean to system out
  +        System.out.println(person);
  +    }
  +    
  +}
  +]]></source>
  +    </p>
  +</subsection>
   <subsection name='A Rich Site Summary Mapping'>
   
       <p>In the RSS example from Digester there's a bean which matches this pattern.</p>
  
  
  
  1.22      +14 -5     jakarta-commons/betwixt/xdocs/todo.xml
  
  Index: todo.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/todo.xml,v
  retrieving revision 1.21
  retrieving revision 1.22
  diff -u -r1.21 -r1.22
  --- todo.xml	30 Dec 2002 22:54:55 -0000	1.21
  +++ todo.xml	1 Jan 2003 20:15:26 -0000	1.22
  @@ -45,10 +45,6 @@
                   <strong>Investigate Swing XML'ization Issues</strong>
                   Investigate and document. <em>(MVDB will probably need to handle
this.)</em>
               </li>
  -            <li>
  -                <strong>Add read and write examples</strong>
  -                Add simple read and write examples to getting started section.
  -            </li>
           </ul>
       </subsection>
       
  @@ -105,12 +101,21 @@
               This should also allow updaters to be ignored for certain properties.
           </li>
           <li>
  -            <strong>Add dynabeans support</strong> 
  +            <strong>Add dynabeans support.</strong> 
               Dynabeans are a feature of <code>commons-beanutils</code> that
allows data in non-beans to be
               wrapped into pseudo-beans. If betwixt supported dynabeans then you could do
cool stuff like 
               SQL -&gt; DynaBeans -&gt; XML. Probably a good way to do this would
be to ensure that all property
               intrspection is done by dyanbeans-aware methods of beanutils.
           </li>
  +        <li>
  +            <strong>Update RSS example application.</strong>
  +            The original betwixt documentation made use of a good example application based
on RSS.
  +            Unfortunately, this no longer works since the build was updated to maven.
  +            The instructions and means of running are linked to the CVS version.
  +            New instructions - and probably movement of some of the code - is needed to
support
  +            a release distribution. The example also needs some more work - better java
docs and also
  +            more features.
  +        </li>
          </ul>
       </subsection>
       
  @@ -207,6 +212,10 @@
                   <strong>Upgrade To Latest Dependencies</strong>
                   Check that betwixt works with the latest versions of the dependent 
                   Replace all references to deprecated methods. 
  +            </li>
  +            <li>
  +                <strong>Add read and write examples</strong>
  +                Add simple read and write examples to getting started section.
               </li>
           </ul>
       </subsection>
  
  
  

--
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