ClassCatalog (Oracle - Berkeley DB Java API)
Date: 2020-06-01

Package com.sleepycat.bind.serial

## Interface ClassCatalog

- All Known Implementing Classes:
    `StoredClassCatalog`

      public interface ClassCatalog

  A catalog of class description information for use during object serialization.

  A catalog is used to store class descriptions separately from serialized objects, to avoid redundantly stored information with each object. When serialized objects are stored in a database, a `StoredClassCatalog` should be used.

  This information is used for serialization of class descriptors or java.io.ObjectStreamClass objects, each of which represents a unique class format. For each unique format, a unique class ID is assigned by the catalog. The class ID can then be used in the serialization stream in place of the full class information. When used with `SerialInput` and `SerialOutput` or any of the serial bindings, the use of the catalog is transparent to the application.

  See Also:
    Class Evolution

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Close a catalog database and release any cached resources.
    `java.io.ObjectStreamClass` | `getClassFormat​(byte[] classID)` | Return the ObjectStreamClass for the given class ID.
    `byte[]` | `getClassID​(java.io.ObjectStreamClass classDesc)` | Return the class ID for the current version of the given class description.
    `java.lang.ClassLoader` | `getClassLoader()` | Returns the ClassLoader to be used by bindings that use this catalog, or null if a default class loader should be used.

- - ### Method Detail

    - #### close

          void close()
              throws DatabaseException

      Close a catalog database and release any cached resources.
      Throws:
        `DatabaseException` - if an error occurs closing the catalog database.

    - #### getClassID

          byte[] getClassID​(java.io.ObjectStreamClass classDesc)
                     throws DatabaseException,
                            java.lang.ClassNotFoundException

      Return the class ID for the current version of the given class description. This is used for storing in serialization streams in place of a full class descriptor, since it is much more compact. To get back the ObjectStreamClass for a class ID, call `getClassFormat(byte[])`. This function causes a new class ID to be assigned if the class description has changed.
      Parameters:
        `classDesc` - The class description for which to return the class ID.
      Returns:
        The class ID for the current version of the class.
      Throws:
        `DatabaseException` - if an error occurs accessing the catalog database.
        `java.lang.ClassNotFoundException` - if the class does not exist.

    - #### getClassFormat

          java.io.ObjectStreamClass getClassFormat​(byte[] classID)
                                            throws DatabaseException,
                                                   java.lang.ClassNotFoundException

      Return the ObjectStreamClass for the given class ID. This may or may not be the current class format, depending on whether the class has changed since the class ID was generated.
      Parameters:
        `classID` - The class ID for which to return the class format.
      Returns:
        The class format for the given class ID, which may or may not represent the current version of the class.
      Throws:
        `DatabaseException` - if an error occurs accessing the catalog database.
        `java.lang.ClassNotFoundException` - if the class does not exist.

    - #### getClassLoader

          java.lang.ClassLoader getClassLoader()

      Returns the ClassLoader to be used by bindings that use this catalog, or null if a default class loader should be used. The ClassLoader is used by `SerialBinding` to load classes whose description is stored in the catalog.

      In BDB JE, the implementation of this method in `StoredClassCatalog` returns the ClassLoader property of the catalog database Environment. This ensures that the Environment's ClassLoader property is used for loading all user-supplied classes.

      Returns:
        the ClassLoader or null.

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