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/guide binding.xml start.xml
Date Fri, 27 Aug 2004 21:13:36 GMT
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>&lt;betwixt-config&gt;</code> which contains
one or more
  +<code>&lt;class&gt;</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


Mime
View raw message