Class ConfigurablePofContext

This class implements the IPofContext interface using information provided in a configuration file (or in a passed XML configuration).

Inheritance

object

ConfigurablePofContext

Implements

IPofContext

ISerializer

IXmlConfigurable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Tangosol.IO.Pof

Assembly: Coherence.dll

Syntax

public class ConfigurablePofContext : IPofContext, ISerializer, IXmlConfigurable

Remarks

For each user type supported by this POF context, it must be provided with:

• A valid user type ID that is unique within this POF context.
• A .NET type name that identifies a .NET type or interface that all values of the user type are type-assignable to (and that no values of other user types are type-assignable to); in other words, all values of the user type (and no values of other user types) are instances of the specified class, instances of a sub-class of the specified class, or (if it is an interface) instances of a class that implements the specified interface.
• A .NET type name that identifies a non-abstract implementation of the IPofSerializer interface.

The format of the configuration XML is as follows:

 <pof-config>
   <user-type-list>
   ..
     <user-type>
       <type-id>53</type-id>
       <class-name>My.Example.Data.Trade, MyAssembly</class-name>
       <serializer>
         <class-name>Tangosol.IO.Pof.PortableObjectSerializer, Coherence</class-name>
         <init-params>
           <init-param>
             <param-type>System.Int32</param-type>
             <param-value>{type-id}</param-value>
           </init-param>
         </init-params>
       </serializer>
     </user-type>
 <user-type>
   <type-id>54</type-id>
   <class-name>My.Example.Data.Position, MyAssembly</class-name>
 </user-type>

..
<include>file:/my-pof-config.xml</include>
..
</user-type-list>
<allow-interfaces>false</allow-interfaces>
<allow-subclasses>false</allow-subclasses>
<default-serializer>
<class-name>Tangosol.IO.Pof.XmlPofSerializer, Coherence</class-name>
<init-params>
<init-param>
<param-type>System.Int32</param-type>
<param-value>{type-id}</param-value>
</init-param>
</init-params>
</default-serializer>
</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:

• The user-type element should contain a type-id element whose value specifies the unique integer type ID; if none of the user-type elements contains a type-id element, then the type IDs for the user types will be based on the order in which they appear in the configuration, with the first user type being assigned the type ID 0, the second user type being assigned the type ID 1, and so on. (It is strongly recommended that user types IDs always be specified, in order to support schema versioning and evolution.)
• The class-name element is required, and specifies the fully qualified name of the .NET type or interface that all values of the user type are type-assignable to.
• The serializer element is used to specify an implementation of IPofSerializer to use to serialize and deserialize user type values to and from a POF stream. Within the serializer element, the class-name element is required, and zero or more constructor parameters can be defined within an init-params block. If no serializer is specified, then the default-serializer is used if one is specified, otherwise the user type is assumed to implement the IPortableObject interface or have a PortableAttribute. 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 IPofContext 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.

In order to be used by the ConfigurablePofContext, a IPofSerializer 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:

• {type-id}replaced with the Type ID of the User Type
• {class-name} replaced with the name of the class for the User Type
• {class}replaced with the Type for the User Type

If the init-params element is not present, then the ConfigurablePofContext attempts to construct the IPofSerializer by searching for one of the following constructors in the same order as they appear here:

• (int typeId, Type type)
• (int typeId)
• ()

Once constructed, if the IPofSerializer implements the IXmlConfigurable interface, the Config property is set to the passed XML information, transposed as described by TransformInitParams(IXmlElement, IXmlElement), and as described in the pof-config.xsd file.

Constructors

ConfigurablePofContext()

Default constructor.

Declaration

public ConfigurablePofContext()

Remarks

Create a default ConfigurablePofContext that will load definitions from the default POF config file.

ConfigurablePofContext(Stream)

Create a ConfigurablePofContext that will use the passed configuration information.

Declaration

public ConfigurablePofContext(Stream stream)

Parameters

Type	Name	Description
Stream	stream	An Stream containing information in the format of a configuration file used by ConfigurablePofContext.

ConfigurablePofContext(string)

Create a ConfigurablePofContext that will load configuration information from the specified locator.

Declaration

public ConfigurablePofContext(string locator)

Parameters

Type	Name	Description
string	locator	The locator that specifies the location of the IPofContext configuration file; the locator is either a valid path or a URL.

ConfigurablePofContext(ConfigurablePofContext)

Create a copy of ConfigurablePofContext from the given one.

Declaration

public ConfigurablePofContext(ConfigurablePofContext that)

Parameters

Type	Name	Description
ConfigurablePofContext	that	The ConfigurablePofContext to (shallow) copy from.

ConfigurablePofContext(IXmlElement)

Create a ConfigurablePofContext that will use the passed configuration information.

Declaration

public ConfigurablePofContext(IXmlElement xml)

Parameters

Type	Name	Description
IXmlElement	xml	An IXmlElement containing information in the format of a configuration file used by ConfigurablePofContext.

Properties

Config

IXmlElement holding configuration information.

Declaration

public virtual IXmlElement Config { get; set; }

Property Value

Type	Description
IXmlElement	IXmlElement holding configuration information.

Remarks

Note that the configuration will not be available unless the ConfigurablePofContext was constructed with the configuration, the configuration was specified using the IXmlConfigurable interface, or the ConfigurablePofContext has fully initialized itself

Also, note that the configuration cannot be set after the ConfigurablePofContext is fully initialized.

ConfigLocation

Obtain the location of the configuration that the ConfigurablePofContext used to configure itself.

Declaration

protected virtual string ConfigLocation { get; }

Property Value

Type	Description
string	The location information for the configuration for the ConfigurablePofContext, or null if not yet initialized and no location was specified.

DefaultPofConfig

The default XML configuration used when one isn't explicitly passed in the constructor for this class.

Declaration

public static IXmlDocument DefaultPofConfig { get; set; }

Property Value

Type	Description
IXmlDocument	The default XML configuration.

DefaultPofConfigResource

The IResource for the default XML configuration used when one isn't explicitly passed in the constructor for this class.

Declaration

public static IResource DefaultPofConfigResource { get; set; }

Property Value

Type	Description
IResource	The IResource for the default XML configuration.

IsInitialized

Determine if the ConfigurablePofContext has completed its initialization.

Declaration

protected virtual bool IsInitialized { get; }

Property Value

Type	Description
bool	true if the initialization is complete.

IsInterfaceAllowed

Determine if the ConfigurablePofContext supports the configuration of user types by specifying an interface (instead of a class) for the .NET type.

Declaration

protected virtual bool IsInterfaceAllowed { get; }

Property Value

Type	Description
bool	true if an interface name is acceptable in the configuration as the type of a user type.

Exceptions

Type	Condition
ArgumentNullException	If the obtained value from the configuration file is null.
FormatException	If the obtained value from the configuration file is not equivalent to true or false.

IsReferenceEnabled

Determine if Identity/Reference type support is enabled for this ConfigurablePofContext.

Declaration

public virtual bool IsReferenceEnabled { get; set; }

Property Value

Type	Description
bool	true if Identity/Reference type support is enabled

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.

Declaration

protected virtual bool IsSubclassAllowed { get; }

Property Value

Type	Description
bool	true if serialization of sub-classes is explicitly enabled.

Exceptions

Type	Condition
ArgumentNullException	If the obtained value from the configuration file is null.
FormatException	If the obtained value from the configuration file is not equivalent to true or false.

Methods

AppendDefaultSerializerToUserTypes(IXmlElement)

Process <default-serializer> element from specified xml configuration and appends information about serializer to each <user-type> element within <user-type-list> unless user type already has serializer specified.

Declaration

protected virtual void AppendDefaultSerializerToUserTypes(IXmlElement xmlConfig)

Parameters

Type	Name	Description
IXmlElement	xmlConfig	IXmlElement containing pof configuration.

CheckNotInitialized()

Verify that the ConfigurablePofContext has not already been initialized.

Declaration

protected virtual void CheckNotInitialized()

Exceptions

Type	Condition
InvalidOperationException	If the ConfigurablePofContext is already fully initialized.

CreatePofConfig()

Create a ConfigurablePofContext.PofConfig object based on a configuration that was either provided as XML, or can be loaded from the specified (or default) URI.

Declaration

protected virtual ConfigurablePofContext.PofConfig CreatePofConfig()

Returns

Type	Description
ConfigurablePofContext.PofConfig	A PofConfig for this ConfigurablePofContext.

Exceptions

Type	Condition
SystemException	If XML configuration file contains bad data.

Deserialize(DataReader)

Deserialize an object from a stream by reading its state using the specified DataReader object.

Declaration

public virtual object Deserialize(DataReader reader)

Parameters

Type	Name	Description
DataReader	reader	The DataReader with which to read the object's state.

Returns

Type	Description
object	The deserialized user type instance.

Exceptions

Type	Condition
IOException	If an I/O error occurs.

EnsureInitialized()

Fully initialize the ConfigurablePofContext if it has not already been initialized.

Declaration

protected virtual void EnsureInitialized()

GetInheritedUserTypeIdentifier(Type)

Helper method for determining the user type identifier associated with a given class that does not have a direct configured association.

Declaration

protected virtual int GetInheritedUserTypeIdentifier(Type type)

Parameters

Type	Name	Description
Type	type	A user type; must not be null.

Returns

Type	Description
int	The type identifier of the user type associated with the given type or -1 if the user type and its superclass(es) and implemented interface(s) are unknown to this IPofContext.

GetPofConfig()

Obtain the ConfigurablePofContext.PofConfig that represents the initialized state of the ConfigurablePofContext.

Declaration

protected virtual ConfigurablePofContext.PofConfig GetPofConfig()

Returns

Type	Description
ConfigurablePofContext.PofConfig	The PofConfig for the ConfigurablePofContext, or null if not yet initialized.

GetPofSerializer(int)

Return an IPofSerializer that can be used to serialize and deserialize an object of the specified user type to and from a POF stream.

Declaration

public virtual IPofSerializer GetPofSerializer(int typeId)

Parameters

Type	Name	Description
int	typeId	The type identifier of the user type that can be serialized and deserialized using the returned IPofSerializer; must be non-negative.

Returns

Type	Description
IPofSerializer	An IPofSerializer for the specified user type.

Exceptions

Type	Condition
ArgumentException	If the specified user type is negative or unknown to this IPofContext.

GetSerializer(IXmlElement, Type, int)

Returns serializer for user type specified by xmlType.

Declaration

protected virtual IPofSerializer GetSerializer(IXmlElement xmlType, Type type, int typeId)

Parameters

Type	Name	Description
IXmlElement	xmlType	IXmlElement with configuration for user type.
Type	type	User type.
int	typeId	Type id of user type.

Returns

Type	Description
IPofSerializer	IPofSerializer instance based on the configuration.

GetType(int)

Determine the type associated with the given user type identifier.

Declaration

public virtual Type GetType(int typeId)

Parameters

Type	Name	Description
int	typeId	The user type identifier; must be non-negative.

Returns

Type	Description
Type	The type associated with the specified user type identifier.

Exceptions

Type	Condition
ArgumentException	If the specified user type is negative or unknown to this IPofContext.

GetTypeName(int)

Determine the name of the type associated with a user type identifier.

Declaration

public virtual string GetTypeName(int typeId)

Parameters

Type	Name	Description
int	typeId	The user type identifier; must be non-negative.

Returns

Type	Description
string	The name of the type associated with the specified user type identifier.

Exceptions

Type	Condition
ArgumentException	If the specified user type is negative or unknown to this IPofContext.

GetUserTypeIdentifier(object)

Determine the user type identifier associated with the given object.

Declaration

public virtual int GetUserTypeIdentifier(object o)

Parameters

Type	Name	Description
object	o	An instance of a user type; must not be null.

Returns

Type	Description
int	The type identifier of the user type associated with the given object.

Exceptions

Type	Condition
ArgumentException	If the user type associated with the given object is unknown to this IPofContext.
ArgumentNullException	If the o is null.

GetUserTypeIdentifier(string)

Determine the user type identifier associated with the given type name.

Declaration

public virtual int GetUserTypeIdentifier(string typeName)

Parameters

Type	Name	Description
string	typeName	The assembly-qualified name of a user type; must not be null.

Returns

Type	Description
int	The type identifier of the user type associated with the given type name.

Exceptions

Type	Condition
ArgumentException	If the user type associated with the given type name is unknown to this IPofContext.

GetUserTypeIdentifier(Type)

Determine the user type identifier associated with the given type.

Declaration

public virtual int GetUserTypeIdentifier(Type type)

Parameters

Type	Name	Description
Type	type	A user type; must not be null.

Returns

Type	Description
int	The type identifier of the user type associated with the given type.

Exceptions

Type	Condition
ArgumentException	If the user type associated with the given type is unknown to this IPofContext.

GetUserTypeIdentifierInternal(string)

Determine the user type identifier associated with the given type name.

Declaration

protected virtual int GetUserTypeIdentifierInternal(string typeName)

Parameters

Type	Name	Description
string	typeName	The assembly-qualified name of a user type; must not be null or empty.

Returns

Type	Description
int	The type identifier of the user type associated with the given type name or -1 if the user type is unknown to this IPofContext.

GetUserTypeIdentifierInternal(Type)

Determine the user type identifier associated with the given type.

Declaration

protected virtual int GetUserTypeIdentifierInternal(Type type)

Parameters

Type	Name	Description
Type	type	A user type; must not be null.

Returns

Type	Description
int	The type identifier of the user type associated with the given type or -1 if the user type is unknown to this IPofContext.

Initialize()

Bind the ConfigurablePofContext to a URI of the configuration file, resolving all type names, etc.

Declaration

protected virtual void Initialize()

IsUserType(object)

Determine if the given object is of a user type known to this IPofContext.

Declaration

public virtual bool IsUserType(object o)

Parameters

Type	Name	Description
object	o	The object to test; must not be null.

Returns

Type	Description
bool	true iff the specified object is of a valid user type.

Exceptions

Type	Condition
ArgumentNullException	If the o is null.

IsUserType(string)

Determine if the type with the given name is a user type known to this IPofContext.

Declaration

public virtual bool IsUserType(string typeName)

Parameters

Type	Name	Description
string	typeName	The assembly-qualified name of the type to test; must not be null.

Returns

Type	Description
bool	true iff the type with the specified name is a valid user type.

IsUserType(Type)

Determine if the given type is a user type known to this IPofContext.

Declaration

public virtual bool IsUserType(Type type)

Parameters

Type	Name	Description
Type	type	The type to test; must not be null.

Returns

Type	Description
bool	true iff the specified type is a valid user type.

LoadDefaultPofConfig()

Load and return the default XML POF configuration.

Declaration

protected static IXmlDocument LoadDefaultPofConfig()

Returns

Type	Description
IXmlDocument	The default XML POF configuration.

ResolveType(IXmlElement, int)

Returns Type specified by xmlType with configuration information.

Declaration

protected virtual Type ResolveType(IXmlElement xmlType, int typeId)

Parameters

Type	Name	Description
IXmlElement	xmlType	IXmlElement containing type configuration information.
int	typeId	Type id to be used for this type.

Returns

Type	Description
Type	Type instance specified by configuration xml.

Serialize(DataWriter, object)

Serialize an object to a stream by writing its state using the specified DataWriter object.

Declaration

public virtual void Serialize(DataWriter writer, object o)

Parameters

Type	Name	Description
DataWriter	writer	The DataWriter with which to write the object's state.
object	o	The object to serialize.

Exceptions

Type	Condition
IOException	If an I/O error occurs.

ThrowException(string, int, string, Exception, string)

Assemble and throw an informative exception based on the passed details.

Declaration

protected virtual Exception ThrowException(string uri, int typeId, string typename, Exception e, string message)

Parameters

Type	Name	Description
string	uri	The URI of the configuration.
int	typeId	The type ID (if applicable and if known).
string	typename	The user type type name (if applicable and if known).
Exception	e	The underlying exception, if any.
string	message	The detailed description of the problem.

Returns

Type	Description
Exception	This method does not return; it always throws an exception.

Exceptions

Type	Condition
InvalidOperationException	Always thrown.

Implements

IPofContext

ISerializer

IXmlConfigurable