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 2004/08/27 23:13:36 UTC
cvs commit: jakarta-commons/betwixt/xdocs/guide binding.xml start.xml
rdonkin 2004/08/27 14:13:36
Modified: betwixt/xdocs tasks.xml
betwixt/xdocs/guide binding.xml start.xml
Log:
Documentation for multi mapping document support. Contributed by Brian Pugh.
Revision Changes Path
1.34 +5 -1 jakarta-commons/betwixt/xdocs/tasks.xml
Index: tasks.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/tasks.xml,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- tasks.xml 23 Aug 2004 19:33:58 -0000 1.33
+++ tasks.xml 27 Aug 2004 21:13:36 -0000 1.34
@@ -189,7 +189,11 @@
<li><strong>Improved introspection for interfaces</strong> superinterface
properties now checked.</li>
<li><strong>Attribute suppression</strong> - Betwixt now allows the
- expression of certain values to be suppressed through a custom strategy.</li>
+ expression of certain values to be suppressed through a custom strategy.</li>
+ <li><strong>Custom Dot Betwixt Documents</strong> - custom dot betwixt
+ documents can be passed in directly.</li>
+ <li><strong>Multi mapping</strong> documents allowing several mappings to be
+ specified within a single document.</li>
</ul>
</subsection>
<subsection name='0.6'>
1.8 +144 -0 jakarta-commons/betwixt/xdocs/guide/binding.xml
Index: binding.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/guide/binding.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- binding.xml 13 Jul 2004 21:34:48 -0000 1.7
+++ binding.xml 27 Aug 2004 21:13:36 -0000 1.8
@@ -513,6 +513,150 @@
</p>
</subsection>
</section>
+ <section name='Multi Mapping'>
+ <subsection name='Custom Dot Betwixt Documents'>
+ <p>
+There are occasions when it proves useful to be able to override the standard
+loading behaviour for <code>.betwixt</code> mapping file. For example, this is
+one way in which multiple mapping for the same object can be supported (but see
+later sections for more sophisticated solutions to this problem).
+ </p>
+ <p>
+Betwixt supports this by providing writing and reading methods which allow
+an <code>InputSource</code> specifying a <code>.betwixt</code> document to be passed in.
+For example:
+ </p>
+ <source>
+<![CDATA[
+ StringReader dotBetwixtDocument = new StringReader(
+ "<?xml version='1.0' ?>" +
+ "<info>" +
+ " <element name='address'>" +
+...
+ " </element>" +
+ "</info>");
+
+ BeanReader reader = new BeanReader();
+ reader.registerBeanClass(new InputSource(dotBetwixtDocument), Address.class);
+ Address address = reader.parse(in);
+]]>
+ </source>
+ <p>
+parses the input document using the mapping specified in the string whilst:
+ </p>
+ <source>
+<![CDATA[
+ StringReader reader = new StringReader(
+ "<?xml version='1.0' ?>" +
+ "<info>" +
+ " <element name='address'>" +
+...
+ " </element>" +
+ "</info>");
+
+
+ BeanWriter writer;
+...
+ writer.write(bean, new InputSource(reader));
+]]>
+ </source>
+ <p>
+writes out a bean according to the mapping given in the string.
+ </p>
+ </subsection>
+ <subsection name='Multi Mapping Document Format'>
+ <p>
+This xml document format extends the <code>.betwixt</code> vocabulary so that several
+different classes mapping can be registered by a single document.
+The mapping file format is an intuitive extension to the standard .betwixt format.
+The root elements is <code><betwixt-config></code> which contains one or more
+<code><class></code> elements. Each of these specifies a class and contains
+a mapping definition for that class (as found in a standard dot betwixt document).
+ </p>
+ <p>
+For example:
+ </p>
+<source>
+<![CDATA[
+ <?xml version="1.0"?>
+ <betwixt-config>
+ <!--name of the class to map -->
+ <class name="org.some.package.MyClass">
+ <!-- standard definations (same as in standard .betwixt file) -->
+ <element name="repository-registration-result">
+ <element name="repository-id" property="repositoryId"/>
+ <element name="id-mapping" property="idMapping" class="org.some.package.SomeOtherClass"/>
+ <element name="status" property="status"/>
+ <element name="exception" property="exception"/>
+ <element name="primary-luid" property="primaryLuid"/>
+ <addDefaults add-properties='false'/>
+ </element>
+ </class>
+ ...
+ <!--additional class mappings -->
+ <class>
+ ...
+ </class>
+ ...
+ </betwixt-config>
+]]>
+ </source>
+ <p>
+Multi mappings are used directly to register multiple mappings with a single introspector.
+For example,
+ </p>
+ <source>
+<![CDATA[
+ String MAPPING = "<?xml version='1.0'?>" +
+ " <betwixt-config>" +
+ " <class name='org.apache.commons.betwixt.PartyBean'>" +
+ " <element name='party'>" +
+...
+ " </class>" +
+...
+ " </betwixt-config>";
+ BeanReader beanReader = new BeanReader();
+ beanReader.registerMultiMapping(new InputSource(new StringReader(MAPPING)));
+ ...
+ PartyBean result = (PartyBean)beanReader.parse(xmlReader);
+]]>
+ </source>
+ <p>
+registers all mappings in the file then reads beans according to those settings.
+The following does something similar for writing:
+ </p>
+<source>
+<![CDATA[
+ String MAPPING = "<?xml version='1.0'?>" +
+ " <betwixt-config>" +
+ " <class name='org.apache.commons.betwixt.PartyBean'>" +
+ " <element name='party'>" +
+...
+ " </class>" +
+...
+ " </betwixt-config>";
+ BeanWriter beanWriter = new BeanWriter(outputWriter);
+...
+ beanWriter.getXMLIntrospector().register(new InputSource(new StringReader(MAPPING)));
+ beanWriter.write(partyBean);
+]]>
+ </source>
+ </subsection>
+ <subsection name='Multiple Mappings For The Same Object'>
+ <p>
+Betwixt maps an entire object graph. So, though it might see (at first) that specifying
+a custom dot betwixt is all that's required, for all (but the most simple cases)
+several mappings must be specified to map the graph corrected. This is where multi mapping
+documents become very useful.
+ </p>
+ <p>
+A common usage pattern for this problem is to use one <code>XMLIntrospector</code>
+for each of the different ways that the mappings should be done and register the mappings
+through a multi mapping file. All the reader and writers for that particular type can
+then share the same introspector.
+ </p>
+ </subsection>
+</section>
<section name='(Brief) Guide To Creating Custom Strategy Plugins'>
<p>
It is common for users of Betwixt to need to develop their own custom strategies
1.4 +3 -1 jakarta-commons/betwixt/xdocs/guide/start.xml
Index: start.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/guide/start.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- start.xml 13 Jun 2004 21:32:49 -0000 1.3
+++ start.xml 27 Aug 2004 21:13:36 -0000 1.4
@@ -95,7 +95,9 @@
<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>
+ then the default introspection rules are used. (Note that there are also various
+ more advanced ways to vary this rule. For more details see
+ <a href='binding.html#Multi%20Mapping'>multi mapping</a> for more details)</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' ?>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org