je/docs/java/com/sleepycat/persist/model/PersistentProxy.html
2021-06-06 13:46:45 -04:00

356 lines
14 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_151) on Tue Oct 31 17:36:47 EDT 2017 -->
<title>PersistentProxy (Oracle - Berkeley DB Java Edition API)</title>
<meta name="date" content="2017-10-31">
<link rel="stylesheet" type="text/css" href="../../../../style.css" title="Style">
<script type="text/javascript" src="../../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="PersistentProxy (Oracle - Berkeley DB Java Edition API)";
}
}
catch(err) {
}
//-->
var methods = {"i0":6,"i1":6};
var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]};
var altColor = "altColor";
var rowColor = "rowColor";
var tableTab = "tableTab";
var activeTableTab = "activeTableTab";
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/PersistentProxy.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Berkeley DB Java Edition</b><br><font size=\"-1\"> version 7.5.11</font>
</div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../com/sleepycat/persist/model/PrimaryKey.html" title="annotation in com.sleepycat.persist.model"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?com/sleepycat/persist/model/PersistentProxy.html" target="_top">Frames</a></li>
<li><a href="PersistentProxy.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">com.sleepycat.persist.model</div>
<h2 title="Interface PersistentProxy" class="title">Interface PersistentProxy&lt;T&gt;</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>public interface <span class="typeNameLabel">PersistentProxy&lt;T&gt;</span></pre>
<div class="block">Implemented by a proxy class to represent the persistent state of a
(non-persistent) proxied class. Normally classes that are outside the scope
of the developer's control must be proxied since they cannot be annotated,
and because it is desirable to insulate the stored format from changes to
the instance fields of the proxied class. This is useful for classes in the
standard Java libraries, for example.
<p><code>PersistentProxy</code> objects are not required to be thread-safe. A
single thread will create and call the methods of a given <code>PersistentProxy</code> object.</p>
<p>There are three requirements for a proxy class:</p>
<ol>
<li>It must implement the <code>PersistentProxy</code> interface.</li>
<li>It must be specified as a persistent proxy class in the entity model.
When using the <a href="../../../../com/sleepycat/persist/model/AnnotationModel.html" title="class in com.sleepycat.persist.model"><code>AnnotationModel</code></a>, a proxy class is indicated by the
<a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a> annotation with the <a href="../../../../com/sleepycat/persist/model/Persistent.html#proxyFor--"><code>Persistent.proxyFor()</code></a>
property.</li>
<li>It must be explicitly registered by calling <a href="../../../../com/sleepycat/persist/model/EntityModel.html#registerClass-java.lang.Class-"><code>EntityModel.registerClass(java.lang.Class)</code></a> before opening the store.</li>
</ol>
<p>In order to serialize an instance of the proxied class before it is
stored, an instance of the proxy class is created. The proxied instance is
then passed to the proxy's <a href="../../../../com/sleepycat/persist/model/PersistentProxy.html#initializeProxy-T-"><code>initializeProxy</code></a> method.
When this method returns, the proxy instance contains the state of the
proxied instance. The proxy instance is then serialized and stored in the
same way as for any persistent object.</p>
<p>When an instance of the proxy object is deserialized after it is
retrieved from storage, its <a href="../../../../com/sleepycat/persist/model/PersistentProxy.html#convertProxy--"><code>convertProxy()</code></a> method is called. The
instance of the proxied class returned by this method is then returned as a
field in the persistent instance.</p>
<p>For example:</p>
<pre class="code">
import java.util.Locale;
@Persistent(proxyFor=Locale.class)
class LocaleProxy implements PersistentProxy&lt;Locale&gt; {
String language;
String country;
String variant;
private LocaleProxy() {}
public void initializeProxy(Locale object) {
language = object.getLanguage();
country = object.getCountry();
variant = object.getVariant();
}
public Locale convertProxy() {
return new Locale(language, country, variant);
}
}</pre>
<p>The above definition allows the <code>Locale</code> class to be used in any
persistent class, for example:</p>
<pre class="code">
@Persistent
class LocalizedText {
String text;
Locale locale;
}</pre>
<p>A proxied class may not be used as a superclass for a persistent class or
entity class. For example, the following is not allowed.</p>
<pre class="code">
@Persistent
class LocalizedText extends Locale { // NOT ALLOWED
String text;
}</pre>
<p>A proxy for proxied class P does not handle instances of subclasses of P.
To proxy a subclass of P, a separate proxy class is needed.</p>
<p>Several <a href="Entity.html#proxyTypes">built in proxy types</a>
are used implicitly. An application defined proxy will be used instead of a
built-in proxy, if both exist for the same proxied class.</p>
<p>With respect to class evolution, a proxy instance is no different than
any other persistent instance. When using a <a href="../../../../com/sleepycat/persist/raw/RawStore.html" title="class in com.sleepycat.persist.raw"><code>RawStore</code></a> or <a href="../../../../com/sleepycat/persist/evolve/Converter.html" title="class in com.sleepycat.persist.evolve"><code>Converter</code></a>, only the raw data of the proxy instance will be visible. Raw
data for the proxied instance never exists.</p>
<p>Currently a proxied object may not contain a reference to itself. For
simple proxied objects such as the Locale class shown above, this naturally
won't occur. But for proxied objects that are containers -- the built-in
Collection and Map classes for example -- this can occur if the container is
added as an element of itself. This should be avoided. If an attempt to
store such an object is made, an <code>IllegalArgumentException</code> will be
thrown.</p>
<p>Note that a proxy class may not be a subclass of an entity class.</p></div>
<dl>
<dt><span class="simpleTagLabel">Author:</span></dt>
<dd>Mark Hayes</dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method.summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr id="i0" class="altColor">
<td class="colFirst"><code><a href="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="type parameter in PersistentProxy">T</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/PersistentProxy.html#convertProxy--">convertProxy</a></span>()</code>
<div class="block">Returns a new proxied class instance to which the state of this proxy
instance has been copied.</div>
</td>
</tr>
<tr id="i1" class="rowColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/PersistentProxy.html#initializeProxy-T-">initializeProxy</a></span>(<a href="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="type parameter in PersistentProxy">T</a>&nbsp;object)</code>
<div class="block">Copies the state of a given proxied class instance to this proxy
instance.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method.detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="initializeProxy-java.lang.Object-">
<!-- -->
</a><a name="initializeProxy-T-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>initializeProxy</h4>
<pre>void&nbsp;initializeProxy(<a href="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="type parameter in PersistentProxy">T</a>&nbsp;object)</pre>
<div class="block">Copies the state of a given proxied class instance to this proxy
instance.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>object</code> - the proxied class instance.</dd>
</dl>
</li>
</ul>
<a name="convertProxy--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>convertProxy</h4>
<pre><a href="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="type parameter in PersistentProxy">T</a>&nbsp;convertProxy()</pre>
<div class="block">Returns a new proxied class instance to which the state of this proxy
instance has been copied.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the new proxied class instance.</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/PersistentProxy.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Berkeley DB Java Edition</b><br><font size=\"-1\"> version 7.5.11</font>
</div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../com/sleepycat/persist/model/PrimaryKey.html" title="annotation in com.sleepycat.persist.model"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?com/sleepycat/persist/model/PersistentProxy.html" target="_top">Frames</a></li>
<li><a href="PersistentProxy.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><font size=1>Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.</font> </small></p>
</body>
</html>