Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.io.pof
Class ConfigurablePofContext

    java.lang.Object
      com.tangosol.io.pof.ConfigurablePofContext

All Implemented Interfaces:
  ClassLoaderAware, PofContext, Serializer, XmlConfigurable

Direct Known Subclasses:
  SafeConfigurablePofContext

    public class ConfigurablePofContext

extends java.lang.Object
implements PofContext, ClassLoaderAware, XmlConfigurable

This class implements the `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:

- A valid user type ID that is unique within this POF context;
- A Java class name that identifies a Java class 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 Java class name that identifies a non-abstract implementation of the PofSerializer interface.

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:

- 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 Java class or interface that all values of the user type are type-assignable to.
- The `serializer` element is used to specify an implementation of PofSerializer 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 user type is assumed to implement the PortableObject interface, and the `PortableObjectSerializer` implementation is 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:

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

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

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

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 pof-config.dtd 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 WeakHashMap 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.

Since:
  Coherence 3.2
Author:
  jh/cp 2006.07.24

Nested Class Summary
`protected static class` | `ConfigurablePofContext.PofConfig` The information related to the configuration of a particular PofContext for a specific URI and ClassLoader.

Field Summary
`static java.lang.String` | `DEFAULT_RESOURCE` The name of the application resource that contains the default set of wire-format-to-object bindings.
`static java.lang.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.

Constructor Summary
`ConfigurablePofContext()` Default constructor.
`ConfigurablePofContext(java.lang.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.

Method Summary
`protected 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.
`java.lang.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.
`java.lang.Class` | `getClass(int nTypeId)` Determine the class associated with the given user type identifier.
`java.lang.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 java.lang.String` | `getConfigLocation()` Obtain the location of the configuration that the ConfigurablePofContext used to configure itself.
`java.lang.ClassLoader` | `getContextClassLoader()` Retrieve the context ClassLoader for this object.
`protected int` | `getInheritedUserTypeIdentifier(java.lang.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(java.lang.Class clz)` Determine the user type identifier associated with the given class.
`int` | `getUserTypeIdentifier(java.lang.Object o)` Determine the user type identifier associated with the given object.
`int` | `getUserTypeIdentifier(java.lang.String sClass)` Determine the user type identifier associated with the given class name.
`protected int` | `getUserTypeIdentifierInternal(java.lang.Class clz)` Determine the user type identifier associated with the given class.
`protected int` | `getUserTypeIdentifierInternal(java.lang.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 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` | `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(java.lang.Class clz)` Determine if the given class is a user type known to this PofContext.
`boolean` | `isUserType(java.lang.Object o)` Determine if the given object is of a user type known to this PofContext.
`boolean` | `isUserType(java.lang.String sClass)` Determine if the class with the given name is a user type known to this PofContext.
`protected java.lang.Class` | `loadClass(java.lang.String sClass)` Find the specified class, return a Java Class object for it.
`protected java.net.URL` | `loadResource(java.lang.String sURI)` Find the specified resource, returning a URL for it.
`protected java.lang.RuntimeException` | `report(java.lang.String sURI, int nTypeId, java.lang.String sClass, java.lang.Throwable e, java.lang.String sText)` Assemble and throw an informative exception based on the passed details.
`void` | `serialize(WriteBuffer.BufferOutput out, java.lang.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(java.lang.ClassLoader loader)` Specify the context ClassLoader for this object.
`java.lang.String` | `toString()` Return a description of this ConfigurablePofContext.

Field Detail

### PROPERTY_CONFIG

    public static final java.lang.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.

  The value of this property must be the name of a resource that contains an XML document with the structure defined in `/pof-config.dtd` (deployed in `coherence.jar`). An example configuration is provided in the `example-pof-config.xml` file (found in the same location as the DTD), and includes a list of many of the POF-capable Coherence classes.

  The default value for the `"tangosol.pof.config"` system property is `"coherence-pof-config.xml"`.

  See Also:
    Constant Field Values

### DEFAULT_RESOURCE

    public static final java.lang.String DEFAULT_RESOURCE

  The name of the application resource that contains the default set of wire-format-to-object bindings.

  The default value for the resource name is `"coherence-pof-config.xml"`. The default can be overriden by specifying a value for the `tangosol.pof.config` system property.

Constructor Detail

### ConfigurablePofContext

    public ConfigurablePofContext()

  Default constructor.

  Create a default ConfigurablePofContext that will load configuration information from the locator specified in `DEFAULT_RESOURCE`.

### ConfigurablePofContext

    public ConfigurablePofContext(java.lang.String sLocator)

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

  Parameters:
    `sLocator` - the locator that specifies the location of the PofContext configuration file; the locator is either a valid path or a URL

### ConfigurablePofContext

    public ConfigurablePofContext(XmlElement xml)

  Create a ConfigurablePofContext that will use the passed configuration information.

  Parameters:
    `xml` - an XmlElement containing information in the format of a configuration file used by ConfigurablePofContext

Method Detail

### getConfig

    public XmlElement getConfig()

  Determine the current configuration of the object.

  Note that the configuration will not be available unless the ConfigurablePofContext was constructed with the configuration, the configuration was specified using the `XmlConfigurable` interface, or the ConfigurablePofContext has fully initialized itself (which does not occur until a ClassLoader is provided, or an attempt is made through the ConfigurablePofContext to serialize or deserialize a POF object, whichever comes first.)

  Specified by:
    `getConfig` in interface `XmlConfigurable`
  Returns:
    the XML configuration or null

### setConfig

    public void setConfig(XmlElement xml)

  Specify the configuration for the object.

  Note that the configuration cannot be set after the ConfigurablePofContext is fully initialized.

  Specified by:
    `setConfig` in interface `XmlConfigurable`
  Parameters:
    `xml` - the XML configuration for the object
  Throws:
    `java.lang.IllegalStateException` - if the ConfigurablePofContext is already fully initialized

### getContextClassLoader

    public java.lang.ClassLoader getContextClassLoader()

  Retrieve the context ClassLoader for this object. The context ClassLoader is provided by the creator of the object for use by the object when loading classes and resources.

  Specified by:
    `getContextClassLoader` in interface `ClassLoaderAware`
  Returns:
    the context ClassLoader for this object
  See Also:
    `Thread.getContextClassLoader()`

### setContextClassLoader

    public void setContextClassLoader(java.lang.ClassLoader loader)

  Specify the context ClassLoader for this object. The context ClassLoader can be set when the object is created, and allows the creator to provide the appropriate class loader to be used by the object when when loading classes and resources.

  Note that the ConfigurablePofContext will fully initialize when it is provided a ClassLoader.

  Specified by:
    `setContextClassLoader` in interface `ClassLoaderAware`
  Parameters:
    `loader` - the context ClassLoader for this object
  Throws:
    `java.lang.IllegalStateException` - if the ConfigurablePofContext is already fully initialized

### serialize

    public void serialize(WriteBuffer.BufferOutput out,
                          java.lang.Object o)
                   throws java.io.IOException

  Serialize an object to a WriteBuffer by writing its state using the specified BufferOutput object.

  Specified by:
    `serialize` in interface `Serializer`
  Parameters:
    `out` - the BufferOutput with which to write the object's state
    `o` - the object to serialize
  Throws:
    `java.io.IOException` - if an I/O error occurs

### deserialize

    public java.lang.Object deserialize(ReadBuffer.BufferInput in)
                                 throws java.io.IOException

  Deserialize an object from a ReadBuffer by reading its state using the specified BufferInput object.

  Specified by:
    `deserialize` in interface `Serializer`
  Parameters:
    `in` - the BufferInput with which to read the object's state
  Returns:
    the deserialized user type instance
  Throws:
    `java.io.IOException` - if an I/O error occurs

### getPofSerializer

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

  Specified by:
    `getPofSerializer` in interface `PofContext`
  Parameters:
    `nTypeId` - the type identifier of the user type that can be serialized and deserialized using the returned PofSerializer; must be non-negative
  Returns:
    a PofSerializer for the specified user type

### getUserTypeIdentifier

    public int getUserTypeIdentifier(java.lang.Object o)

  Determine the user type identifier associated with the given object.

  Specified by:
    `getUserTypeIdentifier` in interface `PofContext`
  Parameters:
    `o` - an instance of a user type; must not be null
  Returns:
    the type identifier of the user type associated with the given object

### getUserTypeIdentifier

    public int getUserTypeIdentifier(java.lang.Class clz)

  Determine the user type identifier associated with the given class.

  Specified by:
    `getUserTypeIdentifier` in interface `PofContext`
  Parameters:
    `clz` - a user type class; must not be null
  Returns:
    the type identifier of the user type associated with the given class

### getUserTypeIdentifier

    public int getUserTypeIdentifier(java.lang.String sClass)

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

  Specified by:
    `getUserTypeIdentifier` in interface `PofContext`
  Parameters:
    `sClass` - the name of a user type class; must not be null
  Returns:
    the type identifier of the user type associated with the given class name

### getClassName

    public java.lang.String getClassName(int nTypeId)

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

  Specified by:
    `getClassName` in interface `PofContext`
  Parameters:
    `nTypeId` - the user type identifier; must be non-negative
  Returns:
    the name of the class associated with the specified user type identifier

### getClass

    public java.lang.Class getClass(int nTypeId)

  Determine the class associated with the given user type identifier.

  Specified by:
    `getClass` in interface `PofContext`
  Parameters:
    `nTypeId` - the user type identifier; must be non-negative
  Returns:
    the class associated with the specified user type identifier

### isUserType

    public boolean isUserType(java.lang.Object o)

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

  Specified by:
    `isUserType` in interface `PofContext`
  Parameters:
    `o` - the object to test; must not be null
  Returns:
    true iff the specified object is of a valid user type

### isUserType

    public boolean isUserType(java.lang.Class clz)

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

  Specified by:
    `isUserType` in interface `PofContext`
  Parameters:
    `clz` - the class to test; must not be null
  Returns:
    true iff the specified class is a valid user type

### isUserType

    public boolean isUserType(java.lang.String sClass)

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

  Specified by:
    `isUserType` in interface `PofContext`
  Parameters:
    `sClass` - the name of the class to test; must not be null
  Returns:
    true iff the class with the specified name is a valid user type

### getUserTypeIdentifierInternal

    protected int getUserTypeIdentifierInternal(java.lang.Class clz)

  Determine the user type identifier associated with the given class.

  Parameters:
    `clz` - a user type class; must not be null
  Returns:
    the type identifier of the user type associated with the given class or -1 if the user type is unknown to this PofContext

### getInheritedUserTypeIdentifier

    protected int getInheritedUserTypeIdentifier(java.lang.Class clz)

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

  Parameters:
    `clz` - a user type class; must not be null
  Returns:
    the type identifier of the user type associated with the given class or -1 if the user type and its superclass(es) and implemented interface(s) are unknown to this PofContext

### getUserTypeIdentifierInternal

    protected int getUserTypeIdentifierInternal(java.lang.String sClass)

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

  Parameters:
    `sClass` - the name of a user type class; must not be null
  Returns:
    the type identifier of the user type associated with the given class name or -1 if the user type is unknown to this PofContext

### isInitialized

    protected boolean isInitialized()

  Determine if the ConfigurablePofContext has completed its initialization.

  Returns:
    true iff the initialization is complete

### getConfigLocation

    protected java.lang.String getConfigLocation()

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

  Returns:
    the location information for the configuration for the ConfigurablePofContext, or null if not yet initialized and no location was specified

### getPofConfig

    protected ConfigurablePofContext.PofConfig getPofConfig()

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

  Returns:
    the PofConfig for the ConfigurablePofContext, or null if not yet initialized

### isInterfaceAllowed

    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.

  Returns:
    true iff an interface name is acceptable in the configuration as the class of a user type

### isSubclassAllowed

    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.

  Returns:
    true iff serialization of sub-classes is explicitly enabled

### toString

    public java.lang.String toString()

  Return a description of this ConfigurablePofContext.

  Returns:
    a String representation of the ConfigurablePofContext object

### checkNotInitialized

    protected void checkNotInitialized()

  Verify that the ConfigurablePofContext has not already been initialized.

  Throws:
    `java.lang.IllegalStateException` - if the ConfigurablePofContext is already fully initialized

### ensureInitialized

    protected void ensureInitialized()

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

### initialize

    protected void initialize()

  Bind the ConfigurablePofContext to a ClassLoader, resolving all class names, etc.

### createPofConfig

    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.

  Returns:
    a PofConfig for this ConfigurablePofContext

### loadClass

    protected java.lang.Class loadClass(java.lang.String sClass)

  Find the specified class, return a Java Class object for it.

  Parameters:
    `sClass` - the fully qualified class name
  Returns:
    the Class object for the specified class name, never null
  Throws:
    `java.lang.RuntimeException` - a RuntimeException (or a subclass thereof) is thrown if the specified Class could not be loaded

### loadResource

    protected java.net.URL loadResource(java.lang.String sURI)

  Find the specified resource, returning a URL for it.

  Parameters:
    `sURI` - the resource identifier to load
  Returns:
    a URL for the resource, or null if it could not be found

### report

    protected java.lang.RuntimeException report(java.lang.String sURI,
                                                int nTypeId,
                                                java.lang.String sClass,
                                                java.lang.Throwable e,
                                                java.lang.String sText)

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

  Parameters:
    `sURI` - the URI of the configuration
    `nTypeId` - the type ID (if applicable and if known)
    `sClass` - the user type class name (if applicable and if known)
    `e` - the underlying exception, if any
    `sText` - the detailed description of the problem
  Returns:
    this method does not return; it always throws an exception
  Throws:
    `java.lang.IllegalStateException` - always thrown

### appendDefaultSerializerToUserTypes

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

  This method could be overridden to add new custom configuration elements to pof-config.

  Parameters:
    `xmlConfig` - the XmlElement containing pof configuration

Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle. All rights reserved.