Skip Headers
Oracle® Coherence Developer's Guide
Release 3.6.1

Part Number E15723-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

D POF User Type Configuration Elements

This appendix provides a listing of the elements that can be used to specify POF user types. POF user type configuration elements are defined in the pof-config.dtd file that can be found in the coherence.jar file.

You can find additional information about the POF user type configuration file in the Javadoc for the ConfigurablePofContext class.

POF User Type Deployment Descriptor

Use the POF user type deployment descriptor to specify the various user types which are being passed into the cluster.

Document Location

The name and location of the descriptor defaults to pof-config.xml. The default POF user type descriptor (packaged in coherence.jar) will be used unless a custom file is found within the application's classpath. The name and location of the descriptor can also be configured using system property tangosol.pof.config. It is recommended that all nodes within a cluster use identical POF user type descriptors.

Document Root

The root element of the POF user type descriptor is pof-config. This is where you may begin specifying your user types.

Document Format

The POF user type descriptor should begin with the following DOCTYPE declaration:

<!DOCTYPE pof-config SYSTEM "pof-config.dtd">

The format of the document and the nesting of elements is illustrated in Example D-1.

Example D-1 Format of a POF User Type Configuration File (pof-config.xml)

<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>
   <default-serializer>
      <class-name>com.mycompany.data.TradeSerializer</class-name>
      <init-params>
         <init-param>
            <param-type>int</param-type>
            <param-value>{type-id}</param-value>
         </init-param>
      </init-params>
   </default-serializer>
</pof-config>

Command Line Override

Oracle Coherence provides a powerful Command Line Setting Override Feature, which allows any element defined in this descriptor to be overridden from the Java command line if it has a system-property attribute defined in the descriptor.


Element Index

Table D-1 lists all elements which may be used from within a POF user type configuration.


allow-interfaces

Used in: <pof-config>

Description

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. Default value is false.

Elements

Terminal element.


allow-subclasses

Used in: <pof-config>

Description

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 will be permitted at runtime and automatically mapped to the specified super-class for purposes of obtaining a serializer.

Valid values are true or false. Default value is false.

Elements

Terminal element.


class-name

Used in: <user-type>, <serializer>, <default-serializer>

Description

The class-name element specifies the name of a Java class or interface.

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.

Within the serializer element, the class-name element is required.

Within the default-serializer element, the class-name element is required.

Elements

Terminal element.


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 will be 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 will be 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:

Elements

Table D-2 describes the elements that can be defined within the default-serializer element.

Table D-2 default-serializer Subelements

Element Required/Optional Description

<class-name>

Required

Specifies the 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.



include

Used in: <user-type-list>

Description

The include element specifies the location of a pof-config 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 pof-config file.

Elements

Terminal element.


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 you can define within the init-param element.

Table D-3 init-param Subelements

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 runtime with a specific runtime 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 elements you can define within 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.



param-type

Used in: <init-param>

Description

The param-type element specifies the Java type of initialization parameter.

Supported types are:

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

Elements

Terminal element.


param-value

Used in: <init-param>

Description

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 runtime with a specific runtime value before the constructor is invoked:

Elements

Terminal element.


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 elements you can define within the pof-config element.

Table D-5 pof-config Subelements

Element Required/Optional Description

<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. 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 will be permitted at runtime and automatically mapped to the specified super-class for purposes of obtaining a serializer. Valid values are true or false. Default value is false.

<user-type-list>

Required

The user-type-list element contains zero or more user-type elements. Each POF user type that will be 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.

<default-serializer>

Optional

The default-serializer specifies what PofSerializer to use to serialize and deserialize all user types defined in the pof-config. If a serializer is specified for a user-type, then that serializer will be used for that user-type instead of the default serializer.



serializer

Used in: <acceptor-config>, <distributed-scheme>, <initiator-config>, <invocation-scheme>, <optimistic-scheme>, <replicated-scheme>, <user-type>

Description

This element may be used either as part of a service scheme element such as proxy-scheme/acceptor-config, and distributed-scheme, or as part of a user-type element within a POF configuration file for specifying a POFSerializer.

Usage Within Service Schemes

Specifies the class configuration info for a com.tangosol.io.Serializer implementation used by the service to serialize and deserialize user types.

For example, the following configures a ConfigurablePofContext that uses the default coherence-pof-config.xml configuration file to write objects to and read from a stream:

<serializer>
  <class-name>com.tangosol.io.pof.ConfigurablePofContext</class-name>
</serializer>

Usage Within user-type

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, in this order:

Elements

Table D-6 describes the elements you can define within the serializer element.

Table D-6 serializer Subelements

Element Required/Optional Description

<class-name>

Required

Specifies the name of the serializer.

<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.



type-id

Used in: <user-type>

Description

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 will be 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.

Note:

Reserved IDs: The first 1000 IDs are reserved for Coherence internal use.

Elements

Terminal element.


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 elements you can define within the user-type element.

Table D-7 user-type Subelements

Element Required/Optional Description

<class-name>

Required

The class-name element specifies the name of a Java class or interface. 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. Within the serializer element, the class-name element is required.

<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 will be 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.



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 will be 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

The following table describes the elements you can define within the user-type-list element.

Table D-8 user-type-list Subelements

Element Required/Optional Description

<include>

Optional

The include element specifies the location of a pof-config 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 pof-config file. Any number of <include> elements may be specified.

<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.