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><option></code> child element to an <code><element></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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
