<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 1.2 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#d0e31264">2.1. Transparency</a></span></dt><dt><span class="section"><a href="features_and_limitations.html#d0e31272">2.2. Custom Distribution Policy</a></span></dt><dt><span class="section"><a href="features_and_limitations.html#d0e31301">2.3. Heterogeneous Database</a></span></dt><dt><span class="section"><a href="features_and_limitations.html#d0e31306">2.4. Parallel Execution</a></span></dt><dt><span class="section"><a href="features_and_limitations.html#d0e31311">2.5. Distributed Query</a></span></dt><dt><span class="section"><a href="features_and_limitations.html#d0e31345">2.6. Targeted Query</a></span></dt><dt><span class="section"><a href="features_and_limitations.html#d0e31362">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="d0e31264"></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="d0e31272"></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="d0e31301"></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="d0e31306"></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="d0e31311"></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="d0e31345"></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="d0e31362"></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-compliant 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-compliant <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> |