D POF User Type Configuration Elements

This appendix provides a detailed reference of the POF configuration deployment descriptor and includes a brief overview of the descriptor. See Appendix E, "The PIF-POF Binary Format," for details of the binary format.

This appendix includes the following sections:

POF Configuration Deployment Descriptor
Element Index

D.1 POF Configuration Deployment Descriptor

The POF configuration deployment descriptor is used to specify non-intrinsic types, referred to as User Types, for objects that are being serialized and deserialized using POF. The name and location of the POF configuration deployment descriptor is specified in the operational deployment descriptor and defaults to pof-config.xml. A sample POF configuration deployment descriptor is located in the root of the coherence.jar library and is used unless a custom pof-config.xml file is found before the coherence.jar library within the application's classpath. All cluster members should use identical POF configuration deployment descriptors.

The POF configuration deployment descriptor schema is defined in the coherence-pof-config.xsd file. This XSD file is located in the root of the coherence.jar library and at the following Web URL:

http://xmlns.oracle.com/coherence/coherence-pof-config/1.2/coherence-pof-config.xsd

The <pof-config> element is the root element of the POF configuration deployment descriptor and typically includes an XSD and Coherence namespace reference and the location of the coherence-pof-config.xsd file. For example:

<?xml version='1.0'?>

<pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config
   coherence-pof-config.xsd">

Notes:

The schema located in the coherence.jar library is always used at run time even if the xsi:schemaLocation attribute references the Web URL.
The xsi:schemaLocation attribute can be omitted to disable schema validation.
When deploying Coherence into environments where the default character set is EBCDIC rather than ASCII, ensure that the deployment descriptor file is in ASCII format and is deployed into its run-time environment in the binary format.

Coherence-specific user types are defined in the coherence-pof-config.xml file that is also located in the root of the coherence.jar library. This file should always be referenced as follows when creating a pof-config.xml file:

<?xml version='1.0'?>

<pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config
   coherence-pof-config.xsd">
   <user-type-list>
      <include>coherence-pof-config.xml</include>
   </user-type-list>
   ...
</pof-config>

Element Index

Table D-1 lists all non-terminal POF configuration deployment descriptor elements.

Table D-1 POF Configuration Elements

Element	Used In
`default-serializer`	`pof-config`
`init-param`	`init-params`
`init-params`	`serializer`
`pof-config`	root element
`serializer`	`user-type`
`user-type`	`user-type-list`
`user-type-list`	`pof-config`

default-serializer

Used in: pof-config

Description

This element specifies a PofSerializer to use when serializing and deserializing all user types defined within the pof-config element. If a serializer is specified within a user-type, then that serializer is used for that user-type instead of the default serializer.

If the default serializer element is omitted, the serializer defined for the specific user type is used. If the serializer for the user type is also omitted, then the user type is assumed to implement the PortableObject interface, and the PortableObjectSerializer implementation is used as the PofSerializer.

If the init-params element is omitted from the default serializer element, then the following four constructors are attempted on the specific PofSerializer implementation, and in this order:

(int nTypeId, Class clz, ClassLoader loader)
(int nTypeId, Class clz)
(int nTypeId)
()

Elements

Table D-2 describes the subelements of the default-serializer element.

Table D-2 default-serializer Subelements

Element	Required/ Optional	Description
`<class-name>`	Required	Specifies the fully qualified name of the `PofSerializer` implementation.
<`init-params`>	Optional	Specifies zero or more arguments (each as an `init-param`) that correspond to the parameters of a constructor of the class that is being configured.

init-param

Used in: init-params

Description

The init-param element provides a type for a configuration parameter and a corresponding value to pass as an argument.

Elements

Table D-3 describes the subelements of the init-param element.

Table D-3 init-param Subelements

Element Required/
Optional Description

Element	Required/ Optional	Description
`<param-type>`	Required	The `param-type` element specifies the Java type of initialization parameter. Supported types are: `string`—indicates that the value is a `java.lang.String` `boolean`—indicates that the value is a `java.lang.Boolean` `int`—indicates that the value is a `java.lang.Integer` `long`—indicates that the value is a `java.lang.Long` `double`—indicates that the value is a `java.lang.Double` `decimal`—indicates that the value is a `java.math.BigDecimal` `file`—indicates that the value is a `java.io.File` `date`— indicates that the value is a `java.sql.Date` `time`—indicates that the value is a `java.sql.Timedatetime` `datetime`—indicates that the value is a `java.sql.Timestamp` `xml`—indicates that the value is the entire `init-param XmlElement`. The value is converted to the specified type, and the target constructor or method must have a parameter of that type for the instantiation to succeed.
`<param-value>`	Required	The `param-value` element specifies a value of the initialization parameter. The value is in a format specific to the type of the parameter. There are four reserved values that can be specified. Each of these values is replaced at run time with a value before the constructor is invoked: `{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 Class for the User Type; `{class-loader}`—replaced with the `ConfigurablePofContext's` `ContextClassLoader`.

<param-type>

Required

The param-type element specifies the Java type of initialization parameter. Supported types are:

string—indicates that the value is a java.lang.String
boolean—indicates that the value is a java.lang.Boolean
int—indicates that the value is a java.lang.Integer
long—indicates that the value is a java.lang.Long
double—indicates that the value is a java.lang.Double
decimal—indicates that the value is a java.math.BigDecimal
file—indicates that the value is a java.io.File
date— indicates that the value is a java.sql.Date
time—indicates that the value is a java.sql.Timedatetime
datetime—indicates that the value is a java.sql.Timestamp
xml—indicates that the value is the entire init-param XmlElement.

The value is converted to the specified type, and the target constructor or method must have a parameter of that type for the instantiation to succeed.

<param-value>

Required

The param-value element specifies a value of the initialization parameter. The value is in a format specific to the type of the parameter. There are four reserved values that can be specified. Each of these values is replaced at run time with a value before the constructor is invoked:

{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 Class for the User Type;
{class-loader}—replaced with the ConfigurablePofContext's ContextClassLoader.

init-params

Used in: serializer, default-serializer

Description

The init-params element contains zero or more arguments (each as an init-param) that correspond to the parameters of a constructor of the class that is being configured.

Elements

Table D-4 describes the subelements of the init-params element.

Table D-4 init-params Subelements

Element	Required/ Optional	Description
<`init-param`>	Required	The `init-param` element provides a type for a configuration parameter and a corresponding value to pass as an argument.

pof-config

root element

Description

The pof-config element is the root element of the POF user type configuration descriptor.

Elements

Table D-5 describes the subelements of the pof-config element.

Table D-5 pof-config Subelements

Element	Required/ Optional	Description
<`user-type-list`>	Required	The `user-type-list` element contains zero or more user-type elements. Each POF user type that is used must be listed in the `user-type-list`. The `user-type-list` element may also contain zero or more `include` elements. Each include element is used to add user-type elements defined in another `pof-config` file.
<allow-interfaces>	Optional	The `allow-interfaces` element indicates whether the user-type `class-name` can specify Java interface types in addition to Java class types. Valid values are `true` or `false`. The default value is `false`.
<allow-subclasses>	Optional	The `allow-subclasses` element indicates whether the user-type `class-name` can specify a Java class type that is abstract, and whether sub-classes of any specified user-type `class-name` is permitted at run time and automatically mapped to the specified super-class for purposes of obtaining a serializer. Valid values are `true` or `false`. The default value is `false`.
<enable-references>	Optional	The `enable-references` element indicates whether or not Identity/Reference type support is enabled. Valid values are `true` or `false`. Default value is `false`.
`<default-serializer>`	Optional	The `default-serializer` specifies what serializer to use to serialize and deserialize all user types defined in the POF configuration file. If a user-type defines a specific serializer, then that serializer is used instead of the default serializer.

serializer

Used in: user-type

Description

The serializer element specifies what POF serializer to use to serialize and deserialize a specific user type. A PofSerializer implementation is used to serialize and deserialize user type values to and from a POF stream.

If the serializer element is omitted, then the user type is assumed to implement the PortableObject interface and the PortableObjectSerializer implementation is used as the POF serializer. If POF annotations are used, then the PofAnnotationSerializer implementation is used as the POF serializer.

If the init-params element is omitted, then the following four constructors are attempted (in this order) on the specific PofSerializer implementation:

(int nTypeId, Class clz, ClassLoader loader)
(int nTypeId, Class clz)
(int nTypeId)
()

Elements

Table D-6 describes the subelements of the serializer element.

Table D-6 serializer Subelements

Element	Required/ Optional	Description
`<class-name>`	Required	Specifies the fully qualified name of the `PofSerializer` implementation.
<`init-params`>	Optional	The `init-params` element contains zero or more arguments (each as an `init-param`) that correspond to the parameters of a constructor of the class that is being configured.

user-type

Used in: user-type-list

Description

The user-type element contains the declaration of a POF user type. A POF user type is a uniquely identifiable, portable, versionable object class that can be communicated among systems regardless of language, operating system, hardware and location.

Within the user-type element, the type-id element is optional, but its use is strongly suggested to support schema versioning and evolution.

Within the user-type element, the class-name element is required, and specifies the fully qualified name of the Java class or interface that all values of the user type are type-assignable to.

If the serializer element is omitted, then the user type is assumed to implement the PortableObject interface, and the PortableObjectSerializer implementation is used as the PofSerializer.

Elements

Table D-7 describes the subelements of the user-type element.

Table D-7 user-type Subelements

Element Required/
Optional Description

Element	Required/ Optional	Description
`<type-id>`	Optional	The `type-id` element specifies an integer value (`n` `>=` `0`) that uniquely identifies the user type. If none of the `user-type` elements contains a `type-id` element, then the type IDs for the user types are based on the order in which they appear in the `user-type-list`, with the first user type being assigned the type `ID` `0`, the second user type being assigned the type `ID` `1`, and so on. However, it is strongly recommended that user types IDs always be specified, to support schema versioning and evolution. The first 1000 IDs are reserved for Coherence internal use and cannot be used.
`<class-name>`	Required	The `class-name` element specifies the fully qualified name of a Java class or interface that all values of the user type are type-assignable to.
<`serializer`>	Optional	The `serializer` element specifies what `PofSerializer` to use to serialize and deserialize a specific user type. A `PofSerializer` is used 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` element. If the serializer element is omitted, then the user type is assumed to implement the `PortableObject` interface, and the `PortableObjectSerializer` implementation is used as the `PofSerializer`. If the `init-params` element is omitted from the `serializer` element, then the following four constructors are attempted on the specific `PofSerializer` implementation, and in this order: `(int nTypeId, Class clz, ClassLoader loader)` `(int nTypeId, Class clz)` `(int nTypeId)` `()`

<type-id>

Optional

The type-id element specifies an integer value (n >= 0) that uniquely identifies the user type. If none of the user-type elements contains a type-id element, then the type IDs for the user types are based on the order in which they appear in the user-type-list, with the first user type being assigned the type ID 0, the second user type being assigned the type ID 1, and so on. However, it is strongly recommended that user types IDs always be specified, to support schema versioning and evolution. The first 1000 IDs are reserved for Coherence internal use and cannot be used.

<class-name>

Required

The class-name element specifies the fully qualified name of a Java class or interface that all values of the user type are type-assignable to.

<serializer>

Optional

The serializer element specifies what PofSerializer to use to serialize and deserialize a specific user type. A PofSerializer is used 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 element.

If the serializer element is omitted, then the user type is assumed to implement the PortableObject interface, and the PortableObjectSerializer implementation is used as the PofSerializer.

If the init-params element is omitted from the serializer element, then the following four constructors are attempted on the specific PofSerializer implementation, and in this order:

(int nTypeId, Class clz, ClassLoader loader)
(int nTypeId, Class clz)
(int nTypeId)
()

user-type-list

Used in: pof-config

Description

The user-type-list element contains zero or more user-type elements. Each POF user type that is used must be listed in the user-type-list.

The user-type-list element may also contain zero or more include elements. Each include element is used to add user-type elements defined in another pof-config file.

Elements

Table D-8 describes the subelements of the user-type-list element.

Table D-8 user-type-list Subelements

Element Required/
Optional Description

Element	Required/ Optional	Description
<`user-type`>	Optional	The `user-type` element contains the declaration of a POF user type. A POF user type is a uniquely identifiable, portable, versionable object class that can be communicated among systems regardless of language, operating system, hardware and location. Any number of `<user-type>` elements may be specified. Within the `user-type` element, the `type-id` element is optional, but its use is strongly suggested to support schema versioning and evolution. Within the `user-type` element, the `class-name` element is required, and specifies the fully qualified name of the Java class or interface that all values of the user type are type-assignable to. If the `serializer` element is omitted, then the user type is assumed to implement the `PortableObject` interface, and the `PortableObjectSerializer` implementation is used as the `PofSerializer`.
`<include>`	Optional	The `include` element specifies the location of a POF configuration file to load `user-type` elements from. The value is a locator string (either a valid path or URL) that identifies the location of the target file. Any number of `<include>` elements may be specified.

<user-type>

Optional

Within the user-type element, the type-id element is optional, but its use is strongly suggested to support schema versioning and evolution.

Within the user-type element, the class-name element is required, and specifies the fully qualified name of the Java class or interface that all values of the user type are type-assignable to.

If the serializer element is omitted, then the user type is assumed to implement the PortableObject interface, and the PortableObjectSerializer implementation is used as the PofSerializer.

<include>

Optional

The include element specifies the location of a POF configuration file to load user-type elements from. The value is a locator string (either a valid path or URL) that identifies the location of the target file. Any number of <include> elements may be specified.