1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2000,2008 Oracle.  All rights reserved.
5 *
6 * $Id: ClassCatalog.java,v 12.6 2008/01/08 20:58:35 bostic Exp $
7 */
8
9package com.sleepycat.bind.serial;
10
11import java.io.ObjectStreamClass;
12
13import com.sleepycat.db.DatabaseException;
14
15/**
16 * A catalog of class description information for use during object
17 * serialization.
18 *
19 * <p>A catalog is used to store class descriptions separately from serialized
20 * objects, to avoid redundantly stored information with each object.
21 * When serialized objects are stored in a database, a {@link
22 * StoredClassCatalog} should be used.</p>
23 *
24 * <p>This information is used for serialization of class descriptors or
25 * java.io.ObjectStreamClass objects, each of which represents a unique class
26 * format.  For each unique format, a unique class ID is assigned by the
27 * catalog.  The class ID can then be used in the serialization stream in place
28 * of the full class information.  When used with {@link SerialInput} and
29 * {@link SerialOutput} or any of the serial bindings, the use of the catalog
30 * is transparent to the application.</p>
31 *
32 * @author Mark Hayes
33 */
34public interface ClassCatalog {
35
36    /**
37     * Close a catalog database and release any cached resources.
38     */
39    public void close()
40        throws DatabaseException;
41
42    /**
43     * Return the class ID for the current version of the given class
44     * description.
45     * This is used for storing in serialization streams in place of a full
46     * class descriptor, since it is much more compact.  To get back the
47     * ObjectStreamClass for a class ID, call {@link #getClassFormat(byte[])}.
48     * This function causes a new class ID to be assigned if the class
49     * description has changed.
50     *
51     * @param classDesc The class description for which to return the
52     * class ID.
53     *
54     * @return The class ID for the current version of the class.
55     */
56    public byte[] getClassID(ObjectStreamClass classDesc)
57        throws DatabaseException, ClassNotFoundException;
58
59    /**
60     * Return the ObjectStreamClass for the given class ID.  This may or may
61     * not be the current class format, depending on whether the class has
62     * changed since the class ID was generated.
63     *
64     * @param classID The class ID for which to return the class format.
65     *
66     * @return The class format for the given class ID, which may or may not
67     * represent the current version of the class.
68     */
69    public ObjectStreamClass getClassFormat(byte[] classID)
70        throws DatabaseException, ClassNotFoundException;
71}
72