| <html><head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
| <title>2. Salient Features</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA User's Guide"><link rel="up" href="ref_guide_slice.html" title="Chapter 12. Distributed Persistence"><link rel="prev" href="ref_guide_slice.html" title="Chapter 12. Distributed Persistence"><link rel="next" href="slice_configuration.html" title="3. Usage"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2. Salient Features</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_slice.html">Prev</a> </td><th width="60%" align="center">Chapter 12. | |
| Distributed Persistence | |
| </th><td width="20%" align="right"> <a accesskey="n" href="slice_configuration.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Features and Limitations"></a>2. Salient Features</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="Features and Limitations.html#d0e30020">2.1. Transparency</a></span></dt><dt><span class="section"><a href="Features and Limitations.html#d0e30028">2.2. Custom Distribution Policy</a></span></dt><dt><span class="section"><a href="Features and Limitations.html#d0e30057">2.3. Heterogeneous Database</a></span></dt><dt><span class="section"><a href="Features and Limitations.html#d0e30062">2.4. Parallel Execution</a></span></dt><dt><span class="section"><a href="Features and Limitations.html#d0e30067">2.5. Distributed Query</a></span></dt><dt><span class="section"><a href="Features and Limitations.html#d0e30101">2.6. Targeted Query</a></span></dt><dt><span class="section"><a href="Features and Limitations.html#d0e30118">2.7. Distributed Transaction</a></span></dt><dt><span class="section"><a href="Features and Limitations.html#collocation_constraint">2.8. Collocation Constraint</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e30020"></a>2.1. Transparency</h3></div></div></div><p> | |
| The existing application or the persistent domain model requires | |
| <span class="emphasis"><em>no change</em></span> to upgrade from a single database | |
| to a distributed database environment. | |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e30028"></a>2.2. Custom Distribution Policy</h3></div></div></div><p> | |
| User application decides how the newly persistent instances be | |
| distributed across the database slices. The data | |
| distribution policy across the slices may be based on the attribute | |
| of the data itself. For example, all Customer whose first name begins with | |
| character 'A' to 'M' will be stored in one slice while names | |
| beginning with 'N' to 'Z' will be stored in another slice. | |
| </p><p> | |
| This custom data distribution policy is specified by implementing | |
| <code class="classname">org.apache.openjpa.slice.DistributionPolicy</code> | |
| interface by the user application. | |
| </p><p> | |
| Slice tracks the original database for existing instances. When | |
| an application issues a query, the resultant instances can be loaded | |
| from different slices. This tracking is important as subsequent | |
| update to any of these instances is committed to the appropriate | |
| original database slice. | |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | |
| You can find the original slice of an instance <code class="code">pc</code> by | |
| the static utility method | |
| <code class="methodname">SlicePersistence.getSlice(pc)</code>. | |
| This method returns the slice identifier string associated with the | |
| given <span class="emphasis"><em>managed</em></span> instance. If the instance is not | |
| being managed then the method return null because any unmanaged or | |
| detached instance is not associated with any slice. | |
| </p></div><p> | |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>Currently, there is no provision for migrating an | |
| existing instance from one slice to another. | |
| </div><p> | |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e30057"></a>2.3. Heterogeneous Database</h3></div></div></div><p> | |
| Each slice can be configured independently with its own JDBC | |
| driver and other connection parameters. Hence the target database | |
| environment can constitute of heterogeneous databases. | |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e30062"></a>2.4. Parallel Execution</h3></div></div></div><p> | |
| All database operations such as query, commit or flush operates | |
| in parallel across the database slices. The execution threading | |
| policy is configurable. | |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e30067"></a>2.5. Distributed Query</h3></div></div></div><p> | |
| The queries are executed across all slices and the results are | |
| merged into a single list. The query result that includes | |
| <code class="code">ORDER BY</code> clause are sorted correctly by merging | |
| results from each individual slice. | |
| </p> | |
| The queries that specify an aggregate projection such as | |
| <code class="code">COUNT()</code>, <code class="code">MAX()</code>, <code class="code">MIN()</code> | |
| and <code class="code">SUM()</code> | |
| are correctly evaluated <span class="emphasis"><em>only if</em></span> they | |
| return a single result. | |
| <p> | |
| </p><p> | |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3> | |
| The aggregate operation <code class="code">AVG()</code> is not supported. | |
| </div><p> | |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e30101"></a>2.6. Targeted Query</h3></div></div></div><p> | |
| You can target the query only to a subset of slices rather than | |
| all slices by setting a <span class="emphasis"><em>hint</em></span>. The hint key | |
| <code class="code">openjpa.hint.slice.Target</code> is set on any query and | |
| hint value is | |
| comma-separated list of slice identifiers. The following | |
| example shows how to target a query only to slice <code class="code">"One"</code> | |
| </p><pre class="programlisting"> | |
| EntityManager em = ...; | |
| em.getTransaction().begin(); | |
| String hint = "openjpa.hint.slice.Target"; | |
| Query query = em.createQuery("SELECT p FROM PObject").setHint(hint, "One"); | |
| List result = query.getResultList(); | |
| // verify that each instance is originaing from the given slice | |
| for (Object pc : result) { | |
| String sliceOrigin = SlicePersistence.getSlice(pc); | |
| assertTrue ("One", sliceOrigin); | |
| } | |
| </pre><p> | |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e30118"></a>2.7. Distributed Transaction</h3></div></div></div><p> | |
| The database slices participate in a global transaction provided | |
| each slice is configured with a XA-complaint JDBC driver, even | |
| when the persistence unit is configured for <code class="code">RESOURCE_LOCAL</code> | |
| transaction. | |
| </p><p> | |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3> | |
| If any of the configured slices is not XA-complaint <span class="emphasis"><em>and</em></span> | |
| the persistence unit is configured for <code class="code">RESOURCE_LOCAL</code> | |
| transaction then each slice is committed without any two-phase | |
| commit protocol. If commit on any slice fails, then atomic nature of | |
| the transaction is not ensured. | |
| </div><p> | |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="collocation_constraint"></a>2.8. Collocation Constraint</h3></div></div></div><p> | |
| No relationship can exist across database slices. In O-R mapping parlance, | |
| this condition translates to the limitation that the closure of an object graph must be | |
| <span class="emphasis"><em>collocated</em></span> in the same database. | |
| For example, consider a domain model where Person relates to Adress. | |
| Person X refers to Address A while Person Y refers to Address B. | |
| Collocation Constraint means that <span class="emphasis"><em>both</em></span> X and A | |
| must be stored in the same | |
| database slice. Similarly Y and B must be stored in a single slice. | |
| </p><p> | |
| Slice, however, helps to maintain collocation constraint automatically. | |
| The instances in the closure set of any newly persistent instance | |
| reachable via cascaded relationship is stored in the same slice. | |
| The user-defined distribution policy requires to supply the slice | |
| for the root instance only. | |
| </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_slice.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_slice.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="slice_configuration.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12. | |
| Distributed Persistence | |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 3. Usage</td></tr></table></div></body></html> |