com.sleepycat.bind.serial

## Class SerialBinding<E>

- java.lang.Object
- - com.sleepycat.bind.serial.SerialBase
  - - com.sleepycat.bind.serial.SerialBinding<E>

- All Implemented Interfaces:
    EntryBinding<E>

      public class SerialBinding<E>
      extends SerialBase
      implements EntryBinding<E>

  A concrete `EntryBinding` that treats a key or data entry as a serialized object.

  This binding stores objects in serialized object format. The deserialized objects are returned by the binding, and their `Class` must implement the `Serializable` interface.

  For key bindings, a tuple binding is usually a better choice than a serial binding. A tuple binding gives a reasonable sort order, and works with comparators in all cases -- see below.

  WARNING: SerialBinding should not be used with Berkeley DB Java Edition for key bindings, when a custom comparator is used. In JE, comparators are instantiated and called internally at times when databases are not accessible. Because serial bindings depend on the class catalog database, a serial binding cannot be used during these times. An attempt to use a serial binding with a custom comparator will result in a NullPointerException during environment open or close.

  Class Evolution

  `SerialBinding` and other classes in this package use standard Java serialization and all rules of Java serialization apply. This includes the rules for class evolution. Once an instance of a class is stored, the class must maintain its `serialVersionUID` and follow the rules defined in the Java specification. To use a new incompatible version of a class, a different `ClassCatalog` must be used or the class catalog database must be truncated.

  If more advanced class evolution features are required, consider using the `Direct Persistence Layer`.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SerialBinding(ClassCatalog classCatalog, java.lang.Class<E> baseClass)` Creates a serial binding.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `E` | `entryToObject(DatabaseEntry entry)` Deserialize an object from an entry buffer.
    `java.lang.Class<E>` | `getBaseClass()` Returns the base class for this binding.
    `java.lang.ClassLoader` | `getClassLoader()` Returns the class loader to be used during deserialization, or null if a default class loader should be used.
    `void` | `objectToEntry(E object, DatabaseEntry entry)` Serialize an object into an entry buffer.

    - ### Methods inherited from class com.sleepycat.bind.serial.SerialBase

      `getSerialBufferSize, getSerialOutput, setSerialBufferSize`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SerialBinding

          public SerialBinding(ClassCatalog classCatalog,
                               java.lang.Class<E> baseClass)

      Creates a serial binding.
      Parameters:
        `classCatalog` - is the catalog to hold shared class information and for a database should be a `StoredClassCatalog`.
        `baseClass` - is the base class for serialized objects stored using this binding -- all objects using this binding must be an instance of this class. Note that if this parameter is non-null, then this binding will not support serialization of null values.

  - ### Method Detail

    - #### getBaseClass

          public final java.lang.Class<E> getBaseClass()

      Returns the base class for this binding.
      Returns:
        the base class for this binding.

    - #### getClassLoader

          public java.lang.ClassLoader getClassLoader()

      Returns the class loader to be used during deserialization, or null if a default class loader should be used. The default implementation of this method returns `ClassCatalog.getClassLoader()`, if it returns a non-null value. If `ClassCatalog.getClassLoader()` returns null, then `Thread.currentThread().getContextClassLoader()` is returned.

      This method may be overridden to return a dynamically determined class loader. For example, `getBaseClass().getClassLoader()` could be called to use the class loader for the base class, assuming that a base class has been specified.

      If this method returns null, a default class loader will be used as determined by the `java.io.ObjectInputStream.resolveClass` method.

      Returns:
        the ClassLoader or null.

    - #### entryToObject

          public E entryToObject(DatabaseEntry entry)

      Deserialize an object from an entry buffer. May only be called for data that was serialized using `objectToEntry(E, com.sleepycat.db.DatabaseEntry)`, since the fixed serialization header is assumed to not be included in the input data. `SerialInput` is used to deserialize the object.
      Specified by:
        `entryToObject` in interface `EntryBinding<E>`
      Parameters:
        `entry` - is the input serialized entry.
      Returns:
        the output deserialized object.

    - #### objectToEntry

          public void objectToEntry(E object,
                                    DatabaseEntry entry)

      Serialize an object into an entry buffer. The fixed serialization header is not included in the output data to save space, and therefore to deserialize the data the complementary `entryToObject(com.sleepycat.db.DatabaseEntry)` method must be used. `SerialOutput` is used to serialize the object.

      Note that this method sets the DatabaseEntry offset property to a non-zero value and the size property to a value less than the length of the byte array.

      Specified by:
        `objectToEntry` in interface `EntryBinding<E>`
      Parameters:
        `object` - is the input deserialized object.
        `entry` - is the output serialized entry.
      Throws:
        `java.lang.IllegalArgumentException` - if the object is not an instance of the base class for this binding, including if the object is null and a non-null base class was specified.

Copyright (c) 1996, 2017 Oracle and/or its affiliates. All rights reserved.