KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sleepycat > persist > model > PersistentProxy


1 /*-
2  * See the file LICENSE for redistribution information.
3  *
4  * Copyright (c) 2002,2006 Oracle. All rights reserved.
5  *
6  * $Id: PersistentProxy.java,v 1.12 2006/10/30 21:14:33 bostic Exp $
7  */
8
9 package com.sleepycat.persist.model;
10
11 import com.sleepycat.persist.evolve.Converter; // for javadoc
12 import com.sleepycat.persist.raw.RawStore; // for javadoc
13
14 /**
15  * Implemented by a proxy class to represent the persistent state of a
16  * (non-persistent) proxied class. Normally classes that are outside the scope
17  * of the developer's control must be proxied since they cannot be annotated,
18  * and because it is desirable to insulate the stored format from changes to
19  * the instance fields of the proxied class. This is useful for classes in the
20  * standard Java libraries, for example.
21  *
22  * <p>{@code PersistentProxy} objects are not required to be thread-safe. A
23  * single thread will create and call the methods of a given {@code
24  * PersistentProxy} object.</p>
25  *
26  * <p>There are three requirements for a proxy class:</p>
27  * <ol>
28  * <li>It must implement the <code>PersistentProxy</code> interface.</li>
29  * <li>It must be specified as a persistent proxy class in the entity model.
30  * When using the {@link AnnotationModel}, a proxy class is indicated by the
31  * {@link Persistent} annotation with the {@link Persistent#proxyFor}
32  * property.</li>
33  * <li>It must be explicitly registered by calling {@link
34  * EntityModel#registerClass} before opening the store.</li>
35  * </ol>
36  *
37  * <p>In order to serialize an instance of the proxied class before it is
38  * stored, an instance of the proxy class is created. The proxied instance is
39  * then passed to the proxy's {@link #initializeProxy initializeProxy} method.
40  * When this method returns, the proxy instance contains the state of the
41  * proxied instance. The proxy instance is then serialized and stored in the
42  * same way as for any persistent object.</p>
43  *
44  * <p>When an instance of the proxy object is deserialized after it is
45  * retrieved from storage, its {@link #convertProxy} method is called. The
46  * instance of the proxied class returned by this method is then returned as a
47  * field in the persistent instance.</p>
48  *
49  * <p>For example:</p>
50  * <pre class="code">
51  * import java.util.Locale;
52  *
53  * {@literal @Persistent(proxyFor=Locale.class)}
54  * class LocaleProxy implements {@literal PersistentProxy<Locale>} {
55  *
56  * String language;
57  * String country;
58  * String variant;
59  *
60  * private LocaleProxy() {}
61  *
62  * public void initializeProxy(Locale object) {
63  * language = object.getLanguage();
64  * country = object.getCountry();
65  * variant = object.getVariant();
66  * }
67  *
68  * public Locale convertProxy() {
69  * return new Locale(language, country, variant);
70  * }
71  * }</pre>
72  *
73  * <p>The above definition allows the {@code Locale} class to be used in any
74  * persistent class, for example:</p>
75  * <pre class="code">
76  * {@literal @Persistent}
77  * class LocalizedText {
78  * String text;
79  * Locale locale;
80  * }</pre>
81  *
82  * <p>A proxy for proxied class P does not handle instances of subclasses of P.
83  * To proxy subclasses of P, a separate proxy class is needed.</p>
84  *
85  * <p>Several {@link <a HREF="Entity.html#proxyTypes">built in proxy types</a>}
86  * are used implicitly. An application defined proxy will be used instead of a
87  * built-in proxy, if both exist for the same proxied class.</p>
88  *
89  * <p>With respect to class evolution, a proxy instance is no different than
90  * any other persistent instance. When using a {@link RawStore} or {@link
91  * Converter}, only the raw data of the proxy instance will be visible. Raw
92  * data for the proxied instance never exists.</p>
93  *
94  * @author Mark Hayes
95  */
96 public interface PersistentProxy<T> {
97
98     /**
99      * Copies the state of a given proxied class instance to this proxy
100      * instance.
101      */
102     void initializeProxy(T object);
103
104     /**
105      * Returns a new proxied class instance to which the state of this proxy
106      * instance has been copied.
107      */
108     T convertProxy();
109 }
110
Popular Tags