1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<!--NewPage--> 3<HTML> 4<HEAD> 5<!-- Generated by javadoc (build 1.6.0_03) on Mon Apr 12 16:25:50 EDT 2010 --> 6<TITLE> 7PersistentProxy (Oracle - Berkeley DB Java API) 8</TITLE> 9 10<META NAME="date" CONTENT="2010-04-12"> 11 12<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../style.css" TITLE="Style"> 13 14<SCRIPT type="text/javascript"> 15function windowTitle() 16{ 17 if (location.href.indexOf('is-external=true') == -1) { 18 parent.document.title="PersistentProxy (Oracle - Berkeley DB Java API)"; 19 } 20} 21</SCRIPT> 22<NOSCRIPT> 23</NOSCRIPT> 24 25</HEAD> 26 27<BODY BGCOLOR="white" onload="windowTitle();"> 28<HR> 29 30 31<!-- ========= START OF TOP NAVBAR ======= --> 32<A NAME="navbar_top"><!-- --></A> 33<A HREF="#skip-navbar_top" title="Skip navigation links"></A> 34<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 35<TR> 36<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 37<A NAME="navbar_top_firstrow"><!-- --></A> 38<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 39 <TR ALIGN="center" VALIGN="top"> 40 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 41 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 42 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 43 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/PersistentProxy.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 44 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 45 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 46 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 47 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 48 </TR> 49</TABLE> 50</TD> 51<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 52<b>Berkeley DB</b><br><font size="-1"> version 4.8.30</font></EM> 53</TD> 54</TR> 55 56<TR> 57<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 58 <A HREF="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><B>PREV CLASS</B></A> 59 <A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html" title="annotation in com.sleepycat.persist.model"><B>NEXT CLASS</B></A></FONT></TD> 60<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 61 <A HREF="../../../../index.html?com/sleepycat/persist/model/PersistentProxy.html" target="_top"><B>FRAMES</B></A> 62 <A HREF="PersistentProxy.html" target="_top"><B>NO FRAMES</B></A> 63 <SCRIPT type="text/javascript"> 64 <!-- 65 if(window==top) { 66 document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 67 } 68 //--> 69</SCRIPT> 70<NOSCRIPT> 71 <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> 72</NOSCRIPT> 73 74 75</FONT></TD> 76</TR> 77<TR> 78<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 79 SUMMARY: NESTED | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD> 80<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 81DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD> 82</TR> 83</TABLE> 84<A NAME="skip-navbar_top"></A> 85<!-- ========= END OF TOP NAVBAR ========= --> 86 87<HR> 88<!-- ======== START OF CLASS DATA ======== --> 89<H2> 90<FONT SIZE="-1"> 91com.sleepycat.persist.model</FONT> 92<BR> 93Interface PersistentProxy<T></H2> 94<HR> 95<DL> 96<DT><PRE>public interface <B>PersistentProxy<T></B></DL> 97</PRE> 98 99<P> 100Implemented by a proxy class to represent the persistent state of a 101 (non-persistent) proxied class. Normally classes that are outside the scope 102 of the developer's control must be proxied since they cannot be annotated, 103 and because it is desirable to insulate the stored format from changes to 104 the instance fields of the proxied class. This is useful for classes in the 105 standard Java libraries, for example. 106 107 <p><code>PersistentProxy</code> objects are not required to be thread-safe. A 108 single thread will create and call the methods of a given <code>PersistentProxy</code> object.</p> 109 110 <p>There are three requirements for a proxy class:</p> 111 <ol> 112 <li>It must implement the <code>PersistentProxy</code> interface.</li> 113 <li>It must be specified as a persistent proxy class in the entity model. 114 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 115 <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> 116 property.</li> 117 <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> 118 </ol> 119 120 <p>In order to serialize an instance of the proxied class before it is 121 stored, an instance of the proxy class is created. The proxied instance is 122 then passed to the proxy's <A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html#initializeProxy(T)"><CODE>initializeProxy</CODE></A> method. 123 When this method returns, the proxy instance contains the state of the 124 proxied instance. The proxy instance is then serialized and stored in the 125 same way as for any persistent object.</p> 126 127 <p>When an instance of the proxy object is deserialized after it is 128 retrieved from storage, its <A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html#convertProxy()"><CODE>convertProxy()</CODE></A> method is called. The 129 instance of the proxied class returned by this method is then returned as a 130 field in the persistent instance.</p> 131 132 <p>For example:</p> 133 <pre class="code"> 134 import java.util.Locale; 135 136 @Persistent(proxyFor=Locale.class) 137 class LocaleProxy implements PersistentProxy<Locale> { 138 139 String language; 140 String country; 141 String variant; 142 143 private LocaleProxy() {} 144 145 public void initializeProxy(Locale object) { 146 language = object.getLanguage(); 147 country = object.getCountry(); 148 variant = object.getVariant(); 149 } 150 151 public Locale convertProxy() { 152 return new Locale(language, country, variant); 153 } 154 }</pre> 155 156 <p>The above definition allows the <code>Locale</code> class to be used in any 157 persistent class, for example:</p> 158 <pre class="code"> 159 @Persistent 160 class LocalizedText { 161 String text; 162 Locale locale; 163 }</pre> 164 165 <p>A proxied class may not be used as a superclass for a persistent class or 166 entity class. For example, the following is not allowed.</p> 167 <pre class="code"> 168 @Persistent 169 class LocalizedText extends Locale { // NOT ALLOWED 170 String text; 171 }</pre> 172 173 <p>A proxy for proxied class P does not handle instances of subclasses of P. 174 To proxy a subclass of P, a separate proxy class is needed.</p> 175 176 <p>Several <a href="Entity.html#proxyTypes">built in proxy types</a> 177 are used implicitly. An application defined proxy will be used instead of a 178 built-in proxy, if both exist for the same proxied class.</p> 179 180 <p>With respect to class evolution, a proxy instance is no different than 181 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 182 data for the proxied instance never exists.</p> 183 184 <p>Currently a proxied object may not contain a reference to itself. For 185 simple proxied objects such as the Locale class shown above, this naturally 186 won't occur. But for proxied objects that are containers -- the built-in 187 Collection and Map classes for example -- this can occur if the container is 188 added as an element of itself. This should be avoided. If an attempt to 189 store such an object is made, an <code>IllegalArgumentException</code> will be 190 thrown.</p> 191 192 <p>Note that a proxy class may not be a subclass of an entity class.</p> 193<P> 194 195<P> 196<HR> 197 198<P> 199 200<!-- ========== METHOD SUMMARY =========== --> 201 202<A NAME="method_summary"><!-- --></A> 203<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 204<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 205<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 206<B>Method Summary</B></FONT></TH> 207</TR> 208<TR BGCOLOR="white" CLASS="TableRowColor"> 209<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 210<CODE> <A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="type parameter in PersistentProxy">T</A></CODE></FONT></TD> 211<TD><CODE><B><A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html#convertProxy()">convertProxy</A></B>()</CODE> 212 213<BR> 214 Returns a new proxied class instance to which the state of this proxy 215 instance has been copied.</TD> 216</TR> 217<TR BGCOLOR="white" CLASS="TableRowColor"> 218<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 219<CODE> void</CODE></FONT></TD> 220<TD><CODE><B><A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html#initializeProxy(T)">initializeProxy</A></B>(<A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="type parameter in PersistentProxy">T</A> object)</CODE> 221 222<BR> 223 Copies the state of a given proxied class instance to this proxy 224 instance.</TD> 225</TR> 226</TABLE> 227 228<P> 229 230<!-- ============ METHOD DETAIL ========== --> 231 232<A NAME="method_detail"><!-- --></A> 233<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 234<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 235<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2"> 236<B>Method Detail</B></FONT></TH> 237</TR> 238</TABLE> 239 240<A NAME="initializeProxy(java.lang.Object)"><!-- --></A><A NAME="initializeProxy(T)"><!-- --></A><H3> 241initializeProxy</H3> 242<PRE> 243void <B>initializeProxy</B>(<A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="type parameter in PersistentProxy">T</A> object)</PRE> 244<DL> 245<DD>Copies the state of a given proxied class instance to this proxy 246 instance. 247<P> 248<DD><DL> 249</DL> 250</DD> 251</DL> 252<HR> 253 254<A NAME="convertProxy()"><!-- --></A><H3> 255convertProxy</H3> 256<PRE> 257<A HREF="../../../../com/sleepycat/persist/model/PersistentProxy.html" title="type parameter in PersistentProxy">T</A> <B>convertProxy</B>()</PRE> 258<DL> 259<DD>Returns a new proxied class instance to which the state of this proxy 260 instance has been copied. 261<P> 262<DD><DL> 263</DL> 264</DD> 265</DL> 266<!-- ========= END OF CLASS DATA ========= --> 267<HR> 268 269 270<!-- ======= START OF BOTTOM NAVBAR ====== --> 271<A NAME="navbar_bottom"><!-- --></A> 272<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> 273<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 274<TR> 275<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 276<A NAME="navbar_bottom_firstrow"><!-- --></A> 277<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 278 <TR ALIGN="center" VALIGN="top"> 279 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 280 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 281 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 282 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/PersistentProxy.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 283 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 284 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 285 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 286 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 287 </TR> 288</TABLE> 289</TD> 290<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 291<b>Berkeley DB</b><br><font size="-1"> version 4.8.30</font></EM> 292</TD> 293</TR> 294 295<TR> 296<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 297 <A HREF="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><B>PREV CLASS</B></A> 298 <A HREF="../../../../com/sleepycat/persist/model/PrimaryKey.html" title="annotation in com.sleepycat.persist.model"><B>NEXT CLASS</B></A></FONT></TD> 299<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 300 <A HREF="../../../../index.html?com/sleepycat/persist/model/PersistentProxy.html" target="_top"><B>FRAMES</B></A> 301 <A HREF="PersistentProxy.html" target="_top"><B>NO FRAMES</B></A> 302 <SCRIPT type="text/javascript"> 303 <!-- 304 if(window==top) { 305 document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 306 } 307 //--> 308</SCRIPT> 309<NOSCRIPT> 310 <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> 311</NOSCRIPT> 312 313 314</FONT></TD> 315</TR> 316<TR> 317<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 318 SUMMARY: NESTED | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD> 319<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 320DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD> 321</TR> 322</TABLE> 323<A NAME="skip-navbar_bottom"></A> 324<!-- ======== END OF BOTTOM NAVBAR ======= --> 325 326<HR> 327<font size=1>Copyright (c) 1996-2009 Oracle. All rights reserved.</font> 328</BODY> 329</HTML> 330