objectdb.java

来自「SRI international 发布的OAA框架软件」· Java 代码 · 共 117 行

/* $Id: ObjectDB.java,v 1.2 2003/06/25 20:32:30 giuli Exp $*/
/**************************************************************************
 * Copyright 2001, 2002 SRI International. All rights reserved.
 *
 * The material contained in this file is confidential and proprietary to SRI
 * International and may not be reproduced, published, or disclosed to others
 * without authorization from SRI International.
 *
 * DISCLAIMER OF WARRANTIES
 *
 * SRI International MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
 * SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT
 * LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SRI International SHALL NOT BE
 * LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING
 * OR DISTRIBUTING THIS SOFTWARE
 **************************************************************************/
package com.sri.sedc.javanetbridge;

import java.util.List;


/**
 * ObjectDB is used to store references to objects.
 *
 * <h3>Usage</h3>
 * <p>
 * To store an object reference and retrieve an intger for that reference,
 * use the method {@link #addObjRef}. To retrieve an object reference, use
 * the method {@link #getObjFromId}. To delete a reference by reference number
 * or by providing the object itself, use {@link #releaseObjRef(int)} and
 * {@link #releaseObjRef(java.lang.Object)}.
 * </p>
 * <p>
 * Note that a reference count is maintained for each object. Each time that
 * <code>AddObjRef</code> is called for the same object, the reference count
 * for that object is incremented. Each time <code>removeObjRef</code> is
 * called for the same object, the reference count for that object is
 * decremented. When the reference count reaches 0, the object is removed from
 * the database. The purpose of this referencing system is to ensure that
 * the object will not be garbage collected until all references for the object
 * have been released.
 * </p>
 */
public interface ObjectDB {
    /**
     * Adds an object reference. This method will check if the input object is
     * already in the database. If the object is not in the database, an entry
     * will be made for it and a number associated with the object. If
     * the object is already in the database, its reference count will be
     * incremented before this method returns. Note that if the object is
     * not in the database, it is assigned a reference count of 1. This
     * method returns an id number for the object that can be used in any
     * of the other methods.
     *
     * @param obj the object to add a reference for
     * @return the id number for the object
     */
    int addObjRef(Object obj);

    /**
     * Clears the object database, removing all entries.
     */
    void clear();

    /**
     * Retrieves all objects in the database.
     *
     * @return a copy of the objects list
     */
    List getObjects();

    /**
     * Reeleases an object reference. The reference count for the object is
     * decremented by 1, and if the reference count reaches 0 the object is
     * removed from the database.
     *
     * @param obj the object to release a reference for
     * @return -1 if the object was not in the database, or the new reference
     *  count for the object. If the return value is 0, the object has been
     *  removed from the database.
     * @see #releaseObjRef(int)
     */
    int releaseObjRef(Object obj);

    /**
     * Reeleases an object reference. The reference count for the object is
     * decremented by 1, and if the reference count reaches 0 the object is
     * removed from the database.
     *
     * @param id the id number of the object to release a reference for
     * @return -1 if the object was not in the database, or the new reference
     *  count for the object. If the return value is 0, the object has been
     *  removed from the database.
     * @see #releaseObjRef(java.lang.Object)
     */
    int releaseObjRef(int id);

    /**
     * Retrieves an object by id.
     *
     * @param id the id of the object
     * @return the object for the given id
     * @throws com.sri.sedc.javanetbridge.ObjectNotFoundException if the input id does not exist in this database
     */
    Object getObjFromId(int id) throws ObjectNotFoundException;

    /**
     * Retrieves an id for an object in the database.
     *
     * @param obj the object
     * @return the id for the given object
     * @throws com.sri.sedc.javanetbridge.ObjectNotFoundException if the input object does not exist in this database
     */
    int getIdFromObj(Object obj) throws ObjectNotFoundException;
}