Author: fancy
Date: Mon Jan 26 19:49:32 2009
New Revision: 737799
URL: http://svn.apache.org/viewvc?rev=737799&view=rev
Log:
OPENJPA-861 Update the manual for XML column support for MySQL
committing patch provided by Milosz Tylenda
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml?rev=737799&r1=737798&r2=737799&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml Mon Jan
26 19:49:32 2009
@@ -2472,10 +2472,33 @@
</primary>
</indexterm>
<para>
-DB2, Oracle and SQLServer support XML column types and
+Some databases support XML column types and
XPath queries and indexes over these columns. OpenJPA supports mapping of an
-entity property mapped to an XML column.
+entity property mapped to an XML column on the following databases and their
+minimum versions.
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+DB2 9
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+MySQL 5.1.30
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Oracle 9
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+SQLServer 2005
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
Annotate the entity property using the XMLValueHandler strategy:
</para>
@@ -2491,25 +2514,35 @@
</programlisting>
<para>
The entity property class is required to have
-jaxb binding annotations. This is produced when the classes are generated
-from an XML schema using the jaxb generator XJC.Ensure that
<classname>@XmlRootElement</classname>
-appears in the root class. In some case this annotation needs to be added
manually if it is missing.
+JAXB binding annotations. You can generate property class from an XML schema
by using
+the <literal>xjc</literal> generator from the
+<ulink url="https://jaxb.dev.java.net/";>JAXB reference implementation</ulink>.
+The <literal>xjc</literal> will generate the
+class along with the required annotations. Ensure that
<classname>@XmlRootElement</classname>
+appears in the root class. In some cases this annotation needs to be added
manually.
+ </para>
+ <para>
+The entity property class is required to have getter and setter methods for
all its
+fields. By default, the <literal>xjc</literal> will not generate setter
+methods for collections but you can force it to do so by using the
+<ulink
url="https://jaxb2-commons.dev.java.net/collection-setter-injector/";>collection
+setter injector plugin</ulink>.
</para>
<para>
-The jaxb jar files must be on the application classpath (jaxb-api.jar,
+The JAXB jar files must be on the application classpath (jaxb-api.jar,
jaxb-impl.jar, jsr173_1.0_api.jar or equivalent).
</para>
<para>
-EJB Query path expressions can navigate into the mapped class and its
+JPQL path expressions can navigate into the mapped class and its
subfields to any level.
</para>
<para>
-The path expression is rewritten into an equivalent XPATH expression using SQL
+The path expression is rewritten into an equivalent XPath expression using SQL
XML functions.
</para>
<para>
-The path expression must be single valued. Path expressions over XML
-mapped classes can only be used in WHERE as an operand to a simple predicate
+The path expression must be single-valued. Path expressions over XML
+mapped classes can only be used in the WHERE clause as an operand to a simple
predicate
(= <> < > >= <=).
</para>
<para>
@@ -2518,7 +2551,7 @@
<itemizedlist>
<listitem>
<para>
-an input to a EJB query scalar function
+an input to a JPQL scalar function
</para>
</listitem>
<listitem>
@@ -2533,22 +2566,22 @@
</listitem>
<listitem>
<para>
-used in the FROM , GROUP BY, HAVING, ORDER BY clauses
+used in the FROM, GROUP BY, HAVING, ORDER BY clauses
</para>
</listitem>
</itemizedlist>
<para>
-XML schema must not contain namespace declarations. The EJB query path
+XML schema must not contain namespace declarations. The JPQL path
expressions can not refer to Java fields generated from XML ANY type or
XML mixed element types.
</para>
<para>
-The datatype generated by JAXB must be a valid EJB query type
-to use the property in an EJB query predicate.
+The data type generated by JAXB must be a valid type
+to use the property in a JPQL predicate.
</para>
<para>
Shown below is a sample XML schema <link
linkend="ref_guide_xmlmapping_myaddress">myaddress.xsd</link>,
-in which the JPA entity Order has <classname><shipAddress></classname>
persistent field that maps to an XML column.
+in which the JPA entity Order has <classname>shipAddress</classname>
persistent field that maps to an XML column.
</para>
<example id="ref_guide_xmlmapping_myaddress">
<title>
@@ -2608,11 +2641,12 @@
Java classes <link linkend="ref_guide_xmlmapping_address">Address</link>,
<link linkend="ref_guide_xmlmapping_usaaddress">USAAddress</link> and
<link linkend="ref_guide_xmlmapping_canaddress">CANAddress</link>
-are produced using jaxb XJC generator from myaddress schema.
+are produced from <literal>myaddress</literal> schema by using the
+<literal>xjc</literal> generator.
</para>
<example id="ref_guide_xmlmapping_address">
<title>
- Address.Java
+ Address.java
</title>
<programlisting>
...
@@ -2714,7 +2748,7 @@
</example>
<example id="ref_guide_xmlmapping_createorder">
<title>
- Showing creation of Order Entity having shipAddress mapped to
XML column
+ Showing creation of Order entity having shipAddress mapped to
XML column
</title>
<programlisting>
...
@@ -2734,9 +2768,9 @@
...
</programlisting>
</example>
- <example id="ref_guide_xmlmapping_ejbquery">
+ <example id="ref_guide_xmlmapping_jpqlquery">
<title>
- Sample EJB Queries for XML Column mapping
+ Sample JPQL queries for XML column mapping
</title>
<programlisting>
. select o from Order o where o.shipAddress.city = "San Jose" or
@@ -2746,7 +2780,7 @@
. select o.shipAddress.city from Order o (INVALID)
-. select o from Order o where o.shipAddress.street = "San Jose"
(INVALID multi valued)
+. select o from Order o where o.shipAddress.street = "San Jose"
(INVALID multi-valued)
</programlisting>
</example>
</section>
