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