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 reading.xml
Date Thu, 21 Aug 2003 22:43:24 GMT
rdonkin     2003/08/21 15:43:24

  Modified:    betwixt/xdocs tasks.xml
               betwixt/xdocs/guide reading.xml
  Log:
  Documentation for bean creation chains.
  
  Revision  Changes    Path
  1.21      +18 -0     jakarta-commons/betwixt/xdocs/tasks.xml
  
  Index: tasks.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/tasks.xml,v
  retrieving revision 1.20
  retrieving revision 1.21
  diff -u -r1.20 -r1.21
  --- tasks.xml	16 Aug 2003 06:30:24 -0000	1.20
  +++ tasks.xml	21 Aug 2003 22:43:24 -0000	1.21
  @@ -245,6 +245,12 @@
               but contains a special case that allows the default setting to round trip java.util.Date's

               without breaking compatibility.
               </li>
  +                <li>
  +<strong>Refactored creation of Bean For Elements In Reading</strong>
  +Factored out the code that creates beans for elements (when reading) into separates classes
uses the 
  +<em>Chain Of Responsibility</em> pattern. This allows users to hook into the
creation process and 
  +add their own custom creation steps or replace the defaults with new functionality.
  +            </li>
           </ul>
       </subsection>
   </section>
  @@ -368,6 +374,18 @@
                   <a href='guide/binding.html#Converting Dates (And Other Objects)'>the
guide</a>.
               </li>
           </ul>
  +    </subsection>
  +        <subsection name='Dependencies'>
  +            <p>
  +                <ul>
  +                    <li>
  +Upgraded <code>commons-beanutils</code> to <code>1.6.1</code>.
  +                </li>
  +                    <li>
  +Upgraded <code>commons-digester</code> to <code>1.5</code>.
  +                </li>
  +            </ul>
  +        </p>
       </subsection>
   </section>
   </body>
  
  
  
  1.2       +117 -0    jakarta-commons/betwixt/xdocs/guide/reading.xml
  
  Index: reading.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/guide/reading.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- reading.xml	14 Aug 2003 21:26:03 -0000	1.1
  +++ reading.xml	21 Aug 2003 22:43:24 -0000	1.2
  @@ -72,5 +72,122 @@
   </subsection>
   </section>
   
  +    <section name='Reading Beans - In Depth'>
  +    
  +        <subsection name='Understanding The Class Creation Chain'>
  +            <p>
  +Betwixt uses the <em>Chain Of Responsibility</em> pattern to decide the object
which should be created 
  +for a particular element. The standard chain contains <code>ChainedBeanCreator</code>s
which implement
  +functionality such as standard bean creation based on the expected type and the returning
of beans by ID.
  +This allows users to easily insert their own <code>ChainedBeanCreator</code>s
into the chain - or to 
  +replace the standard Betwixt chain completely.
  +        </p>
  +    </subsection>
  +    
  +        <subsection name='Customizing Bean Creation'>
  +            <p>
  +The chain used by the BeanReader is part of the <code>ReadConfiguration</code>
and is accessed via the 
  +BeanCreationChain property. For example the following sets a custom chain.
  +<code><pre>
  +        BeanCreationChain chain = MyBeanCreationChain();
  +        BeanReader reader = new BeanReader();
  +        ...
  +        reader.registerBeanClass("bean", Bean.class);
  +        reader.getReadConfiguration().setBeanCreationChain(chain);
  +        ...
  +        Bean bean = (Bean) reader.parse(in);
  +        ...
  +</pre></code>
  +        </p>
  +            <p>
  +Betwixt provides a standard (list-backed) chain called BeanCreationList. This provides
an easy methods to 
  +register your own <code>ChainedBeanCreator</code>. It also provides a factory
method which creates an instance
  +with the standard betwixt chain already set. For example, the following inserts a custom
in second place:
  +<code><pre>
  +        BeanCreationList chain = BeanCreationList.createStandardChain();
  +        BeanCreator creator = MyBeanCreator();
  +        chain.insertBeanCreator(1, creator);
  +</pre></code>
  +        </p>
  +            <p>
  +Another useful class is <code>ChainedBeanCreationFactory</code>. This contains
factory methods for the 
  +<code>BeanCreator</code>s used by Betwixt. This allows a user to easily mix
custom and standard creators.
  +        </p>
  +    </subsection>
  +    
  +        <subsection name='Example: Enums'>
  +            <p>
  +Herein is contained a practical example demonstrating how custom bean creation may be used.
  +        </p>
  +            <p>
  +A common java pattern is the use of strongly typed Enum classes. Let's say that you have
the following class:
  +<code><pre>
  +public class CompassPoint {
  +
  +    public static final CompassPoint NORTH = new CompassPoint("North");
  +    public static final CompassPoint SOUTH = new CompassPoint("South");
  +    public static final CompassPoint EAST = new CompassPoint("East");
  +    public static final CompassPoint WEST = new CompassPoint("West");
  +    
  +    private String name;
  +    
  +    private CompassPoint(String name) {
  +        this.name = name;
  +    }
  +    
  +    public String getName() {
  +        return name;
  +    }
  +}
  +</pre></code>
  +and you have a bean which you would like to map to xml and back using Betwixt. Betwixt
is bean-centric. 
  +It aims to make mapping beans easy. But, <code>CompassPoint</code> objects
are not beans and do not
  +have the empty constructors that Betwixt requires.
  +        </p>
  +            <p>
  +A good way to solve this problem is to create a custom BeanCreator which knows how to create
an enum
  +of the right type from the 'name' attribute value. For example:
  +<code><pre>
  +public class CompassPointEnumCreator implements ChainedBeanCreator {
  +    public Object create(ElementMapping mapping, ReadContext context, BeanCreationChain
chain) {
  +        if (CompassPoint.class.equals(mapping.getType())) {
  +            String value = mapping.getAttributes().getValue("name");
  +            if ("North".equals(value)) {
  +                return CompassPoint.NORTH;
  +            }
  +            if ("South".equals(value)) {
  +                return CompassPoint.SOUTH;
  +            }
  +            if ("East".equals(value)) {
  +                return CompassPoint.EAST;
  +            }
  +            if ("West".equals(value)) {
  +                return CompassPoint.WEST;
  +            }
  +        }
  +        return chain.create(mapping, context);
  +    }
  +}
  +</pre></code>
  +        </p>
  +            <p>
  +Once this class has been created, all that remains is to add this into the chain. In this
case,
  +it's probably most convenient to use the factory method to create a standard chain and
then insert
  +the BeanCreator at a suitable position:
  +<code><pre>
  +    BeanCreationList chain = BeanCreationList.createStandardChain();
  +    chain.insertBeanCreator(1, new EnumCreator());
  +    ...
  +    BeanReader reader = new BeanReader();
  +    reader.getXMLIntrospector().setAttributesForPrimitives(true);
  +    reader.getXMLIntrospector().setWrapCollectionsInElement(false);
  +    reader.getReadConfiguration().setBeanCreationChain(chain);
  +    ...
  +</pre></code>            
  +Now you're ready to start reading enums!
  +        </p>
  +    </subsection>
  +</section>
  +
   </body>
   </document>
  
  
  

Mime
View raw message