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 writing.xml
Date Mon, 08 Sep 2003 13:58:53 GMT
rdonkin     2003/09/08 06:58:53

  Modified:    betwixt/xdocs/guide binding.xml writing.xml
  Log:
  Documentation for ClassNormalizer
  
  Revision  Changes    Path
  1.3       +30 -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.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- binding.xml	16 Aug 2003 06:30:24 -0000	1.2
  +++ binding.xml	8 Sep 2003 13:58:53 -0000	1.3
  @@ -339,6 +339,36 @@
   property is specified then the bean can be written and then read back.
       </p>
   </subsection>
  +        <subsection name='Introspection And Normalization'>
  +            <p>
  +When an Object is introspected by the <code>XMLIntrospector</code>, the class
is examined and 
  +an <code>XMLBeanInfo</code> created based upon it. But there are occasions
when some variation 
  +is needed - for example when reading or writing Entity Beans or Proxy implementations.
  +        </p>
  +            <p> 
  +Betwixt provides the <code>ClassNormalizer</code> strategy class as a way to
allow users to customise
  +the process by which Betwixt works out which Class should be introspected for a given Object.

  +The default implementation simply supplies the Class of the Object.
  +But by setting the <code>classNormalizer</code> property of <code>XMLIntrospector</code>,

  +a custom implementation can be used instead.
  +        </p>
  +            <p>
  +Betwixt supplies a second implementation called <code>ListedClassNormalizer</code>.
  +This contains a list of classes to match together with the Class which should be returned

  +when the Class is matched. 
  +        </p>
  +            <p>
  +For example, take a class <code>FaceImpl</code> that implements an interface
<code>IFace</code>.
  +Betwixt will introspect every instance of <code>FaceImpl</code> as if it just
implemented
  +<code>IFace</code> by use of the following code:             
  +        </p>
  +<code><pre>
  +        XMLIntrospector introspector = ...;
  +        ListedClassNormalizer classNormalizer = new ListedClassNormalizer();
  +        classNormalizer.addSubstitution( IFace.class );
  +        introspector.setClassNormalizer( classNormalizer );
  +</pre></code>
  +    </subsection>
   </section>
   
       <section name='Converting Objects And Primitives To Strings (And Back Again)'>
  
  
  
  1.2       +50 -0     jakarta-commons/betwixt/xdocs/guide/writing.xml
  
  Index: writing.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/guide/writing.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- writing.xml	14 Aug 2003 21:26:31 -0000	1.1
  +++ writing.xml	8 Sep 2003 13:58:53 -0000	1.2
  @@ -22,6 +22,56 @@
   .betwixt file.
                   </p>
       </subsection>
  +        <subsection name='Writing Entity Beans'>
  +            <p>
  +Entity beans are a kind of Enterprise Java Bean. For more details see the
  +<a href='http://java.sun.com/j2ee/'>J2EE</a> specification. They are a common
way to persist data.
  +When dealing with an entity bean, you usually deal with the remote interface rather than
the
  +concrete implementation. There is no gaurantee that the class presented by the container
will be
  +the class your created to provide the bean's functionality. 
  +Indeed, <code>Proxy</code> implementations are 
  +one common way in which the remote interfaces are implemented. 
  +        </p>
  +            <p>
  +This causes some difficulties for Betwixt. Betwixt (by default) will introspect the actual
implementation
  +presented by the container.
  +Fortunately, the normalization mechanism described <a href='binding#Introspection%20And%20Normalization'>here</a>

  +can be used to allow betwixt to introspect the actual interface (rather than the implementation).
  +        </p>
  +            <p>
  +There are two different strategies that can be used. The first is to create a special 
  +<code>ClassNormalizer</code> which extracts an interface from a <code>Proxy</code>.
  +(Thanks to Christoph Gaffga for suggesting this.)
  +For example:
  +        </p>
  +<code><pre>
  +        XMLIntrospector introspector = ...;
  +        introspector.setClassNormalizer( new ClassNormalizer() {
  +                public Class normalize( Class clazz ) {
  +                    if ( Proxy.isProxyClass(clazz) &amp;&amp; clazz.getInterfaces().length
>0 ) {
  +                        return clazz.getInterfaces()[0];
  +                    }
  +                    return clazz;
  +                }
  +            });
  +</pre></code>
  +            <p>
  +Of course, this will only work if your J2EE implementation uses <code>Proxy</code>
classes to implement
  +it's Entity Beans.
  +        </p>
  +            <p>
  +The alternative is to use a <code>ListedClassNormalizer</code> and register
all remote interfaces.
  +For example:
  +        </p>
  +<code><pre>
  +        XMLIntrospector introspector = ...;
  +        ListedClassNormalizer classNormalizer = new ListedClassNormalizer();
  +        classNormalizer.addSubstitution( MyRemoteInterfaceOne.class );
  +        classNormalizer.addSubstitution( MyRemoteInterfaceTwo.class );
  +        ...
  +        introspector.setClassNormalizer( classNormalizer );
  +</pre></code>
  +    </subsection>
   </section>
   </body>
   </document>
  
  
  

Mime
View raw message