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 2003/08/14 23:25:43 UTC
cvs commit: jakarta-commons/betwixt/xdocs/guide examples.xml
rdonkin 2003/08/14 14:25:43
Added: betwixt/xdocs/guide examples.xml
Log:
Split Overview into separate documents in guide directory.
Revision Changes Path
1.1 jakarta-commons/betwixt/xdocs/guide/examples.xml
Index: examples.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Examples</title>
<author email="jstrachan@apache.org">James Strachan</author>
</properties>
<body>
<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>
<source><![CDATA[
public class Channel
public Item[] getItems();
public void addItem(Item item);
}
]]></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>
<source><![CDATA[public class Foo {
public Collection getPeople();
public void addPerson(Person person);
}]]></source>
<p>Though these two beans do match</p>
<source><![CDATA[public class Foo {
public Collection getPersonCollection();
public void addPerson(Person person);
}
public class Foo {
public Iterator getPersonIterator();
public void addPerson(Person person);
}
]]></source>
<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>
<td width="50%" align="center"><b>Composite getter method</b></td>
<td width="50%" align="center"><b>Adder method</b></td>
</tr>
<tr>
<td width="50%" align="center">getChildren()</td>
<td width="50%" align="center">addChild()</td>
</tr>
<tr>
<td width="50%" align="center">getPersonList()</td>
<td width="50%" align="center">addPerson()</td>
</tr>
<tr>
<td width="50%" align="center">getItems()</td>
<td width="50%" align="center">addItem()</td>
</tr>
<tr>
<td width="50%" align="center">getChannels()</td>
<td width="50%" align="center">addChannel()</td>
</tr>
<tr>
<td width="50%" align="center">getSheep()</td>
<td width="50%" align="center">addSheep()</td>
</tr>
</table>
</subsection>
</section>
</body>
</document>