public interface PersistentProxy<T>
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 proxied class may not be used as a superclass for a persistent class or entity class. For example, the following is not allowed.
@Persistent class LocalizedText extends Locale { // NOT ALLOWED String text; }
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.
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 RawStore
or Converter
, only the raw data of the proxy instance will be visible. Raw
data for the proxied instance never exists.
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 IllegalArgumentException
will be
thrown.
Note that a proxy class may not be a subclass of an entity class.
Modifier and Type | Method | Description |
---|---|---|
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.
|
void initializeProxy(T object)
object
- the proxied class instance.T convertProxy()
Copyright (c) 1996, 2020 Oracle and/or its affiliates. All rights reserved.