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 output.xml
Date Sun, 11 Apr 2004 10:53:49 GMT
rdonkin     2004/04/11 03:53:49

  Modified:    betwixt/xdocs tasks.xml
               betwixt/xdocs/guide binding.xml output.xml
  Log:
  Added documentation for options and CDATA encoding.
  
  Revision  Changes    Path
  1.28      +8 -0      jakarta-commons/betwixt/xdocs/tasks.xml
  
  Index: tasks.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/tasks.xml,v
  retrieving revision 1.27
  retrieving revision 1.28
  diff -u -r1.27 -r1.28
  --- tasks.xml	4 Apr 2004 11:04:03 -0000	1.27
  +++ tasks.xml	11 Apr 2004 10:53:49 -0000	1.28
  @@ -283,6 +283,14 @@
               <li>
   <strong>Added Support For Replacement Of Bad Characters</strong> to default
mapping of element names.
               </li>
  +            <li>
  +<strong>Added Options mechanism</strong> for communication behaviour hints
to optional
  +strategies.
  +            </li>
  +            <li>
  +<strong>CDATA encoding support</strong> add support for flexible coding of
body text as CDATA
  +sections (in addition to character escaping).
  +            </li>
           </ul>
       </subsection>
   </section>
  
  
  
  1.5       +64 -1     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.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- binding.xml	29 Feb 2004 21:58:36 -0000	1.4
  +++ binding.xml	11 Apr 2004 10:53:49 -0000	1.5
  @@ -476,6 +476,69 @@
           </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
  +to handle some parts of the binding process. This section contains some information
  +that may of of some use for those people. Help to create a more comprehensive guide
  +would be appreciated.
  +        </p>
  +        <subsection name='Using Options'>
  +            <p>
  +Options provide an extensible way for extra mapping information to be communicated
  +from the binding to those components executing the mapping. Each <code>Descriptor</code>
  +exposes an 
  +<a href='../apidocs/org/apache/commons/betwixt/Descriptor.html#getOptions()'>Options
property</a>.
  +This contains a set of values indexed by name (both are strings). These options can be
  +set programmatically during the binding. They can also be set through the <code>.betwixt</code>
  +file.
  +        </p>
  +            <p>
  +Setting option values through the <code>.betwixt</code> file is easy: just
add an 
  +<code>&lt;option&gt;</code> child element to an <code>&lt;element&gt;</code>
element.
  +For example, the <code>XMLBeanInfo</code> for the following betwixt file:
  +        </p>
  +<source>
  +<![CDATA[
  +<?xml version='1.0'?>
  +<info primitiveTypes="attribute">
  +	<element name='some-bean'>
  +		<element name='some-property' property='someProperty'>
  +			<option>
  +				<name>org.apache.commons.betwixt.example-one</name>
  +				<value>value-one</value>
  +			</option>
  +		</element>
  +		<element name='another-property' property='anotherProperty'>
  +			<option>
  +				<name>org.apache.commons.betwixt.example-two</name>
  +				<value>value-two</value>
  +			</option>
  +		</element>
  +	</element>
  +</info>
  +]]>
  +</source>
  +            <p>
  +will have the value <em>value-one</em> associated with the option name
  +<em>org.apache.commons.betwixt.example-one</em> in the options for the 
  +<code>some-property</code> descriptor and <em>value-two</em>
  +associated with <em>org.apache.commons.betwixt.example-two</em>
  +for <code>another-property</code>.
  +Note that the last value set for a particular option name is the one that
  +will be used.
  +        </p>
  +            <p>
  +The recommended convention for naming option's is to prefix with the reverse domain
  +name (the same convension that is used for the standard naming of packages). 
  +In any case, all option names beginning with <code>org.apache</code> should
be avoided since
  +these may be used by ASF products in the future.
  +        </p>
  +            <p>
  +At the moment, there is no support for inheritance of options (from parent to child)
  +through this may be considered later if there is sufficient demand.            
  +        </p>
  +    </subsection>
  +</section>
   </body>
   </document>
  
  
  
  1.2       +26 -1     jakarta-commons/betwixt/xdocs/guide/output.xml
  
  Index: output.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/guide/output.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- output.xml	4 Apr 2004 11:03:52 -0000	1.1
  +++ output.xml	11 Apr 2004 10:53:49 -0000	1.2
  @@ -76,8 +76,33 @@
           writer.setMixedContentEncodingStrategy(MixedContentEncodingStrategy.CDATA);
   </source>
               <p>
  -By default, Betwixt using escaping and produces no CDATA sections.
  +By default, Betwixt uses character escaping only. However, the default
  +strategy also supports per-property specification through
  +setting the appropriate <a href='binding.html#Using%20Options'>option</a>.
  +Setting the <code>org.apache.commons.betwixt.mixed-content-encoding</code>
  +option to <code>CDATA</code> will instruct the default strategy to wrap
  +the element's body text in a CDATA section.
  +For example, the following betwixt file fragment encodes the 
  +<code>some-property</code> element's body text as CDATA
  +(when the default strategy is used):
           </p>
  +<source>
  +<![CDATA[
  +<?xml version='1.0'?>
  +<info primitiveTypes="attribute">
  +	<element name='some-bean'>
  +        ...
  +		<element name='some-property' property='someProperty'>
  +			<option>
  +				<name>org.apache.commons.betwixt.mixed-content-encoding</name>
  +				<value>CDATA</value>
  +			</option>
  +		</element>
  +        ...
  +	</element>
  +</info>
  +]]>
  +</source>
       </subsection>
   </section>
   <section name='Pushing Results to SAX'>
  
  
  

---------------------------------------------------------------------
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