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.
Use the POF user type deployment descriptor to specify the various user types which are being passed into the cluster.
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.
The root element of the POF user type descriptor is pof-config
. This is where you may begin specifying your user types.
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 J-1.
Example J-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> </pof-config>
Table J-1 lists all elements which may be used from within a POF user type configuration.
Table J-1 POF Configuration Elements
Element | Used In: |
---|---|
< |
|
< |
|
root element |
|
< |
|
Used in: <pof-config
>
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
.
Terminal element.
Used in: <pof-config
>
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
.
Terminal element.
Used in: <user-type
>, <serializer
>
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.
Terminal element.
Used in: <user-type-list
>
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.
Terminal element.
Used in: <init-params
>
The init-param
element provides a type for a configuration parameter and a corresponding value to pass as an argument.
Table J-2 describes the subelements you can define within the init-param
element.
Table J-2 init-param Subelements
Element | Required/Optional | Description |
---|---|---|
Required |
The
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. |
|
Required |
The
|
Used in: <serializer
>
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.
Table J-3 describes the elements you can define within the init-params
element.
Table J-3 init-params Subelements
Element | Required/Optional | Description |
---|---|---|
Required |
The |
Used in: <init-param
>
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 in order for the instantiation to succeed.
Terminal element.
Used in: <init-param
>
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
.
Terminal element.
root element
The pof-config
element is the root element of the POF user type configuration descriptor.
Table J-4 describes the elements you can define within the pof-config
element.
Table J-4 pof-config Subelements
Element | Required/Optional | Description |
---|---|---|
Optional |
The |
|
Optional |
The |
|
Required |
The |
Used in: <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:
(int nTypeId, Class clz, ClassLoader loader)
(int nTypeId, Class clz)
(int nTypeId)
()
Table J-5 describes the elements you can define within the serializer
element.
Table J-5 serializer Subelements
Element | Required/Optional | Description |
---|---|---|
Required |
Specifies the name of the serializer. |
|
Optional |
The |
Used in: <user-type
>
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.Terminal element.
Used in: <user-type-list
>
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
.
Table J-6 describes the elements you can define within the user-type
element.
Table J-6 user-type Subelements
Element | Required/Optional | Description |
---|---|---|
Required |
The |
|
Optional |
The If the serializer element is omitted, then the user type is assumed to implement the If the
|
|
< |
Optional |
The |
Used in: <pof-config
>
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.
The following table describes the elements you can define within the user-type-list
element.
Table J-7 user-type-list Subelements
Element | Required/Optional | Description |
---|---|---|
< |
Required |
The |
Required |
The Within the Within the If the |