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 overview.xml todo.xml
Date Sun, 05 Jan 2003 15:47:45 GMT
rdonkin     2003/01/05 07:47:45

  Modified:    betwixt/src/java/org/apache/commons/betwixt
                        XMLIntrospector.java
               betwixt/xdocs overview.xml todo.xml
  Log:
  Improved XMLRegsitry documentation. Added a section on XMLRegistry to the main documentation
and improved java docs.
  
  Revision  Changes    Path
  1.15      +18 -0     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/XMLIntrospector.java
  
  Index: XMLIntrospector.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/XMLIntrospector.java,v
  retrieving revision 1.14
  retrieving revision 1.15
  diff -u -r1.14 -r1.15
  --- XMLIntrospector.java	5 Jan 2003 09:52:22 -0000	1.14
  +++ XMLIntrospector.java	5 Jan 2003 15:47:45 -0000	1.15
  @@ -151,10 +151,28 @@
           this.log = log;
       }
       
  +    /** 
  +     * <p>Get current registry implementation used.
  +     * The registry is checked to see if it has an <code>XMLBeanInfo</code>
for a class
  +     * before introspecting. 
  +     * After standard introspection is complete, the instance will be passed to the registry.</p>
  +     *
  +     * <p>This allows finely grained control over the caching strategy.
  +     * It also allows the standard introspection mechanism to be overridden on a per class
basis.</p>
  +     */
       public XMLBeanInfoRegistry getRegistry() {
           return registry;
       }
       
  +    /** 
  +     * <p>Set current registry implementation used.
  +     * The registry is checked to see if it has an <code>XMLBeanInfo</code>
for a class
  +     * before introspecting. 
  +     * After standard introspection is complete, the instance will be passed to the registry.</p>
  +     *
  +     * <p>This allows finely grained control over the caching strategy.
  +     * It also allows the standard introspection mechanism to be overridden on a per class
basis.</p>
  +     */
       public void setRegistry(XMLBeanInfoRegistry registry) {
           this.registry = registry;
       }
  
  
  
  1.10      +56 -2     jakarta-commons/betwixt/xdocs/overview.xml
  
  Index: overview.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/overview.xml,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- overview.xml	5 Jan 2003 10:23:07 -0000	1.9
  +++ overview.xml	5 Jan 2003 15:47:45 -0000	1.10
  @@ -72,8 +72,10 @@
   
   </section>
   
  -<section name="Customizing the mapping of a bean to XML">
  +<section name="Customizing the mapping of a bean to XML (basic)">
       
  +<subsection name=".betwixt files">
  +
       <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 
  @@ -132,7 +134,9 @@
   </element>
   </info>
   ]]></source>
  -    
  +
  +</subsection>
  +
   </section>
   
   <section name="Bean naming conventions">
  @@ -304,6 +308,56 @@
       any property that starts with the singular name. For example, it will match a plural
property called
       <code>FooBars</code> for a singular property called <code>FooBar</code>.

       </p>
  +</subsection>
  +
  +</section>
  +
  +<section name="Customizing the mapping of a bean to XML (advanced)">
  +
  +<subsection name="Caching and XMLRegistry">
  +    
  +    <p>
  +    Introspection is slow and so caching the results improves preformance. Though the writers

  +    and readers can - by nature - only be used safely in a single thread, a single 
  +    <code>XMLIntrospector</code> instance can be safely shared amongst multiple
threads. Sharing a
  +    single instance will improve performance by sharing it's <code>XMLBeanInfo</code>
cache.
  +    </p>
  +    
  +    <p>
  +    The <code>XMLBeanInfoRegistry</code> interface allows finely grained, pluggable
control over 
  +    the caching strategy used by a <code>XMLIntrospector</code>. The implementation
used can be set
  +    by passing an instance to <code>XMLIntrospector.setRegistry</code>.
  +    </p>
  +    
  +    <p>
  +    Before using the standard introspection techniques to create a new <code>XMLBeanInfo</code>
instance
  +    for a bean, the current <code>XMLBeanInfoRegistry</code> is first checked.
Only if the registry 
  +    does not return an <code>XMLBeanInfo</code> will a new one be created.
Once a new instance has been
  +    created by introspection, the <code>XMLBeanInfoRegistry</code> implementation
will be called so that
  +    the <code>XMLBeanInfo</code> can (if required) be cached.
  +    </p>
  +    
  +    <p>
  +    The default strategy caches everything and supports flushes. Betwixt contains an alternative

  +    implementation that does not cache anything. Users that require more sophisticated
caching 
  +    strategies should create custom implementations.
  +    </p>
  +    
  +    <p>
  +    The <code>XMLBeanInfoRegistry</code> can also be used to override the standard
introspection mechanism
  +    on a per class basis. The safest way to do this is to create a custom <code>XMLBeanInfoRegistry</code>

  +    implementation that pre-loads <code>XMLBeanInfo</code>'s for the required
classes. If flush is called, 
  +    the cache should be reset that it contains only those that it contained at the start.

  +    </p>
  +
  +</subsection>
  +
  +<subsection name="Other XMLIntrospector Settings">
  +    
  +    <p>
  +    Here are discussed the important settings that haven't been covered already.
  +    </p>
  +    
   </subsection>
   
   </section>
  
  
  
  1.25      +4 -4      jakarta-commons/betwixt/xdocs/todo.xml
  
  Index: todo.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/todo.xml,v
  retrieving revision 1.24
  retrieving revision 1.25
  diff -u -r1.24 -r1.25
  --- todo.xml	5 Jan 2003 10:26:31 -0000	1.24
  +++ todo.xml	5 Jan 2003 15:47:45 -0000	1.25
  @@ -24,10 +24,6 @@
                   Make sure that warnings are added about consequences of changing settings.
               </li>
               <li>
  -                <strong>Add XMLRegistry documentation. </strong>
  -                Add documentation about XMLRegistry to main documentation.
  -            </li>
  -            <li>
                   <strong>Improve Java Docs. </strong>
                   Go through java docs, add any which are missing, correct any mistakes etc.
               </li>
  @@ -224,6 +220,10 @@
                   This needs to be added to the main documentation.
                   Example code needs to be created.
                   This code can also be used for more test cases.
  +            </li>
  +            <li>
  +                <strong>Add XMLRegistry documentation. </strong>
  +                Add documentation about XMLRegistry to main documentation.
               </li>
           </ul>
       </subsection>
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message