|
Berkeley DB Java Edition version 3.0.12 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface PersistentProxy<T>
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.
PersistentProxy
objects are not required to be thread-safe. A
single thread will create and call the methods of a given PersistentProxy
object.
There are three requirements for a proxy class:
PersistentProxy
interface.AnnotationModel
, a proxy class is indicated by the Persistent
annotation with the Persistent.proxyFor()
property.EntityModel.registerClass(java.lang.Class)
before opening the store.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 initializeProxy
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.
When an instance of the proxy object is deserialized after it is
retrieved from storage, its convertProxy()
method is called. The
instance of the proxied class returned by this method is then returned as a
field in the persistent instance.
For example:
import java.util.Locale; @Persistent(proxyFor=Locale.class) class LocaleProxy implements PersistentProxy<Locale> { 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); } }
The above definition allows the Locale
class to be used in any
persistent class, for example:
@Persistent class LocalizedText { String text; Locale locale; }
A proxy for proxied class P does not handle instances of subclasses of P. To proxy subclasses of P, a separate proxy class is needed.
Several built in proxy types are used implicitly. An application defined proxy will be used instead of a built-in proxy, if both exist for the same proxied class.
With respect to class evolution, a proxy instance is no different than
any other persistent instance. When using a ConversionStore
, RawStore
or Converter
, only the raw data of the proxy instance will
be visible. Raw data for the proxied instance never exists.
Generic Types
Special consideration is needed when the proxied class has generic type
parameters. The proxy class should have the same number of type parameters
as the proxied class. For example, a proxy class for HashMap<K,V>
might declare arrays of type K
and V
as shown below:
@Persistent(proxyFor=HashSet.class) class HashMapProxy<K,V> implements PersistentProxy<HashSet<K,V>> { private K[] keys; private V[] values; ... }
The type parameters of the proxy class and proxied class are linked by the Direct Persistence Layer to determine actual types. Knowing actual types is important for efficient class evolution, as described under Generic Types and Class Evolution.
Using the example of the proxy class above, imagine that a field in a
persistent class is declared with type HashMap<Integer,Color>
. The
Direct Persistence Layer can determine that the actual type arguments in the
field declaration, Integer
and Color
, are the types of the
keys
and values
arrays in the proxy class. The type
parameters K
and V
are the links between types in the proxy
class and types in the proxied class.
Method Summary | |
---|---|
T |
convertProxy()
Returns a new proxied class instance to which the state of this proxy instance has been copied. |
void |
initializeProxy(T object)
Copies the state of a given proxied class instance to this proxy instance. |
Method Detail |
---|
void initializeProxy(T object)
T convertProxy()
|
Berkeley DB Java Edition version 3.0.12 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |