public class ConfigurablePofContext extends Object implements PofContext, ClassLoaderAware, XmlConfigurable
PofContext
interface using information provided in a configuration file (or in a passed XML configuration).
For each user type supported by this POF context, it must be provided with:
The format of the configuration XML is as follows:
<pof-config> <user-type-list> .. <user-type> <type-id>53</type-id> <class-name>com.mycompany.data.Trade</class-name> <serializer> <class-name>com.tangosol.io.pof.PortableObjectSerializer</class-name> <init-params> <init-param> <param-type>int</param-type> <param-value>{type-id}</param-value> </init-param> </init-params> </serializer> </user-type> <user-type> <type-id>54</type-id> <class-name>com.mycompany.data.Position</class-name> </user-type> .. <include>file:/my-pof-config.xml</include> .. </user-type-list> <allow-interfaces>false</allow-interfaces> <allow-subclasses>false</allow-subclasses> </pof-config>For each user type, a user-type element must exist inside the user-type-list element. The user-type-list element contains up to three elements, in the following order:
Portable
annotation. If the former, a PortableObjectSerializer
will be used. If the later, a PofAnnotationSerializer
will be used.The optional include element allows user-type elements defined in another configuration XML to be added to the user type list. The value of this element is a locator string (either a valid path or URL) that specifies the location of the target PofContext configuration file. The user-type elements of the target file are imported verbatum; therefore, if the included elements contain explicit type identifiers, each identifier must be unique with respect to the the user type identifiers (either explicit or generated) defined within the including file. If the included user types do not contain explicit type identifiers, then the type identifiers will be based on the order in which the user types appear in the composite configuration file. Multiple include elements may be used within a single user-type-list element.
The ConfigurablePofContext is truly ClassLoader-aware. It is conceivable that the ConfigurablePofContext is loaded by the system ClassLoader (or some other relatively global ClassLoader), while the objects deserialized by the PofContext are loaded by an application-specific ClassLoader, such as is typical within an application server. The ConfigurablePofContext is designed to load the configuration, the POF-able object classes and the PofSerializer classes from within a specified ClassLoader context, and to pass the ClassLoader information on to the PofSerializer instances, just in case they are not loaded from within the application's ClassLoader context. In other words, the ConfigurablePofContext, its configuration, the PofSerializer classes and the POF-able classes can all be loaded by the same ClassLoader, or they can all be loaded by different ClassLoaders, so long as the configuration, the POF-able classes and the PofSerializer classes can be loaded by either the specified ClassLoader or by the ClassLoader that loaded the ConfigurablePofContext itself.
In order to be used by the ConfigurablePofContext, a PofSerializer implementation must provide a public constructor that accepts the parameters detailed by the init-params element. The parameter values, as specified by the param-value element, can specify one of the following substitutable values:
Once constructed, if the PofSerializer implements the XmlConfigurable interface, the setConfig
method is invoked, and it is passed the parameter XML information, transposed as described by transformInitParams
, and as described in the coherence-pof-config.xsd file.
Finally, if the PofSerializer implements the ClassLoaderAware interface and a ClassLoader has been specified, then the setContextClassLoader
method is invoked with the reference to the specified ClassLoader.
Conceptually, the identity of a ConfigurablePofContext is a combination of a configuration locator and a ClassLoader. The ClassLoader is used to resolve and load the configuration details whose location is specified by the configuration locator, and to load all of the classes specified by the configuration. To achieve acceptable performance, and to limit the redundant use of resources, the ConfigurablePofContext maintains a WeakHashMap keyed by ClassLoader, whose corresponding values are each a SafeHashMap keyed by configuration locator, whose corresponding values contain the data necessary to efficiently perform the operations prescribed by the PofContext interface.
Note: The configuration for the default constructor
can be specified using the tangosol.pof.config
system property.
Modifier and Type | Class and Description |
---|---|
protected static class |
ConfigurablePofContext.PofConfig
The information related to the configuration of a particular PofContext for a specific URI and ClassLoader.
|
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_RESOURCE
The name of the application resource that contains the default set of wire-format-to-object bindings.
|
static String |
PROPERTY_CONFIG
The name of the system property ("tangosol.pof.config") that can be used to override the location of the default POF configuration file.
|
protected static Class |
ROOT_LAMBDA_CLASS
Marker serving as the implicit root class for all lambdas.
|
Constructor and Description |
---|
ConfigurablePofContext()
Default constructor.
|
ConfigurablePofContext(ConfigurablePofContext that)
Copy constructor for a ConfigurablePofContext.
|
ConfigurablePofContext(String sLocator)
Create a ConfigurablePofContext that will load configuration information from the specified locator.
|
ConfigurablePofContext(XmlElement xml)
Create a ConfigurablePofContext that will use the passed configuration information.
|
Modifier and Type | Method and Description |
---|---|
protected static void |
appendDefaultSerializerToUserTypes(XmlElement xmlConfig)
Process <default-serializer> element from the specified xml configuration and append information about the serializer to each <user-type> element within <user-type-list> unless user type already has a serializer specified.
|
protected void |
checkNotInitialized()
Verify that the ConfigurablePofContext has not already been initialized.
|
protected ConfigurablePofContext.PofConfig |
createPofConfig()
Create a PofConfig object based on a configuration that was either provided as XML, or can be loaded from the specified (or default) URI using the provided ClassLoader.
|
Object |
deserialize(ReadBuffer.BufferInput in)
Deserialize an object from a ReadBuffer by reading its state using the specified BufferInput object.
|
protected void |
ensureInitialized()
Fully initialize the ConfigurablePofContext if it has not already been initialized.
|
Class |
getClass(int nTypeId)
Determine the class associated with the given user type identifier.
|
String |
getClassName(int nTypeId)
Determine the name of the class associated with the given user type identifier.
|
XmlElement |
getConfig()
Determine the current configuration of the object.
|
protected String |
getConfigLocation()
Obtain the location of the configuration that the ConfigurablePofContext used to configure itself.
|
ClassLoader |
getContextClassLoader()
Retrieve the context ClassLoader for this object.
|
protected int |
getInheritedUserTypeIdentifier(Class clz)
Helper method for determining the user type identifier associated with a given class that does not have a direct configured association.
|
protected ConfigurablePofContext.PofConfig |
getPofConfig()
Obtain the PofConfig that represents the initialized state of the ConfigurablePofContext.
|
PofSerializer |
getPofSerializer(int nTypeId)
Return a PofSerializer that can be used to serialize and deserialize an object of the specified user type to and from a POF stream.
|
int |
getUserTypeIdentifier(Class clz)
Determine the user type identifier associated with the given class.
|
int |
getUserTypeIdentifier(Object o)
Determine the user type identifier associated with the given object.
|
int |
getUserTypeIdentifier(String sClass)
Determine the user type identifier associated with the given class name.
|
protected int |
getUserTypeIdentifierInternal(Class clz)
Determine the user type identifier associated with the given class.
|
protected int |
getUserTypeIdentifierInternal(String sClass)
Determine the user type identifier associated with the given class name.
|
protected void |
initialize()
Bind the ConfigurablePofContext to a ClassLoader, resolving all class names, etc.
|
protected PofSerializer |
instantiateSerializer(XmlElement xmlSer, int nTypeId, Class clz)
Create a
PofSerializer from the provided XML serializer element. |
protected boolean |
isInitialized()
Determine if the ConfigurablePofContext has completed its initialization.
|
protected boolean |
isInterfaceAllowed()
Determine if the ConfigurablePofContext supports the configuration of user types by specifying an interface (instead of a class) for the Java type.
|
protected boolean |
isLambdaAllowed()
Determine if implicit root lambda class processing is allowed.
|
boolean |
isPreferJavaTime()
Return <c>true</c> if
PofReader.readObject(int) method should return the appropriate Java 8 date/time type, or <c>false</c> if a legacy date/time types should be returned in order to preserve backwards compatibility. |
boolean |
isReferenceEnabled()
Determine if Identity/Reference type support is enabled for this ConfigurablePofContext.
|
protected boolean |
isSubclassAllowed()
Determine if the ConfigurablePofContext supports the serialization of an object that is an instance of a sub-class of a configured type, but not actually an instance of a class of a configured type.
|
boolean |
isUserType(Class clz)
Determine if the given class is a user type known to this PofContext.
|
boolean |
isUserType(Object o)
Determine if the given object is of a user type known to this PofContext.
|
boolean |
isUserType(String sClass)
Determine if the class with the given name is a user type known to this PofContext.
|
protected Class |
loadClass(String sClass)
Find the specified class, return a Java Class object for it.
|
static void |
mergeIncludes(String sURI, XmlElement xmlConfig, ClassLoader loader)
Merge all included POF configuration files into the given xml configuration.
|
protected RuntimeException |
report(String sURI, int nTypeId, String sClass, Throwable e, String sText)
Assemble and throw an informative exception based on the passed details.
|
void |
serialize(WriteBuffer.BufferOutput out, Object o)
Serialize an object to a WriteBuffer by writing its state using the specified BufferOutput object.
|
void |
setConfig(XmlElement xml)
Specify the configuration for the object.
|
void |
setContextClassLoader(ClassLoader loader)
Specify the context ClassLoader for this object.
|
void |
setPreferJavaTime(boolean fPreferJavaTime)
Set the flag specifying if Java 8 date/time types (java.time.*) should be preferred over legacy types.
|
void |
setReferenceEnabled(boolean fReferenceEnabled)
Set the referenceEnabled flag.
|
String |
toString()
Return a description of this ConfigurablePofContext.
|
public static final String PROPERTY_CONFIG
The value of this property must be the name of a resource that contains an XML document with the structure defined in /coherence-pof-config.xsd (deployed in coherence.jar).
The default value for the "coherence.pof.config" system property is "coherence-pof-config.xml".
public static final String DEFAULT_RESOURCE
The default value for the resource name is "pof-config.xml". The default can be overriden by specifying a value for the tangosol.pof.config
system property.
protected static final Class ROOT_LAMBDA_CLASS
public ConfigurablePofContext()
Create a default ConfigurablePofContext that will load configuration information from the locator specified in DEFAULT_RESOURCE
.
public ConfigurablePofContext(String sLocator)
sLocator
- the locator that specifies the location of the PofContext configuration file; the locator is either a valid path or a URLpublic ConfigurablePofContext(XmlElement xml)
xml
- an XmlElement containing information in the format of a configuration file used by ConfigurablePofContextpublic ConfigurablePofContext(ConfigurablePofContext that)
that
- the ConfigurablePofContext to (shallow) copy frompublic XmlElement getConfig()
getConfig
in interface XmlConfigurable
public void setConfig(XmlElement xml)
Note that the configuration cannot be set after the ConfigurablePofContext is fully initialized.
setConfig
in interface XmlConfigurable
xml
- the XML configuration for the objectIllegalStateException
- if the ConfigurablePofContext is already fully initializedpublic ClassLoader getContextClassLoader()
getContextClassLoader
in interface ClassLoaderAware
Thread.getContextClassLoader()
public void setContextClassLoader(ClassLoader loader)
Note that the ConfigurablePofContext will fully initialize when it is provided a ClassLoader.
setContextClassLoader
in interface ClassLoaderAware
loader
- the context ClassLoader for this objectIllegalStateException
- if the ConfigurablePofContext is already fully initializedpublic void serialize(WriteBuffer.BufferOutput out, Object o) throws IOException
Note: Starting with Coherence 12.2.1 classes that need to designate an alternative object to be used by the Serializer when writing the object to the buffer should implement the SerializationSupport.writeReplace()
method.
serialize
in interface Serializer
out
- the BufferOutput with which to write the object's stateo
- the object to serializeIOException
- if an I/O error occurspublic Object deserialize(ReadBuffer.BufferInput in) throws IOException
Note: Starting with Coherence 12.2.1 classes that need to designate an alternative object to be returned by the Serializer after an object is deserialized from the buffer should implement the SerializationSupport.readResolve()
method.
deserialize
in interface Serializer
in
- the BufferInput with which to read the object's stateIOException
- if an I/O error occurspublic PofSerializer getPofSerializer(int nTypeId)
getPofSerializer
in interface PofContext
nTypeId
- the type identifier of the user type that can be serialized and deserialized using the returned PofSerializer; must be non-negativepublic int getUserTypeIdentifier(Object o)
getUserTypeIdentifier
in interface PofContext
o
- an instance of a user type; must not be nullpublic int getUserTypeIdentifier(Class clz)
getUserTypeIdentifier
in interface PofContext
clz
- a user type class; must not be nullpublic int getUserTypeIdentifier(String sClass)
getUserTypeIdentifier
in interface PofContext
sClass
- the name of a user type class; must not be nullpublic String getClassName(int nTypeId)
getClassName
in interface PofContext
nTypeId
- the user type identifier; must be non-negativepublic Class getClass(int nTypeId)
getClass
in interface PofContext
nTypeId
- the user type identifier; must be non-negativepublic boolean isUserType(Object o)
isUserType
in interface PofContext
o
- the object to test; must not be nullpublic boolean isUserType(Class clz)
isUserType
in interface PofContext
clz
- the class to test; must not be nullpublic boolean isUserType(String sClass)
isUserType
in interface PofContext
sClass
- the name of the class to test; must not be nullpublic boolean isPreferJavaTime()
PofReader.readObject(int)
method should return the appropriate Java 8 date/time type, or <c>false</c> if a legacy date/time types should be returned in order to preserve backwards compatibility.isPreferJavaTime
in interface PofContext
protected int getUserTypeIdentifierInternal(Class clz)
clz
- a user type class; must not be nullprotected int getInheritedUserTypeIdentifier(Class clz)
clz
- a user type class; must not be nullprotected int getUserTypeIdentifierInternal(String sClass)
sClass
- the name of a user type class; must not be nullprotected boolean isInitialized()
protected String getConfigLocation()
protected ConfigurablePofContext.PofConfig getPofConfig()
protected boolean isInterfaceAllowed()
protected boolean isSubclassAllowed()
protected boolean isLambdaAllowed()
public boolean isReferenceEnabled()
public void setReferenceEnabled(boolean fReferenceEnabled)
fReferenceEnabled
- the referenceEnabled flag to setpublic void setPreferJavaTime(boolean fPreferJavaTime)
public String toString()
protected void checkNotInitialized()
IllegalStateException
- if the ConfigurablePofContext is already fully initializedprotected void ensureInitialized()
protected void initialize()
protected ConfigurablePofContext.PofConfig createPofConfig()
protected PofSerializer instantiateSerializer(XmlElement xmlSer, int nTypeId, Class clz)
PofSerializer
from the provided XML serializer element.xmlSer
- xml defining the serializer to createnTypeId
- the user type id this class is registered withclz
- the class of the user typeprotected Class loadClass(String sClass)
sClass
- the fully qualified class nameRuntimeException
- a RuntimeException (or a subclass thereof) is thrown if the specified Class could not be loadedprotected RuntimeException report(String sURI, int nTypeId, String sClass, Throwable e, String sText)
sURI
- the URI of the configurationnTypeId
- the type ID (if applicable and if known)sClass
- the user type class name (if applicable and if known)e
- the underlying exception, if anysText
- the detailed description of the problemIllegalStateException
- always thrownpublic static void mergeIncludes(String sURI, XmlElement xmlConfig, ClassLoader loader)
sURI
- the URI of the POF configuration filexmlConfig
- the base POF configurationloader
- the ClassLoader
used to find the included POF configuration resourcesprotected static void appendDefaultSerializerToUserTypes(XmlElement xmlConfig)
This method could be overridden to add new custom configuration elements to pof-config.
xmlConfig
- the XmlElement containing pof configuration