Apache
/
openjpa
mirror of https://github.com/apache/openjpa.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

OPENJPA-240 add XMLMapping documentation to ref_guide_mapping.xml 

Committing Catalina's openjpa-project.patch

git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@560330 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
David J. Wisneski 2007-07-27 17:38:24 +00:00
parent 8c1710ed63
commit 8586e0fef3
1 changed files with 3328 additions and 3032 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

296
openjpa-project/src/doc/manual/ref_guide_mapping.xml
View File

@ -2372,6 +2372,302 @@ supported by the database.
</itemizedlist>
</section>
</section>
<section id="ref_guide_xmlmapping">
<title>
XML Column Mapping
</title>
<indexterm zone="ref_guide_xmlmapping">
<primary>
mapping metadata
</primary>
<secondary>
xml column mapping
</secondary>
</indexterm>
<indexterm zone="ref_guide_xmlmapping">
<primary>
xml mapping column
</primary>
</indexterm>
<para>
DB2, Oracle and SQLServer support XML column types and
XPath queries and indexes over these columns.OpenJPA supports mapping of an
entity property mapped to an XML column.
</para>
<para>
Annotate the entity property using the XMLValueHandler strategy:
</para>
<programlisting>
@Persistent
@Strategy(&quot;org.apache.openjpa.jdbc.meta.strats.XMLValueHandler&quot;)
</programlisting>
<para>
The default fetch type is EAGER but can be changed to LAZY by using:
</para>
<programlisting>
@Persistence(fetch=FetchType.LAZY)
</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.
</para>
<para>
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
subfields to any level.
</para>
<para>
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
(= &lt;&gt; &lt; &gt; &gt;= &lt;=).
</para>
<para>
Path expressions over XML mapped fields can not be:
</para>
<itemizedlist>
<listitem>
<para>
an input to a EJB query scalar function
</para>
</listitem>
<listitem>
<para>
an operand of BETWEEN, IS NULL, LIKE or IN predicate
</para>
</listitem>
<listitem>
<para>
used to project out subfields in the SELECT clause
</para>
</listitem>
<listitem>
<para>
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
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.
</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>&lt;shipAddress&gt;</classname> persistent field that maps to an XML column.
</para>
<example id="ref_guide_xmlmapping_myaddress">
<title>
myaddress.xsd
</title>
<programlisting>
&lt;?xml version=&quot;1.0&quot; ?&gt;
&lt;xs:schema xmlns:xs=&quot;http://www.w3.org/2001/XMLSchema&quot; &gt;
&lt;xs:complexType name=&quot;Address&quot;&gt;
&lt;xs:sequence&gt;
&lt;xs:element name=&quot;Name&quot; type=&quot;xs:string&quot; /&gt;
&lt;xs:element name=&quot;Street&quot; type=&quot;xs:string&quot;
minOccurs=&quot;1&quot; maxOccurs=&quot;3&quot; /&gt;
&lt;xs:element name=&quot;City&quot; type=&quot;xs:string&quot; /&gt;
&lt;/xs:sequence&gt;
&lt;/xs:complexType&gt;
&lt;xs:complexType name=&quot;CAN_Address&quot;&gt;
&lt;xs:complexContent&gt;
&lt;xs:extension base=&quot;Address&quot;&gt;
&lt;xs:sequence&gt;
&lt;xs:element name=&quot;Province&quot; type=&quot;xs:string&quot; /&gt;
&lt;xs:element name=&quot;PostalCode&quot; type=&quot;xs:string&quot; /&gt;
&lt;/xs:sequence&gt;
&lt;/xs:extension&gt;
&lt;/xs:complexContent&gt;
&lt;/xs:complexType&gt;
&lt;xs:simpleType name=&quot;USPS_ZIP&quot;&gt;
&lt;xs:restriction base=&quot;xs:integer&quot;&gt;
&lt;xs:minInclusive value=&quot;01000&quot; /&gt;
&lt;xs:maxInclusive value=&quot;99999&quot; /&gt;
&lt;/xs:restriction&gt;
&lt;/xs:simpleType&gt;
&lt;xs:complexType name=&quot;USA_Address&quot;&gt;
&lt;xs:complexContent&gt;
&lt;xs:extension base=&quot;Address&quot;&gt;
&lt;xs:sequence&gt;
&lt;xs:element name=&quot;State&quot; type=&quot;xs:string&quot; /&gt;
&lt;xs:element name=&quot;ZIP&quot; type=&quot;USPS_ZIP&quot; /&gt;
&lt;/xs:sequence&gt;
&lt;/xs:extension&gt;
&lt;/xs:complexContent&gt;
&lt;/xs:complexType&gt;
&lt;xs:element name=&quot;MailAddress&quot; type=&quot;Address&quot; /&gt;
&lt;xs:element name=&quot;AddrCAN&quot; type=&quot;CAN_Address&quot;
substitutionGroup=&quot;MailAddress&quot; /&gt;
&lt;xs:element name=&quot;AddrUSA&quot; type=&quot;USA_Address&quot;
substitutionGroup=&quot;MailAddress&quot; /&gt;
&lt;/xs:schema&gt;
</programlisting>
</example>
<para>
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.
</para>
<example id="ref_guide_xmlmapping_address">
<title>
Address.Java
</title>
<programlisting>
...
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = &quot;Address&quot;, propOrder = {
&quot;name&quot;,
&quot;street&quot;,
&quot;city&quot;
})
public class Address {
@XmlElement(name = &quot;Name&quot;, required = true)
protected String name;
@XmlElement(name = &quot;Street&quot;, required = true)
protected List&lt;String&gt; street;
@XmlElement(name = &quot;City&quot;, required = true)
protected String city;
/**
* Getter and Setter methods.
*
*/
...
}
</programlisting>
</example>
<example id="ref_guide_xmlmapping_usaaddress">
<title>
USAAddress.java
</title>
<programlisting>
...
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = &quot;USA_Address&quot;, propOrder = {
&quot;state&quot;,
&quot;zip&quot;
})
public class USAAddress
extends Address
{
@XmlElement(name = &quot;State&quot;)
protected String state;
@XmlElement(name = &quot;ZIP&quot;)
protected int zip;
/**
* Getter and Setter methods.
*
*/
...
}
</programlisting>
</example>
<example id="ref_guide_xmlmapping_canaddress">
<title>
CANAddress.java
</title>
<programlisting>
...
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = &quot;CAN_Address&quot;, propOrder = {
&quot;province&quot;,
&quot;postalCode&quot;
})
public class CANAddress
extends Address
{
@XmlElement(name = &quot;Province&quot;)
protected String province;
@XmlElement(name = &quot;PostalCode&quot;)
protected String postalCode;
/**
* Getter and Setter methods.
*
*/
...
}
</programlisting>
</example>
<example id="ref_guide_xmlmapping_annorder">
<title>
Showing annotated Order entity with XML mapping strategy
</title>
<programlisting>
@Entity
public class Order {
@Id private into id;
@Persistent
@Strategy (&quot;org.apache.openjpa.jdbc.meta.strats.XMLValueHandler&quot;)
private Address shipAddress;
...
}
</programlisting>
</example>
<example id="ref_guide_xmlmapping_createorder">
<title>
Showing creation of Order Entity having shipAddress mapped to XML column
</title>
<programlisting>
...
myaddress.ObjectFactory addressFactory = new myaddress.ObjectFactory();
Customer c1 = new Customer();
c1.setCid( new Customer.CustomerKey(&quot;USA&quot;, 1) );
c1.setName(&quot;Harry's Auto&quot;);
Order o1 = new Order( 850, false, c1);
USAAddress addr1 = addressFactory.createUSAAddress();
addr1.setCity(&quot;San Jose&quot;);
addr1.setState(&quot;CA&quot;);
addr1.setZIP(new Integer(&quot;95141&quot;));
addr1.getStreet().add(&quot;12500 Monterey&quot;);
addr1.setName( c1.getName());
o1.setShipAddress(addr1);
em.persist(o1);
...
</programlisting>
</example>
<example id="ref_guide_xmlmapping_ejbquery">
<title>
Sample EJB Queries for XML Column mapping
</title>
<programlisting>
. select o from Order o where o.shipAddress.city = &quot;San Jose&quot; or
o.shipAddress.city = &quot;San Francisco&quot; (OK)
. select o.shipaAddress from Order o (OK)
. select o.shipAddress.city from Order o (INVALID)
. select o from Order o where o.shipAddress.street = &quot;San Jose&quot; (INVALID multi valued)
</programlisting>
</example>
</section>
</section>
<section id="ref_guide_mapping_limits">
<title>