Package com.tangosol.util

Class ExternalizableHelper

java.lang.Object
com.tangosol.util.Base
com.tangosol.util.BitHelper
com.tangosol.util.ExternalizableHelper
Direct Known Subclasses:
AbstractAggregator, AbstractExtractor, AbstractPofValue, AbstractPriorityTask, AbstractQueryRecorderFilter, AbstractUpdater, ArrayFilter, CompositeAggregator, CompositeKey, DecoratedBinaryDeltaCompressor, DecorationOnlyDeltaCompressor, DefaultKeyPartitioningStrategy, ExternalizableHelper.IntDecoratedObject, ExtractorEventTransformer, FilterTrigger, GroupAggregator, KeyAssociatedFilter, MapEventFilter, MapEventTransformerFilter, Ownership, PartitionedFilter, PermissionInfo, PofValueParser, PresentFilter, PropertyAdapter, SafeConfigurablePofContext.ExternalSerializer, SafeConfigurablePofContext.SafePofSerializer, SamplingEventTransformer, SemiLiteEventTransformer, SimpleValue, XmlBean
public abstract class ExternalizableHelper extends BitHelper
Helpers for the Serializable, Externalizable and the ExternalizableLite interface.

Note: This class is configured via the ExternalizableHelper.xml document located in the same package as the class. The location of the configuration file can be overridden using the coherence.externalizable.config system property.

Author:
cp 2003.03.28

  • Field Details

    • FMT_NONE

      public static final int FMT_NONE
      Serialization format: Unknown value (alias to FMT_UNKNOWN).
      See Also:

    • FMT_UNKNOWN

      public static final int FMT_UNKNOWN
      Serialization format: Unknown value.
      See Also:

    • FMT_NULL

      public static final int FMT_NULL
      Serialization format: Null value.
      See Also:

    • FMT_INT

      public static final int FMT_INT
      Serialization format: Integer value.
      See Also:

    • FMT_LONG

      public static final int FMT_LONG
      Serialization format: Long value.
      See Also:

    • FMT_DOUBLE

      public static final int FMT_DOUBLE
      Serialization format: Double value.
      See Also:

    • FMT_INTEGER

      public static final int FMT_INTEGER
      Serialization format: BigInteger value.
      See Also:

    • FMT_DECIMAL

      public static final int FMT_DECIMAL
      Serialization format: BigDecimal value.
      See Also:

    • FMT_STRING

      public static final int FMT_STRING
      Serialization format: String value.
      See Also:

    • FMT_BINARY

      public static final int FMT_BINARY
      Serialization format: Binary value.
      See Also:

    • FMT_B_ARRAY

      public static final int FMT_B_ARRAY
      Serialization format: Byte array value.
      See Also:

    • FMT_XML_SER

      public static final int FMT_XML_SER
      Serialization format: XmlSerializable value.
      See Also:

    • FMT_OBJ_EXT

      public static final int FMT_OBJ_EXT
      Serialization format: ExternalizableLite value.
      See Also:

    • FMT_OBJ_SER

      public static final int FMT_OBJ_SER
      Serialization format: Serializable value.
      See Also:

    • FMT_XML_BEAN

      public static final int FMT_XML_BEAN
      Serialization format: XmlBean value.
      See Also:

    • FMT_IDO

      public static final int FMT_IDO
      Serialization format: Integer-decorated value.
      See Also:

    • FMT_FLOAT

      public static final int FMT_FLOAT
      Serialization format: Float value.
      See Also:

    • FMT_SHORT

      public static final int FMT_SHORT
      Serialization format: Short value.
      See Also:

    • FMT_BYTE

      public static final int FMT_BYTE
      Serialization format: Byte value.
      See Also:

    • FMT_BOOLEAN

      public static final int FMT_BOOLEAN
      Serialization format: Boolean value.
      See Also:

    • FMT_BIN_DECO

      public static final int FMT_BIN_DECO
      Serialization format: Decorated Binary value.

      Structure is: 

       byte 0    : format identifier (18)
 byte 1    : bit mask of decoration identifiers (see DECO_* constants)
 byte 2    : packed int specifying the length of the first decoration
 byte next : binary data
 ...
      For each decoration, there is a packed int for its length, followed by its binary data. The first decoration is the decorated value itself, if present.

      Note: FMT_IDO cannot be combined with FMT_BIN_DECO.

      See Also:

    • FMT_BIN_EXT_DECO

      public static final int FMT_BIN_EXT_DECO
      Serialization format: Extended-range Decorated Binary value.

      Structure is: 

       byte 0    : format identifier (19)
 byte 1    : bit mask of decoration identifiers (see DECO_* constants),
             in the packed long format (1-10 bytes)
 byte next : packed int specifying the length of the first decoration
 byte next : binary data
 ...
      For each decoration, there is a packed int for its length, followed by its binary data. The first decoration is the decorated value itself, if present.

      Note: FMT_IDO cannot be combined with FMT_BIN_EXT_DECO.

      See Also:

    • FMT_EXT

      public static final int FMT_EXT
      Serialization format: A DefaultSerializer is NOT used.
      See Also:

    • FMT_OPT

      public static final int FMT_OPT
      Serialization format: Optional value.
      See Also:

    • FMT_OPT_INT

      public static final int FMT_OPT_INT
      Serialization format: OptionalInt value.
      See Also:

    • FMT_OPT_LONG

      public static final int FMT_OPT_LONG
      Serialization format: OptionalLong value.
      See Also:

    • FMT_OPT_DOUBLE

      public static final int FMT_OPT_DOUBLE
      Serialization format: OptionalDouble value.
      See Also:

    • DECO_ID_MIN

      public static final int DECO_ID_MIN
      Decoration range: The minimum decoration identifier.
      See Also:

    • DECO_ID_MAX

      public static final int DECO_ID_MAX
      Decoration range: The maximum decoration identifier.
      See Also:

    • DECO_VALUE

      public static final int DECO_VALUE
      Decoration: The original value (before being decorated).
      See Also:

    • DECO_EXPIRY

      public static final int DECO_EXPIRY
      Decoration: The expiry for the value.
      See Also:

    • DECO_STORE

      public static final int DECO_STORE
      Decoration: The persistent state for the value.
      See Also:

    • DECO_TX

      public static final int DECO_TX
      Decoration: Information managed on behalf of the transactions implementation.
      See Also:

    • DECO_PUSHREP

      public static final int DECO_PUSHREP
      Decoration: Information managed on behalf of Push Replication.
      See Also:

    • DECO_BACKUP

      public static final int DECO_BACKUP
      Decoration: Suggests the backup is not in sync.
      See Also:

    • DECO_RSVD_1

      public static final int DECO_RSVD_1
      Decoration: Reserved for future use by Coherence; do not use.
      See Also:

    • DECO_CUSTOM

      public static final int DECO_CUSTOM
      Decoration: A client specific value (opaque). The original intent of the "custom" decoration was that it would be reserved for use by application code, but previous to Coherence 3.7 it was also used for the OptimisticNamedCache implementation, the TopLink Grid implementation and the Coherence Incubator's "Push Replication" project. As of Coherence 3.7, this attribute is once again made available to frameworks and applications, although care must be taken to avoid using the versions of any of the frameworks that utilized this decoration. Applications are instead encouraged to use the new DECO_APP_1, DECO_APP_2 and DECO_APP_3 decorations.
      See Also:

    • DECO_WLS

      public static final int DECO_WLS
      Decoration: Information managed on behalf of WebLogic.
      See Also:

    • DECO_APP_1

      public static final int DECO_APP_1
      Decoration: Application-assignable decoration; this decoration will not be used, modified or overwritten by Coherence or other Oracle products.
      See Also:

    • DECO_APP_2

      public static final int DECO_APP_2
      Decoration: Application-assignable decoration; this decoration will not be used, modified or overwritten by Coherence or other Oracle products.
      See Also:

    • DECO_APP_3

      public static final int DECO_APP_3
      Decoration: Application-assignable decoration; this decoration will not be used, modified or overwritten by Coherence or other Oracle products.
      See Also:

    • DECO_MEMCACHED

      public static final int DECO_MEMCACHED
      Decoration: Information managed on behalf of Memcached acceptor.
      See Also:

    • DECO_JCACHE

      public static final int DECO_JCACHE
      Decoration: Holds JCache specific meta-information for an entry.
      See Also:

    • DECO_JCACHE_SYNTHETIC

      public static final int DECO_JCACHE_SYNTHETIC
      Decoration: Indicates if an update or delete is considered to be synthetic for JCache. (this is not the same as a Coherence synthetic update)
      See Also:

    • DECO_QUEUE_METADATA

      public static final int DECO_QUEUE_METADATA
      Decoration: Information about a queue element
      See Also:

    • MAX_DECO_HEADER_BYTES

      protected static final int MAX_DECO_HEADER_BYTES
      The maximum number of bytes the header of the binary-decorated value may contain.
      See Also:

    • TRINT_DOMAIN_SPAN

      public static final int TRINT_DOMAIN_SPAN
      Trints use 6 hexits (3 bytes), so the trint domain span is 0x01000000.
      See Also:

    • TRINT_MAX_VALUE

      public static final int TRINT_MAX_VALUE
      Trints use 6 hexits (3 bytes), so the trint maximum is 0x00FFFFFF.
      See Also:

    • TRINT_MAX_VARIANCE

      public static final int TRINT_MAX_VARIANCE
      Trints use 6 hexits (3 bytes), so the trint maximum variance (from a "current" value) is half the trint domain span, or 0x00800000.
      See Also:

    • EMPTY_BINARY_ARRAY

      public static final Binary[] EMPTY_BINARY_ARRAY
      An empty array of Binary objects.

    • PACKED_LONG_SIZE

      public static final int PACKED_LONG_SIZE
      Maximum size of a packed long.
      See Also:

    • PACKED_INT_SIZE

      public static final int PACKED_INT_SIZE
      Maximum size of a packed int.
      See Also:

    • BINARY_SIZE

      public static final int BINARY_SIZE
      Binary overhead.
      See Also:

    • CONVERTER_TO_BINARY

      public static final Converter CONVERTER_TO_BINARY
      A converter from Object to Binary format that uses the DefaultSerializer.
      Since:
      Coherence 2.4

    • CONVERTER_FROM_BINARY

      public static final Converter CONVERTER_FROM_BINARY
      A converter from Binary to Object format, which uses the DefaultSerializer.
      Since:
      Coherence 2.4

    • CONVERTER_STRIP_INTDECO

      public static final Converter CONVERTER_STRIP_INTDECO
      A pass-through Binary converter that removes an IntDecoration if present.
      Since:
      Coherence 3.4

    • PROPERTY_CONFIG

      public static final String PROPERTY_CONFIG
      The name of the system property that can be used to override the location of the ExternalizableHelper configuration file.

      The value of this property must be the name of a resource that contains an XML document with the structure defined in the /com/tangosol/util/ExternalizableHelper.xml configuration descriptor.

      See Also:

    • FORCE_RESOLVING_STREAMS

      public static final boolean FORCE_RESOLVING_STREAMS
      Option: Always use a ResolvingObjectInputStream, even if a regular ObjectInputStream is available.

    • USE_XMLBEAN_CLASS_CACHE

      public static final boolean USE_XMLBEAN_CLASS_CACHE
      Option: Use an XmlBean class cache.

    • XMLBEAN_CLASS_CACHE

      public static final ExternalizableHelper.XmlBeanClassCache XMLBEAN_CLASS_CACHE
      Option: XmlBean class cache implementation.

    • USE_POF_STREAMS

      public static final boolean USE_POF_STREAMS
      Option: Use POF as the default serialization format.

    • LAMBDA_SERIALIZATION

      public static final String LAMBDA_SERIALIZATION
      Option: Use either static or dynamic lambda serialization.

    • s_streamfactory

      public static ObjectStreamFactory s_streamfactory
      Option: Configurable ObjectStreamFactory.

    • CHUNK_THRESHOLD

      public static final int CHUNK_THRESHOLD
      A threshold used to decide whether to perform deserialization using a chunking algorithm; default is greater than 128MB.
      See Also:

    • CHUNK_SIZE

      public static final int CHUNK_SIZE
      When using the chunking algorithm each chunk is constrained to 64MB by default.
      See Also:

  • Constructor Details

    • ExternalizableHelper

      public ExternalizableHelper()

  • Method Details

    • toByteArray

      public static byte[] toByteArray(Object o)
      Write an object to a byte array.
      Parameters:
      o - the object to write into a byte array
      Returns:
      a byte array containing the serialized form of the passed object
      Throws:
      WrapperException - may contain an IOException

    • toByteArray

      public static byte[] toByteArray(Object o, Serializer serializer)
      Write an object to a byte array using the specified Serializer.
      Parameters:
      o - the object to write into a byte array
      serializer - the Serializer to use
      Returns:
      a byte array containing the serialized form of the passed object
      Throws:
      WrapperException - may contain an IOException

    • toByteArray

      public static byte[] toByteArray(long l, byte[] ab)
      Convert a long to an 8-byte byte array.
      Parameters:
      l - the long to convert
      ab - the byte array to populate or null if a new byte array should be created
      Returns:
      an 8-byte byte array that represents the given long
      See Also:

    • toLong

      public static long toLong(byte[] ab)
      Convert a byte array to a long.
      Parameters:
      ab - the byte array to convert
      Returns:
      a long based on the provided byte array
      See Also:

    • fromByteArray

      public static Object fromByteArray(byte[] ab)
      Read an object from a byte array.
      Parameters:
      ab - the byte array containing the object
      Returns:
      the object deserialized from the byte array
      Throws:
      WrapperException - may contain an IOException

    • fromByteArray

      public static Object fromByteArray(byte[] ab, ClassLoader loader)
      Read an object from a byte array.
      Parameters:
      ab - the byte array containing the object
      loader - the ClassLoader to use
      Returns:
      the object deserialized from the byte array
      Throws:
      WrapperException - may contain an IOException

    • toBinary

      public static Binary toBinary(Object o)
      Write an object into a Binary object.
      Parameters:
      o - the object to write into a Binary object
      Returns:
      a Binary object containing a serialized form of the passed object
      Throws:
      WrapperException - may contain an IOException

    • toBinary

      public static Binary toBinary(Object o, Serializer serializer)
      Write an object into a Binary object using the specified Serializer.
      Parameters:
      o - the object to write into a Binary object
      serializer - the Serializer to use
      Returns:
      a Binary object containing a serialized form of the passed object
      Throws:
      WrapperException - may contain an IOException

    • toBinary

      public static Binary toBinary(Object o, Serializer serializer, WriteBuffer buf)
      Write an object into a Binary object using the specified Serializer.
      Parameters:
      o - the object to write into a Binary object
      serializer - the Serializer to use
      buf - the reusable WriteBuffer to serialize into; this buffer is not safe to reuse until the returned Binary has been disposed of
      Returns:
      a Binary object containing a serialized form of the passed object
      Throws:
      WrapperException - may contain an IOException

    • fromBinary

      public static <T> T fromBinary(Binary bin)
      Read an object from a Binary object.
      Type Parameters:
      T - the class of the deserialized object
      Parameters:
      bin - the Binary object containing the serialized object
      Returns:
      the object deserialized from the Binary object
      Throws:
      WrapperException - may contain an IOException

    • fromBinary

      public static <T> T fromBinary(Binary bin, ClassLoader loader)
      Read an object from a Binary object.
      Type Parameters:
      T - the class of the deserialized object
      Parameters:
      bin - the Binary object containing the serialized object
      loader - the ClassLoader to use
      Returns:
      the object deserialized from the Binary object
      Throws:
      WrapperException - may contain an IOException

    • fromBinary

      public static <T> T fromBinary(Binary bin, Serializer serializer)
      Read an object from a Binary object using the specified Serializer.
      Type Parameters:
      T - the class of the deserialized object
      Parameters:
      bin - the Binary object containing the serialized object
      serializer - the Serializer to use
      Returns:
      the object deserialized from the Binary object
      Throws:
      WrapperException - may contain an IOException

    • fromBinary

      public static <T> T fromBinary(Binary bin, Serializer serializer, Class<T> clazz)
      Read an object from a Binary object using the specified Serializer and expected class.
      Type Parameters:
      T - the class of the deserialized object
      Parameters:
      bin - the Binary object containing the serialized object
      serializer - the Serializer to use
      clazz - deserialize object as an instance of this class
      Returns:
      the object deserialized from the Binary object
      Throws:
      RuntimeException - may contain an IOException

    • fromBinary

      public static <T> T fromBinary(Binary bin, Serializer serializer, Remote.Function<ReadBuffer.BufferInput,ReadBuffer.BufferInput> supplier)
      Read an object from a Binary object using the specified Serializer.
      Type Parameters:
      T - the class of the deserialized object
      Parameters:
      bin - the Binary object containing the serialized object
      serializer - the Serializer to use
      supplier - an optional Function that given a BufferInput returns either the same or another BufferInput
      Returns:
      the object deserialized from the Binary object
      Throws:
      RuntimeException - may contain an IOException

    • fromBinary

      public static <T> T fromBinary(Binary bin, Serializer serializer, Remote.Function<ReadBuffer.BufferInput,ReadBuffer.BufferInput> supplier, Class<T> clazz)
      Read an object from a Binary object using the specified Serializer and expected class.
      Type Parameters:
      T - the class of the deserialized object
      Parameters:
      bin - the Binary object containing the serialized object
      serializer - the Serializer to use
      supplier - an optional Function that given a BufferInput returns either the same or another BufferInput
      clazz - deserialize object as an instance of this class
      Returns:
      the object deserialized from the Binary object
      Throws:
      RuntimeException - may contain an IOException

    • ensureSerializer

      public static Serializer ensureSerializer(ClassLoader loader)
      Obtain a Serializer for the specified ClassLoader. This method is intended to provide configurable indirection for the serialization of application objects.
      Parameters:
      loader - a ClassLoader
      Returns:
      the Serializer to use with the specified ClassLoader

    • toLiteBinary

      public static Binary toLiteBinary(ExternalizableLite o)
      Write an ExternalizableLite object into a Binary object. Unlike the toBinary, this method only serializes the object's content and not the identity part. To reconstruct the object frm that binary you would instantiate and "read" it as follows: 
         ExternalizableLite o = new MyLiteObject();
   o.readExternal(bin.getBufferInput());
      Parameters:
      o - the ExternalizableLite object to write into a Binary object
      Returns:
      a Binary object containing a serialized form of the passed object
      Throws:
      WrapperException - may contain an IOException

    • isVersionCompatible

      public static boolean isVersionCompatible(DataInput in, int nMajor, int nMinor, int nMicro, int nPatchSet, int nPatch)
      Determine whether the sender of the content (the given DataInput) runs a version that supersedes (greater or equal to) the specified version.
      Parameters:
      in - the DataInput to interrogate
      nMajor - the major version
      nMinor - the minor version
      nMicro - the micro version
      nPatchSet - the patch set version
      nPatch - the patch version
      Returns:
      true iff the sender's version is greater or equal to the specified one
      Throws:
      IllegalArgumentException - if the DataInput is not a VersionAwareBufferInput

    • isVersionCompatible

      public static boolean isVersionCompatible(DataInput in, int nYear, int nMonth, int nPatch)
      Determine whether the sender of the content (the given DataInput) runs a version that supersedes (greater or equal to) the specified version.
      Parameters:
      in - the DataInput to interrogate
      nYear - the year segment of the calendar based version
      nMonth - the month segment of the calendar based version
      nPatch - the patch segment of the calendar based version
      Returns:
      true iff the sender's version is greater or equal to the specified one
      Throws:
      IllegalArgumentException - if the DataInput is not a VersionAwareBufferInput

    • isVersionCompatible

      public static boolean isVersionCompatible(DataOutput out, int nMajor, int nMinor, int nMicro, int nPatchSet, int nPatch)
      Determine whether all the recipients of the content (the given DataOutput) run versions that supersede (greater or equal to) the specified version.
      Parameters:
      out - the DataOutput to interrogate
      nMajor - the major version
      nMinor - the minor version
      nMicro - the micro version
      nPatchSet - the patch set version
      nPatch - the patch version
      Returns:
      true iff the sender's version is greater or equal to the specified one
      Throws:
      IllegalArgumentException - if the DataOutput is not a VersionAwareBufferOutput

    • isVersionCompatible

      public static boolean isVersionCompatible(DataOutput out, int nYear, int nMonth, int nPatch)
      Determine whether all the recipients of the content (the given DataOutput) run versions that supersede (greater or equal to) the specified version.
      Parameters:
      out - the DataOutput to interrogate
      nYear - the year segment of the calendar based version
      nMonth - the month segment of the calendar based version
      nPatch - the patch segment of the calendar based version
      Returns:
      true iff the sender's version is greater or equal to the specified one
      Throws:
      IllegalArgumentException - if the DataOutput is not a VersionAwareBufferOutput

    • readTrint

      public static int readTrint(DataInput in) throws IOException
      Read a signed three-byte integer value from a stream.
      Parameters:
      in - DataInput stream to read from
      Returns:
      a three-byte signed integer value as an int
      Throws:
      IOException - if an I/O exception occurs

    • readUnsignedTrint

      public static int readUnsignedTrint(DataInput in) throws IOException
      Read an unsigned three-byte integer value from a stream.
      Parameters:
      in - DataInput stream to read from
      Returns:
      a three-byte unsigned integer value as an int
      Throws:
      IOException - if an I/O exception occurs

    • writeTrint

      public static void writeTrint(DataOutput out, int n) throws IOException
      Write a three-byte integer value to a stream.
      Parameters:
      out - DataOutput stream to write to
      n - a three-byte integer value passed as an int
      Throws:
      IOException - if an I/O exception occurs

    • writeTrint

      public static void writeTrint(DataOutput out, long l) throws IOException
      Write a three-byte integer value to a stream.
      Parameters:
      out - DataOutput stream to write to
      l - a three-byte integer value passed as an long
      Throws:
      IOException - if an I/O exception occurs

    • makeTrint

      public static int makeTrint(long l)
      Convert a long integer to a trint.
      Parameters:
      l - the long value to convert to a trint
      Returns:
      the equivalent unsigned 3-byte integer value (a "trint")

    • readInt

      public static int readInt(ReadBuffer.BufferInput in) throws IOException
      Read an int that uses variable length storage in the buffer.
      Parameters:
      in - a BufferInput to read from
      Returns:
      an int value
      Throws:
      IOException - if an I/O exception occurs

    • readInt

      public static int readInt(DataInput in) throws IOException
      Read an int that uses variable length storage in the stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      an int value
      Throws:
      IOException - if an I/O exception occurs

    • calculatePackedLength

      public static int calculatePackedLength(int n)
      Calculate the number of bytes needed to store a packed integer using a variable-length format.

      The format differs from DataOutput in that DataOutput always uses a fixed-length 4-byte Big Endian binary format for int values. The "packed" format includes a sign bit (0x40) and a continuation bit (0x80) in the first byte, followed by the least 6 significant bits of the int value. Subsequent bytes (each appearing only if the previous byte had its continuation bit set) include a continuation bit (0x80) and the next least 7 significant bits of the int value. In this way, a 32-bit value is encoded into 1-5 bytes, depending on the magnitude of the int value being encoded.

      Parameters:
      n - the value to calculate the packed length of
      Returns:
      the number of bytes needed to store the value

    • writeInt

      public static void writeInt(WriteBuffer.BufferOutput out, int n) throws IOException
      Write an int to a buffer using a variable length of storage.
      Parameters:
      out - a BufferOutput to write to
      n - an int value to write
      Throws:
      IOException - if an I/O exception occurs

    • writeInt

      public static void writeInt(DataOutput out, int n) throws IOException
      Write an int to a stream using a variable length of storage.
      Parameters:
      out - a DataOutput stream to write to
      n - an int value to write
      Throws:
      IOException - if an I/O exception occurs

    • readIntArray2d

      public static int[][] readIntArray2d(DataInput in) throws IOException
      Read a 2-dimensional int-array from the stream.
      Parameters:
      in - the input stream to read from
      Returns:
      the 2-dimensional int-array
      Throws:
      IOException - if an I/O Exception occurs

    • writeIntArray2d

      public static void writeIntArray2d(DataOutput out, int[][] aai) throws IOException
      Write a 2-dimensional int-array to the stream
      Parameters:
      out - the output stream to write to
      aai - the 2-dimensional int-array to write
      Throws:
      IOException - if an I/O Exception occurs
      NullPointerException - if the array is null

    • readLong

      public static long readLong(ReadBuffer.BufferInput in) throws IOException
      Read a long that uses variable length storage in the buffer.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a long value
      Throws:
      IOException - if an I/O exception occurs

    • readLong

      public static long readLong(DataInput in) throws IOException
      Read a long that uses variable length storage in the stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a long value
      Throws:
      IOException - if an I/O exception occurs

    • calculatePackedLength

      public static int calculatePackedLength(long l)
      Calculate the number of bytes needed to store a packed long using a variable-length format.

      The format differs from DataOutput in that DataOutput always uses a fixed-length 8-byte Big Endian binary format for long values. The "packed" format includes a sign bit (0x40) and a continuation bit (0x80) in the first byte, followed by the least 6 significant bits of the long value. Subsequent bytes (each appearing only if the previous byte had its continuation bit set) include a continuation bit (0x80) and the next least 7 significant bits of the long value. In this way, a 64-bit value is encoded into 1-10 bytes, depending on the magnitude of the long value being encoded.

      Parameters:
      l - the long value to calculate the packed length of
      Returns:
      the number of bytes needed to store the value

    • writeLong

      public static void writeLong(WriteBuffer.BufferOutput out, long l) throws IOException
      Write a long to a buffer using a variable length of storage.
      Parameters:
      out - a BufferOutput stream to write to
      l - a long value to write
      Throws:
      IOException - if an I/O exception occurs

    • writeLong

      public static void writeLong(DataOutput out, long l) throws IOException
      Write a long to a stream using a variable length of storage.
      Parameters:
      out - a DataOutput stream to write to
      l - a long value to write
      Throws:
      IOException - if an I/O exception occurs

    • readBooleanArray

      public static boolean[] readBooleanArray(DataInput in) throws IOException
      Read a packed boolean array.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a boolean array value
      Throws:
      IOException - if an I/O exception occurs

    • writeBooleanArray

      public static void writeBooleanArray(DataOutput out, boolean[] af) throws IOException
      Write a packed boolean array.
      Parameters:
      out - a DataOutput stream to write to
      af - a boolean array value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readByteArray

      public static byte[] readByteArray(DataInput in) throws IOException
      Read a variable-length encoded byte array.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a byte array value
      Throws:
      IOException - if an I/O exception occurs

    • writeByteArray

      public static void writeByteArray(DataOutput out, byte[] ab) throws IOException
      Write a variable-length encoded byte array.
      Parameters:
      out - a DataOutput stream to write to
      ab - a byte array value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readUTF

      public static String readUTF(DataInput in) throws IOException
      Read a variable-length encoded UTF packed String. The major difference between this implementation and DataInputStream is that this is not limited to 64KB String values.

      Note: This format changed in Coherence 3.0; previously the leading integer value was the number of characters, and currently it is the number of bytes as per the java.io package implementations.

      Parameters:
      in - a DataInput stream to read from
      Returns:
      a String value
      Throws:
      IOException - if an I/O exception occurs

    • convertUTF

      public static String convertUTF(byte[] ab, int of, int cb, char[] ach) throws UTFDataFormatException
      Convert binary UTF-8 encode data to a String. This method is a helper to allow various I/O implementations to share a single, efficient implementation.
      Parameters:
      ab - an array of bytes containing UTF-8 encoded characters
      of - the offset into the array of the UTF-8 data to decode
      cb - the binary length in the array of the UTF-8 data to decode
      ach - a temp char array large enough to convert the UTF into
      Returns:
      a String value
      Throws:
      UTFDataFormatException - if the UTF data is corrupt

    • writeUTF

      public static void writeUTF(DataOutput out, String s) throws IOException
      Write a variable-length encoded UTF packed String. The major difference between this implementation and DataOutput stream is that this is not limited to 64KB String values.

      Note: This format changed in Coherence 3.0; previously the leading integer value was the number of characters, and currently it is the number of bytes as per the java.io package implementations.

      Parameters:
      out - a DataOutput stream to write to
      s - a String value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readSafeUTF

      public static String readSafeUTF(ReadBuffer.BufferInput in) throws IOException
      Read a variable-length encoded UTF packed String in the buffer.
      Parameters:
      in - a BufferInput to read from
      Returns:
      a String value
      Throws:
      IOException - if an I/O exception occurs

    • readSafeUTF

      public static String readSafeUTF(DataInput in) throws IOException
      Read a variable-length encoded UTF packed String. The major difference between this implementation and DataInputStream is that this is not limited to 64KB String values and allows null value.

      Note: This format changed in Coherence 3.0; previously the leading integer value was the number of characters, and currently it is the number of bytes as per the java.io package implementations.

      Parameters:
      in - a DataInput stream to read from
      Returns:
      a String value (could be null)
      Throws:
      IOException - if an I/O exception occurs

    • writeSafeUTF

      public static void writeSafeUTF(WriteBuffer.BufferOutput out, String s) throws IOException
      Write a variable-length encoded UTF packed String to the buffer.
      Parameters:
      out - a BufferOutput to write to
      s - a String value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • writeSafeUTF

      public static void writeSafeUTF(DataOutput out, String s) throws IOException
      Write a variable-length encoded UTF packed String. The major difference between this implementation and DataOutput stream is that this is not limited to 64KB String values and allows null value.

      Note: This format changed in Coherence 3.0; previously the leading integer value was the number of characters, and currently it is the number of bytes as per the java.io package implementations.

      Parameters:
      out - a DataOutput stream to write to
      s - a String value to write (could be null)
      Throws:
      IOException - if an I/O exception occurs

    • readStringArray

      public static String[] readStringArray(DataInput in) throws IOException
      Read a String array.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a String array value
      Throws:
      IOException - if an I/O exception occurs

    • writeStringArray

      public static void writeStringArray(DataOutput out, String[] as) throws IOException
      Write a String array.
      Parameters:
      out - a DataOutput stream to write to
      as - a String array to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readBigInteger

      public static BigInteger readBigInteger(DataInput in) throws IOException
      Read a BigInteger from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a BigInteger value
      Throws:
      IOException - if an I/O exception occurs

    • writeBigInteger

      public static void writeBigInteger(DataOutput out, BigInteger bigint) throws IOException
      Write a BigInteger to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      bigint - a BigInteger value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readBigDecimal

      public static BigDecimal readBigDecimal(DataInput in) throws IOException
      Read a BigDecimal from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a BigDecimal value
      Throws:
      IOException - if an I/O exception occurs

    • writeBigDecimal

      public static void writeBigDecimal(DataOutput out, BigDecimal dec) throws IOException
      Write a BigDecimal to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      dec - a BigDecimal value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readDate

      public static Date readDate(DataInput in) throws IOException
      Read a Date from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a Date value
      Throws:
      IOException - if an I/O exception occurs

    • writeDate

      public static void writeDate(DataOutput out, Date date) throws IOException
      Write a Date to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      date - a Date value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readTime

      public static Time readTime(DataInput in) throws IOException
      Read a Time from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a Time value
      Throws:
      IOException - if an I/O exception occurs

    • writeTime

      public static void writeTime(DataOutput out, Time time) throws IOException
      Write a Time to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      time - a Time value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readTimestamp

      public static Timestamp readTimestamp(DataInput in) throws IOException
      Read a Timestamp from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a Timestamp value
      Throws:
      IOException - if an I/O exception occurs

    • writeTimestamp

      public static void writeTimestamp(DataOutput out, Timestamp dt) throws IOException
      Write a Timestamp to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      dt - a Timestamp value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readFloatArray

      public static float[] readFloatArray(DataInput in) throws IOException
      Read an array of float numbers from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      an array of floats
      Throws:
      IOException - if an I/O exception occurs

    • writeFloatArray

      public static void writeFloatArray(DataOutput out, float[] afl) throws IOException
      Write an array of float numbers to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      afl - an array of floats to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readDoubleArray

      public static double[] readDoubleArray(DataInput in) throws IOException
      Read an array of double numbers from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      an array of doubles
      Throws:
      IOException - if an I/O exception occurs

    • writeDoubleArray

      public static void writeDoubleArray(DataOutput out, double[] ad) throws IOException
      Write an array of double numbers to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      ad - an array of doubles to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readMap

      public static int readMap(DataInput in, Map map, ClassLoader loader) throws IOException
      Read map content from a DataInput stream and update the specified map.

      This method reads entries from the stream and "puts" them into the specified map one-by-one using the "put" method.

      Parameters:
      in - a DataInput stream to read from
      map - a map to add the entries into
      loader - the ClassLoader to use
      Returns:
      the number of read and inserted entries
      Throws:
      IOException - if an I/O exception occurs
      See Also:

    • readMap

      public static int readMap(DataInput in, Map map, int cBlock, ClassLoader loader) throws IOException
      Read map content from a DataInput stream and update the specified map using the "putAll" method.

      While the method readMap(DataInput, Map, ClassLoader) reads entries from the stream and "puts" them into the specified map one-by-one, this method collects up to the "block" number of entries into a temporary map and then updates the passed in map using the "putAll" method.

      Parameters:
      in - a DataInput stream to read from
      map - a map to add the entries into
      cBlock - the maximum number of entries to read at once
      loader - the ClassLoader to use
      Returns:
      the number of read and inserted entries
      Throws:
      IOException - if an I/O exception occurs

    • writeMap

      public static void writeMap(DataOutput out, Map map) throws IOException
      Write map content to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      map - the map to write
      Throws:
      IOException - if an I/O exception occurs

    • readCollection

      public static int readCollection(DataInput in, Collection collection, ClassLoader loader) throws IOException
      Read collection content from a DataInput stream and update the specified collection.

      This method reads elements from the stream and adds them into the specified collection one-by-one using the "add" method.

      Parameters:
      in - a DataInput stream to read from
      collection - a collection to add the elements into
      loader - the ClassLoader to use
      Returns:
      the number of read and inserted elements
      Throws:
      IOException - if an I/O exception occurs

    • writeCollection

      public static void writeCollection(DataOutput out, Collection collection) throws IOException
      Write collection content to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      collection - the collection to write
      Throws:
      IOException - if an I/O exception occurs

    • readXmlSerializable

      public static XmlSerializable readXmlSerializable(DataInput in) throws IOException
      Read an XmlSerializable object from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      an XmlSerializable value
      Throws:
      IOException - if an I/O exception occurs

    • readXmlSerializable

      public static XmlSerializable readXmlSerializable(DataInput in, ClassLoader loader) throws IOException
      Read an XmlSerializable object from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      loader - the ClassLoader to use
      Returns:
      an XmlSerializable value
      Throws:
      IOException - if an I/O exception occurs

    • writeXmlSerializable

      public static void writeXmlSerializable(DataOutput out, XmlSerializable o) throws IOException
      Write an XmlSerializable object to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      o - an XmlSerializable value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readExternalizableLite

      public static ExternalizableLite readExternalizableLite(DataInput in) throws IOException
      Read an ExternalizableLite object from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      an ExternalizableLite value
      Throws:
      IOException - if an I/O exception occurs

    • readExternalizableLite

      public static ExternalizableLite readExternalizableLite(DataInput in, ClassLoader loader) throws IOException
      Read an ExternalizableLite object from a DataInput stream.

      If the class of the object in the DataInput stream is an ExternalizableLite class annotated with ExternalizableType, use the specified serializer's deserialize method to deserialize the object from the DataInput stream.

      Parameters:
      in - a DataInput stream to read from
      loader - the ClassLoader to use
      Returns:
      an ExternalizableLite value
      Throws:
      IOException - if an I/O exception occurs

    • validateLoadClass

      protected static void validateLoadClass(Class clz, DataInput in) throws InvalidClassException
      Validate that the given class is permitted to be deserialized by consulting any associated ObjectInputFilters.
      Parameters:
      clz - the class to be validated
      in - input context to use to validate if class is allowed to be loaded
      Throws:
      InvalidClassException - if ObjectInputFilter associated with in rejects class clz

    • validateLoadArray

      public static void validateLoadArray(Class clz, int cLength, DataInput in) throws InvalidClassException
      Validate that the given class and array length is permitted to be deserialized by consulting any associated ObjectInputFilters.
      Parameters:
      clz - the array type to be validated
      cLength - the array length to be validated
      in - input context to use to validate if class is allowed to be loaded
      Throws:
      InvalidClassException - if ObjectInputFilter associated with in rejects array length

    • writeExternalizableLite

      public static void writeExternalizableLite(DataOutput out, ExternalizableLite o) throws IOException
      Write an ExternalizableLite object to a DataOutput stream.

      If the class of parameter o is annotated with ExternalizableType, use the specified serializer's serialize method to write o into the DataOutput stream.

      Parameters:
      out - a DataOutput stream to write to
      o - an ExternalizableLite value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readXmlBean

      public static XmlBean readXmlBean(DataInput in, ClassLoader loader) throws IOException
      Read an XmlBean object from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      loader - the ClassLoader to use
      Returns:
      an XmlBean value
      Throws:
      IOException - if an I/O exception occurs

    • writeXmlBean

      public static void writeXmlBean(DataOutput out, XmlBean bean) throws IOException
      Write an XmlBean object to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      bean - an XmlBean value to write
      Throws:
      IOException - if an I/O exception occurs
      NullPointerException - if null value if passed

    • readSerializable

      public static Object readSerializable(DataInput in) throws IOException
      Read an object from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a value object
      Throws:
      IOException - if an I/O exception occurs

    • readSerializable

      public static Object readSerializable(DataInput in, ClassLoader loader) throws IOException
      Read an object from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      loader - the ClassLoader to use
      Returns:
      a value object
      Throws:
      IOException - if an I/O exception occurs

    • writeSerializable

      public static void writeSerializable(DataOutput out, Object o) throws IOException
      Write an object to a DataOutput stream.
      Parameters:
      out - a DataOutput stream to write to
      o - a value object to write
      Throws:
      IOException - if an I/O exception occurs

    • readObject

      public static <T> T readObject(DataInput in) throws IOException
      Read an Object from the passed DataInput object.
      Type Parameters:
      T - the class of the object read
      Parameters:
      in - the DataInput stream to read an object from
      Returns:
      the object read from the DataInput; may be null
      Throws:
      IOException - if an I/O exception occurs

    • readObject

      public static <T> T readObject(DataInput in, ClassLoader loader) throws IOException
      Read an Object from the passed DataInput object.
      Type Parameters:
      T - the class of the object read
      Parameters:
      in - the DataInput stream to read an object from
      loader - the ClassLoader to use
      Returns:
      the object read from the DataInput; may be null
      Throws:
      IOException - if an I/O exception occurs

    • writeObject

      public static void writeObject(DataOutput out, Object o) throws IOException
      Write the specified data to the passed DataOutput object.
      Parameters:
      out - the DataOutput stream to write to
      o - the data to write to the DataOutput; may be null
      Throws:
      IOException - if an I/O exception occurs

    • validateBufferSize

      public static void validateBufferSize(int cb)
      Verify that the requested buffer size is smaller than the configured maximum.
      Parameters:
      cb - size of the buffer being requested
      Throws:
      BufferOverflowException - if cb > MAX_BUFFER

    • getDeltaCompressor

      public static DeltaCompressor getDeltaCompressor(Serializer serializer, DeltaCompressor compressor)
      Return a DeltaCompressor suitable for compressing/extracting binaries produced by ExternalizableHelper using the specified serializer. The returned DeltaCompressor will use the specified compressor to compress/extract binaries in the format produced directly by the specified serializer.
      Parameters:
      serializer - the serializer whose produced binary format is consumed by the specified compressor
      compressor - the compressor
      Returns:
      a DeltaCompressor

    • loadClass

      public static Class loadClass(String sClass, ClassLoader loader1, ClassLoader loader2) throws ClassNotFoundException
      Attempt to load the specified class using sequentionally all of the specified loaders, the ContextClassLoader and the current class loader.
      Parameters:
      sClass - the class name
      loader1 - first ClassLoader to try
      loader2 - second ClassLoader to try
      Returns:
      the Class for the specified name
      Throws:
      ClassNotFoundException - if all the attempts fail

    • loadResource

      public static URL loadResource(String sName, ClassLoader loader1, ClassLoader loader2)
      Attempt to find a valid, resolvable URL for the specified resource, first by using each of the specified ClassLoaders, then using the ContextClassLoader.
      Parameters:
      sName - the resource name
      loader1 - first ClassLoader to try
      loader2 - second ClassLoader to try
      Returns:
      the URL for the specified resource name, or null if the resource could not be found

    • getInputStream

      public static InputStream getInputStream(DataInput in)
      Get an InputStream for the passed DataInput object.
      Parameters:
      in - an Object implementing the DataInput interface
      Returns:
      an Object of type InputStream

    • getOutputStream

      public static OutputStream getOutputStream(DataOutput out)
      Get an OutputStream for the passed DataOutput object.
      Parameters:
      out - an Object implementing the DataOutput interface
      Returns:
      an Object of type OutputStream

    • getShieldedOutputStream

      public static OutputStream getShieldedOutputStream(OutputStream out)
      Get a shielded OutputStream for the passed OutputStream object.
      Parameters:
      out - an OutputStream
      Returns:
      an OutputStream that implements the Shielded interface

    • getObjectInput

      public static ObjectInput getObjectInput(DataInput in, ClassLoader loader) throws IOException
      Get an ObjectInput for the passed DataInput object.
      Parameters:
      in - an Object implementing the DataInput interface
      loader - the ClassLoader to use
      Returns:
      an Object of type ObjectInput
      Throws:
      IOException - if an I/O exception occurs

    • getNewObjectInput

      public static ObjectInput getNewObjectInput(DataInput in, ClassLoader loader) throws IOException
      Get a new ObjectInput for the passed DataInput, even if the passed DataInput is an ObjectInput.
      Parameters:
      in - an Object implementing the DataInput interface
      loader - the ClassLoader to use
      Returns:
      an Object of type ObjectInput that is guaranteed not to be the same reference as in
      Throws:
      IOException - if an I/O exception occurs

    • getObjectOutput

      public static ObjectOutput getObjectOutput(DataOutput out) throws IOException
      Get an ObjectOutput for the passed DataOutput object.
      Parameters:
      out - an Object implementing the DataOutput interface
      Returns:
      an Object of type ObjectOutput
      Throws:
      IOException - if an I/O exception occurs

    • isResolving

      public static boolean isResolving(DataOutput out)
      Determine whether the passed DataOutput handles ClassLoader resolving. Note that the ClassLoader resolving on the "write" side is necessary only to make the stream format symetrical for the "read" side.
      Parameters:
      out - an object implementing DataOutput
      Returns:
      true if the object implementing DataOutput also implements ObjectOutput and handles ClassLoader resolving

    • getObjectStreamFactory

      public static ObjectStreamFactory getObjectStreamFactory()
      Return the ObjectStreamFactory used to convert DataInput/Output into ObjectInput/Output streams.
      Returns:
      the currently used ObjectStreamFactory

    • setObjectStreamFactory

      public static void setObjectStreamFactory(ObjectStreamFactory factory)
      Specify an ObjectStreamFactory that should be used to convert DataInput/Output into ObjectInput/Output streams.

      Warning: This facility should be used with extreme care; failure to set the ObjectStreamFactory identically on all cluster nodes may render some of all clustered services completely inoperable,

      Parameters:
      factory - the ObjectStreamFactory to use

    • isSerializable

      public static boolean isSerializable(Object o)
      Determine if the resource object can be serialized using the DefaultSerializer.
      Parameters:
      o - the resource object
      Returns:
      true iff the resource object can be serialized by the DefaultSerializer

    • getStreamFormat

      public static int getStreamFormat(Object o)
      Internal: Select an optimal stream format to use to store the passed object in a stream (as used by the DefaultSerializer).
      Parameters:
      o - an Object
      Returns:
      a stream format to use to store the object in a stream

    • isSerializerCompatible

      public static boolean isSerializerCompatible(Serializer serializerThis, Serializer serializerThat)
      Determines whether or not the specified serializers are compatible. In other words, this method returns true iff object serialized with the first Serializer can be deserialized by the second and visa versa.
      Parameters:
      serializerThis - the first Serializer
      serializerThat - the second Serializer
      Returns:
      true iff the two Serializers are stream compatible

    • reportIncompatibleSerializers

      public static void reportIncompatibleSerializers(NamedCache cache, String sService, Serializer serializer)
      Log the message explaining the serializer incompatibility between the specified cache and a service.
      Parameters:
      cache - the NamedCache reference
      sService - the service name
      serializer - the serializer used by the service

    • isDecorated

      public static boolean isDecorated(ReadBuffer buf)
      If the ReadBuffer is the result of serialization by ExternalizableHelper, determine if the buffer contains decorations.

      Note: This method can only be used against ReadBuffers that result from serialization by ExternalizableHelper or buffers that are already decorated.

      Parameters:
      buf - the ReadBuffer to check
      Returns:
      true iff the ReadBuffer is decorated

    • isDecorated

      public static boolean isDecorated(ReadBuffer buf, int nId)
      If the ReadBuffer is the result of serialization by ExternalizableHelper, determine if the buffer contains the specified decoration.

      Note: This method can only be used against ReadBuffers that result from serialization by ExternalizableHelper or buffers that are already decorated.

      Parameters:
      buf - the ReadBuffer to check
      nId - the identifier for the decoration to check
      Returns:
      true iff the ReadBuffer is decorated with the specified decoration

    • decorate

      public static Binary decorate(Binary bin, int nId, Binary binDecoration)
      Decorate the passed value with the specified decoration and return the resulting Binary. The passed value may or may not already be decorated.

      The decoration id must be in range defined by DECO_ID_MIN and DECO_ID_MAX. A series of DECO_* constants are defined for the pre-approved decorations, including:

      All other potential decoration id values are reserved. Product and framework developers that require a new decoration id to be assigned to them should contact the Coherence product development team.

      Note: This method can only be used against Binary values that result from serialization by ExternalizableHelper or Binary values that are already decorated.

      Parameters:
      bin - the Binary to decorate, which may already be decorated
      nId - the identifier for the decoration, one of the DECO_* constants
      binDecoration - the decoration to apply; a null value will remove the specified decoration
      Returns:
      a decorated Binary containing the passed decoration

    • decorate

      public static ReadBuffer decorate(ReadBuffer bufOrig, int nId, ReadBuffer bufDeco)
      Decorate the passed value with the specified decoration and return the resulting ReadBuffer. The passed value may or may not already be decorated.

      The decoration id must be in range defined by DECO_ID_MIN and DECO_ID_MAX. A series of DECO_* constants are defined for the pre-approved decorations, including:

      All other potential decoration id values are reserved. Product and framework developers that require a new decoration id to be assigned to them should contact the Coherence product development team.

      Note: This method can only be used against ReadBuffers that result from serialization by ExternalizableHelper or buffers that are already decorated.

      Parameters:
      bufOrig - the ReadBuffer to decorate, which may already be decorated
      nId - the identifier for the decoration, one of the DECO_* constants
      bufDeco - the decoration to apply; a null value will remove the specified decoration
      Returns:
      a decorated ReadBuffer containing the passed decoration

    • decorate

      public static Binary decorate(Binary bin, Binary[] abinDecorations)
      Deprecated.
      as of Coherence 3.7.2
      Decorate the passed Binary with the passed decorations. If the passed Binary is decorated, use its decorations as the defaults and the passed decorations as the overrides; if the passed Binary is not decorated, then use it as the default for the "value" decoration.

      Note: This method can only be used against Binary values that result from serialization by ExternalizableHelper or Binary values that are already decorated.

      Parameters:
      bin - the Binary to decorate, which may already be decorated; may be null
      abinDecorations - the decorations to apply; each non-null element is assumed to be a decoration to add whose identifier is its index in the array; the array contents will not be modified by this method
      Returns:
      a decorated Binary containing the passed decorations

    • decorate

      public static ReadBuffer decorate(ReadBuffer buf, ReadBuffer[] abufDeco)
      Decorate the passed Binary with the passed decorations. If the passed Binary is decorated, use its decorations as the defaults and the passed decorations as the overrides; if the passed Binary is not decorated, then use it as the default for the "value" decoration.

      Note: This method can only be used against Binary values that result from serialization by ExternalizableHelper or Binary values that are already decorated.

      Parameters:
      buf - the Binary to decorate, which may already be decorated; may be null
      abufDeco - the decorations to apply; each non-null element is assumed to be a decoration to add whose identifier is its index in the array; the array contents will not be modified by this method
      Returns:
      a decorated Binary containing the passed decorations

    • getDecoration

      public static Binary getDecoration(Binary bin, int nId)
      Deprecated.
      as of Coherence 3.7.2
      Extract and return the specified decoration from the passed Binary.

      Note: This method can only be used against Binary values that result from serialization by ExternalizableHelper or Binary values that are already decorated.

      Parameters:
      bin - the Binary that may be decorated
      nId - the identifier for the decoration
      Returns:
      the Binary decoration, or null if the passed Binary is not decorated or if no decoration was found for the specified identifier

    • getDecoration

      public static ReadBuffer getDecoration(ReadBuffer buf, int nId)
      Extract and return the specified decoration from the passed ReadBuffer.

      Note: This method can only be used against ReadBuffers that result from serialization by ExternalizableHelper or buffers that are already decorated.

      Parameters:
      buf - the ReadBuffer that may be decorated
      nId - the identifier for the decoration
      Returns:
      the decoration, or null if the passed ReadBuffer is not decorated or if no decoration was found for the specified identifier

    • getDecorations

      public static ReadBuffer[] getDecorations(ReadBuffer buf)
      Return an array containing all of the decorations from the passed ReadBuffer.

      If the passed value is not decorated, then the result is a single- element array containing the undecorated value, which is the DECO_VALUE decoration.

      Note: This method can only be used against ReadBuffers that result from serialization by ExternalizableHelper or buffers that are already decorated.

      Parameters:
      buf - the ReadBuffer that may be decorated
      Returns:
      an array of all decorations on the passed ReadBuffer, indexed by the DECO_* constants

    • undecorate

      public static Binary undecorate(Binary bin, int nId)
      Deprecated.
      as of Coherence 3.7.2
      Remove the specified decoration from the passed Binary. If the resulting Binary has no decorations remaining, then return the undecorated Binary; otherwise return the decorated Binary with the remaining decorations.

      Note: This method can only be used against Binary values that result from serialization by ExternalizableHelper or Binary values that are already decorated.

      Parameters:
      bin - the Binary to undecorate
      nId - the identifier for the decoration to remove
      Returns:
      a Binary that may be decorated or undecorated

    • undecorate

      public static ReadBuffer undecorate(ReadBuffer buf, int nId)
      Remove the specified decoration from the passed ReadBuffer and return the resulting contents (which may be undecorated, or contain the remaining decorations).

      Note: This method can only be used against ReadBuffers that result from serialization by ExternalizableHelper or buffers that are already decorated.

      Parameters:
      buf - the ReadBuffer to undecorate
      nId - the identifier for the decoration to remove
      Returns:
      a ReadBuffer that may or may not be decorated

    • getUndecorated

      public static Binary getUndecorated(Binary bin)
      Deprecated.
      as of Coherence 3.7.2
      If the passed Binary is decorated, extract the original Binary value that the decorations were added to, otherwise return the passed Binary value.

      Note: This method can only be used against Binary values that result from serialization by ExternalizableHelper or Binary values that are already decorated.

      Parameters:
      bin - the Binary object
      Returns:
      the undecorated Binary value, or null if the Binary value is decorated but does not contain an original Binary value

    • getUndecorated

      public static ReadBuffer getUndecorated(ReadBuffer buf)
      If the passed ReadBuffer is decorated, extract the original contents that the decorations were added to, otherwise return the passed Binary value.

      Note: This method can only be used against ReadBuffers that result from serialization by ExternalizableHelper or buffers that are already decorated.

      Parameters:
      buf - the ReadBuffer object
      Returns:
      the undecorated ReadBuffer, or null if the specified buffer is decorated but does not contain an actual value

    • asBinary

      public static Binary asBinary(ReadBuffer buf)
      Return a Binary representing the contents of the specified ReadBuffer, or null if the buffer is null.
      Parameters:
      buf - the read buffer
      Returns:
      the contents of the read buffer as a Binary object, or null

    • replace

      public static Object replace(Object o) throws ObjectStreamException
      Potentially replaces specified argument with a different object before serialization.
      Parameters:
      o - the object to replace, if necessary
      Returns:
      the replacement object
      Throws:
      ObjectStreamException - if an error occurs

    • realize

      public static <T> T realize(Object o, Serializer serializer) throws ObjectStreamException
      Realizes object after deserialization by applying post-serialization rules.
      Type Parameters:
      T - the class of realized object
      Parameters:
      o - the object to realize
      serializer - the serializer that was used to deserialize the object
      Returns:
      fully realized object
      Throws:
      ObjectStreamException - if an error occurs

    • main

      public static void main(String[] asArgs)
      Parse a hex string representing a serialized object.

      Example: 

         java com.tangosol.util.ExternalizableHelper 0x0603486921
      Parameters:
      asArgs - the hex string as the command line arguments

    • encodeExpiry

      public static ReadBuffer encodeExpiry(ReadBuffer buf, long ldtExpiry)
      Return a ReadBuffer whose contents represent the specified buffer with the specified expiry encoded as a DECO_EXPIRY decoration. The encoded expiry can be decoded via the decodeExpiry(com.tangosol.io.ReadBuffer) method.
      Parameters:
      buf - the buffer to encode
      ldtExpiry - the expiry time, or CacheMap.EXPIRY_DEFAULT or CacheMap.EXPIRY_NEVER
      Returns:
      an expiry-encoded ReadBuffer

    • decodeExpiry

      public static long decodeExpiry(ReadBuffer buf)
      Decode the expiry time from the specified ReadBuffer.
      Parameters:
      buf - the buffer to decode
      Returns:
      the decoded expiry, or CacheMap.EXPIRY_DEFAULT if none exists

    • decorate

      public static ExternalizableHelper.IntDecoratedObject decorate(Object oValue, int nDecoration)
      Decorate the specified value with the specified integer decoration.
      Parameters:
      oValue - the value to be decorated
      nDecoration - the integer decoration
      Returns:
      the decorated object

    • decorateBinary

      public static ReadBuffer decorateBinary(ReadBuffer bufValue, int nDecoration)
      Decorate the specified ReadBuffer with the specified integer decoration.
      Parameters:
      bufValue - the ReadBuffer to be decorated
      nDecoration - the integer decoration
      Returns:
      the decorated (with integer decoration) ReadBuffer

    • isIntDecorated

      @Deprecated public static boolean isIntDecorated(ReadBuffer buf)
      Deprecated.
      use isIntDecorated(ByteSequence) instead
      Check whether or not the specified ReadBuffer is a representation of an IntDecoratedObject.
      Parameters:
      buf - the ReadBuffer
      Returns:
      true iff the buffer contains (starts with) a representation of an IntDecoratedObject

    • isIntDecorated

      public static boolean isIntDecorated(ByteSequence buf)
      Check whether or not the specified ByteSequence is a representation of an IntDecoratedObject.
      Parameters:
      buf - the ByteSequence
      Returns:
      true iff the buffer contains (starts with) a representation of an IntDecoratedObject

    • extractIntDecoration

      public static int extractIntDecoration(ReadBuffer buf)
      Extract a decoration value from the specified ReadBuffer that contains a representation of an IntDecoratedObject.
      Parameters:
      buf - the ReadBuffer
      Returns:
      the integer decoration value

    • removeIntDecoration

      public static Binary removeIntDecoration(Binary bin)
      Deprecated.
      as of Coherence 3.7.2
      Remove a decoration value from the specified Binary that contains a representation of an IntDecoratedObject.
      Parameters:
      bin - the Binary object
      Returns:
      the undecorated Binary value

    • removeIntDecoration

      public static ReadBuffer removeIntDecoration(ReadBuffer buf)
      Remove a decoration value from the specified ReadBuffer that contains a representation of an IntDecoratedObject.
      Parameters:
      buf - the ReadBuffer
      Returns:
      the undecorated ReadBuffer

    • readCharArray

      public static char[] readCharArray(DataInput in) throws IOException
      Read a char array.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      a char array value
      Throws:
      IOException - if an I/O exception occurs

    • readLongArray

      public static long[] readLongArray(DataInput in) throws IOException
      Read an array of long numbers from a DataInput stream that use fixed-length 8-byte Big Endian binary format.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      an array of longs
      Throws:
      IOException - if an I/O exception occurs

    • readIntArray

      public static int[] readIntArray(DataInput in) throws IOException
      Read an array of int numbers from a DataInput stream which use fixed-length 4-byte Big Endian binary format.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      an array of ints
      Throws:
      IOException - if an I/O exception occurs

    • readObjectArray

      public static Object[] readObjectArray(DataInput in) throws IOException
      Read an array of object from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      Returns:
      an array of object
      Throws:
      IOException - if an I/O exception occurs

    • checkObjectInputFilter

      protected static boolean checkObjectInputFilter(Class<?> clz, ObjectInputStream ois)
      Return true if the provided class is allowed to be deserialized.
      Parameters:
      clz - the class to be checked
      ois - the ObjectInputStream
      Returns:
      true if the provided class is allowed to be deserialized

    • checkObjectInputFilter

      protected static boolean checkObjectInputFilter(Class<?> clz, DataInput in)
      Return true if the provided class is allowed to be deserialized.
      Parameters:
      clz - the class to be checked
      in - input context containing ObjectInputFilter
      Returns:
      true if the provided class is allowed to be deserialized from in

    • checkObjectInputFilter

      protected static boolean checkObjectInputFilter(Class<?> clz, int cLength, DataInput in)
      Return true if the provided class is allowed to be deserialized.
      Parameters:
      clz - the class to be checked
      cLength - array length to be checked
      in - input context containing ObjectInputFilter
      Returns:
      true if the provided class is allowed to be deserialized from in

    • getObjectInputFilter

      protected static Object getObjectInputFilter(DataInput in)
      Return ObjectInputFilter associated with DataInput.
      Parameters:
      in - DataInput that may or may not have a ObjectInputFilter associated with it
      Returns:
      ObjectInputFilter associated with in or null when one does not exist

    • getConfigSerialFilter

      public static Object getConfigSerialFilter()
      Return the static JVM-wide serial filter or null if not configured.
      Returns:
      ObjectInputFilter as an Object to enable working with Java versions before 9 or null if no filter has been configured.

    • getConfigSerialFilterFactory

      public static BinaryOperator getConfigSerialFilterFactory()
      Return the static JVM-wide serial filter factory.
      Returns:
      deserialization filter factory for Java version 17 and greater, null otherwise.

    • readIntArray

      protected static int[] readIntArray(DataInput in, int c) throws IOException
      Read an array of the specified number of int from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      c - length to read
      Returns:
      an array of ints
      Throws:
      IOException - if an I/O exception occurs

    • readLargeIntArray

      protected static int[] readLargeIntArray(DataInput in, int cLength) throws IOException
      Read an array of ints with length larger than CHUNK_THRESHOLD >> 2.
      Parameters:
      in - a DataInput stream to read from
      cLength - length to read
      Returns:
      an array of ints
      Throws:
      IOException - if an I/O exception occurs

    • readObjectArray

      protected static Object[] readObjectArray(DataInput in, int cLength) throws IOException
      Read an array of the specified number of object from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      cLength - length to read
      Returns:
      an array of objects
      Throws:
      IOException - if an I/O exception occurs

    • readLargeObjectArray

      protected static Object[] readLargeObjectArray(DataInput in, int cLength) throws IOException
      Read an array of objects with length larger than CHUNK_THRESHOLD >> 4.
      Parameters:
      in - a DataInput stream to read from
      cLength - length to read
      Returns:
      an array of objects
      Throws:
      IOException - if an I/O exception occurs

    • readLongArray

      protected static long[] readLongArray(DataInput in, int cLength) throws IOException
      Read an array of the specified number of longs from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      cLength - length to read
      Returns:
      an array of longs
      Throws:
      IOException - if an I/O exception occurs

    • readLargeLongArray

      protected static long[] readLargeLongArray(DataInput in, int cLength) throws IOException
      Read an array of longs with length larger than CHUNK_THRESHOLD >> 3.
      Parameters:
      in - a DataInput stream to read from
      cLength - length to read
      Returns:
      an array of longs
      Throws:
      IOException - if an I/O exception occurs

    • readCharArray

      protected static char[] readCharArray(Utf8Reader reader, int cLength) throws IOException
      Read an array of char for the specified length from the reader.
      Parameters:
      reader - the Utf8Reader to read from
      cLength - the length to read
      Throws:
      IOException

    • readLargeCharArray

      protected static char[] readLargeCharArray(Utf8Reader reader, int cLength) throws IOException
      Read an array of char for the specified length from the reader.
      Parameters:
      reader - the Utf8Reader to read from
      cLength - the length to read
      Throws:
      IOException

    • readLargeByteArray

      protected static byte[] readLargeByteArray(DataInput in, int cb) throws IOException
      Read byte array with length larger than CHUNK_THRESHOLD.
      Parameters:
      in - a DataInput stream to read from
      cb - number of bytes to read
      Returns:
      a read byte array value
      Throws:
      IOException - if an I/O exception occurs

    • readBooleanArray

      protected static boolean[] readBooleanArray(DataInput in, int cLength) throws IOException
      Read the specified number of booleans from a boolean array.
      Parameters:
      in - a DataInput stream to read from
      cLength - the length to read
      Returns:
      a boolean array value
      Throws:
      IOException - if an I/O exception occurs

    • readLargeBooleanArray

      protected static boolean[] readLargeBooleanArray(DataInput in, int cLength) throws IOException
      Read a boolean array with length larger than CHUNK_THRESHOLD.
      Parameters:
      in - a DataInput stream to read from
      cLength - length to read
      Returns:
      the read boolean array
      Throws:
      IOException - if an I/O exception occurs

    • readFloatArray

      protected static float[] readFloatArray(DataInput in, int cfl) throws IOException
      Read an array of the specified number of floats from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      cfl - the length to read
      Returns:
      an array of floats
      Throws:
      IOException - if an I/O exception occurs

    • readLargeFloatArray

      protected static float[] readLargeFloatArray(DataInput in, int cLength) throws IOException
      Read a float array with length larger than CHUNK_THRESHOLD >> 2.
      Parameters:
      in - a DataInput stream to read from
      cLength - length to read
      Returns:
      the read float array value
      Throws:
      IOException - if an I/O exception occurs

    • readDoubleArray

      protected static double[] readDoubleArray(DataInput in, int cdfl) throws IOException
      Read an array of the specified number of doubles from a DataInput stream.
      Parameters:
      in - a DataInput stream to read from
      cdfl - length to read
      Returns:
      an array of doubles
      Throws:
      IOException - if an I/O exception occurs

    • readLargeDoubleArray

      protected static double[] readLargeDoubleArray(DataInput in, int cLength) throws IOException
      Read a double array with length larger than CHUNK_THRESHOLD >> 3.
      Parameters:
      in - a DataInput stream to read from
      cLength - the length to read
      Returns:
      an array of doubles
      Throws:
      IOException - if an I/O exception occurs

    • readStringArray

      protected static String[] readStringArray(DataInput in, int c) throws IOException
      Read array of string for the specified size.
      Parameters:
      in - a DataInput stream to read from
      c - length to read
      Returns:
      the read string array value
      Throws:
      IOException - if an I/O exception occurs

    • readLargeStringArray

      protected static String[] readLargeStringArray(DataInput in, int c) throws IOException
      Read array of string with length larger than threshold CHUNK_THRESHOLD >> 3.
      Parameters:
      in - a DataInput stream to read from
      c - length to read
      Returns:
      the read string array value
      Throws:
      IOException - if an I/O exception occurs

    • getClass

      public static Class getClass(String sClass)
      Return class for the specified class name; null if not found.
      Parameters:
      sClass - the class name
      Returns:
      the class for the specified class name