source: gs2-extensions/tdb/trunk/src/java/org/greenstone/tdbjava/TDBJava.java@ 30193

/*
 * Copyright (C) 2015 Greenstone Digital Libraries, University of Waikato
 * $Id$
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

package org.greenstone.tdbjava;

import java.io.Closeable;
import java.lang.System;
import java.util.Enumeration;

import org.greenstone.tdbjava.TDBJavaException;
import org.greenstone.tdbjava.TDBJavaKeyEnumeration;

/** Java interface to a TDB database table.
 *
 * <P>This database is a simple on-disk hash table.
 *
 * <P>Both the hash keys and values are binary strings of any length.  They
 * are converted to and from Java objects using customizable packing
 * strategies.
 *
 * <P>The implementation of this class consists of two levels: a Java-level
 * interface, and a set of private native functions implemented in C.  As much
 * functionality as possible is implemented in Java: the C functions generally
 * just marshal the information for presentation to the native GDBM library.
 *
 * <P>The native library <CODE>tdbjava</CODE> must be available for dynamic
 * loading in a system-dependant manner.
 *
 * <p>See the <A HREF="https://tdb.samba.org">TDB home page</A> for more
 * information.
 *
 * @author John Thompson ([email protected])
 * @author Martin Pool (original author - GdbmJava)
 */
public class TDBJava
    implements Closeable
{
    static
    {
    // Load native library mapping at runtime (libTDBJava.so)
    System.loadLibrary("TDBJava");
    }

    /* ===== Declare mappings to native methods ===== */

    /**
     * @brief Determine the version number of the TDB library.
     */
    private static native String tdbGetVersion();

    /**
     * @brief Determine the version number of the JNI TDB warapper.
     */
    private static native String tdbWrapperVersion();

    /**
     * @brief Open the database and creating it if necessary.
     */
    private native long tdbOpen(String filename,
                int tdb_flags,
                int open_flags)
    throws TDBJavaException;

    /**
     * @brief Close a database.
     */
    private native void tdbClose(long dbf);

    /**
     * @brief Store an element in the database.
     */
    private native void tdbStore(long dbf,
                 byte[] key,
                 byte[] content,
                 boolean replace);

    /**
     * @brief Fetch an entry in the database given a key.
     */
    private native byte[] tdbFetch(long dbf,
                   byte[] key);

    /**
     * @brief Check if an entry in the database exists.
     */
    private native boolean tdbExists(long dbf,
                     byte[] key);

    /**
     * @brief Delete an entry in the database given a key.
     */
    private native void tdbDelete(long dbf,
                  byte[] key);

    /**
     * @brief Find the first entry in the database and return its key.
     */
    private native byte[] tdbFirstKey(long dbf)
    throws TDBJavaException;

    /**
     * @brief Find the next entry in the database, returning its key.
     */
    private native byte[] tdbNextKey(long dbf,
                     byte[] key)
    throws TDBJavaException;

    /* =====  Normal variable and function declarations ===== */
    /* (should match GdbmFile) */

    /* TDB flags */
    /** When set, default behaviour (included for readability) */
    public final static int TDB_DEFAULT = 0;
    /** When set, causes any existing TDB table to be cleared on first open */
    public final static int TDB_CLEAR_IF_FIRST = 1;
    /** When set, causes TDB table to be in-memory (no file access) */
    public final static int TDB_INTERNAL = 2;
    /** When set, suppresses file locking (flock) */
    public final static int TDB_NOLOCK = 4;

    /** Open database possibilities **/
    public final static int O_DEFAULT  = 0;
    public final static int O_READONLY = 1;

    /** The parameters used to open the database. */
    private String filename;
    private int    tdb_flags;
    private int    open_flags;

    /** The TDB handle for the database file, or 0 if the database has
     * been closed.  Java doesn't understand it, but it stores it and
     * passes it to the C routines. */
    private transient volatile long dbf;

    /** Create a new TDBJava object which automatically wraps a connection to
     * an underlying TDB database (using the TDB library via the JNI wrapper).
     *
     * @param filename the disk filename in which the data will be stored
     * @param flags any of TDB_DEFAULT, TDB_CLEAR_IF_FIRST, TDB_INTERNAL, and
     * TDB_NOLOCK
     *
     */
    public TDBJava(String filename)
    throws TDBJavaException
    {
    this(filename, TDBJava.TDB_DEFAULT, TDBJava.O_DEFAULT);
    }

    public TDBJava(String filename, int tdb_flags)
    throws TDBJavaException
    {
    this(filename, tdb_flags, TDBJava.O_DEFAULT);
    }

    public TDBJava(String filename, int tdb_flags, int open_flags)
    throws TDBJavaException
    {
    this.filename = filename;
    this.tdb_flags = tdb_flags;
    this.open_flags = open_flags;
    this.dbf = this.tdbOpen(this.filename, this.tdb_flags, this.open_flags);
    // Replacement for System.runFinalizersOnExit(true);
    Thread shutdown_thread = new TDBJavaShutdownThread(this);
    Runtime.getRuntime().addShutdownHook(shutdown_thread);
    }

    /** Close the database file if it is still open.
     */
    public synchronized void close()
    throws TDBJavaException
    {
    if (this.dbf != 0) {
        this.tdbClose(this.dbf);
    }
    // opened or created
    this.dbf = 0;
    }

    /** Close the database when the TDBJava is garbage-collected.
     */
    public void finalize()
    throws TDBJavaException
    {
    this.close();
    }

    /** Returns a string indicating the version of the underlying TDB
     * library.
     *
     * @return the version of the native TDB library.
     *
     **/
    public static String getLibraryVersion()
    {
    return TDBJava.tdbGetVersion();
    }

    /** Return a string indicating the version of the JNI TDB library
     * wrapper.
     *
     * @return the release number of the wrapper
     *
     **/
    public static String getWrapperVersion()
    {
    return TDBJava.tdbWrapperVersion();
    }

    /** Indicate whether the database is writable.
     *
     * @return true if the database may be written; otherwise false.
     *
     */
    public boolean isWritable()
    {
    return (TDBJava.O_READONLY != this.open_flags);
    }

    /** Indicate whether the database is open or not.
     *
     * @return false if the database has been closed; otherwise true.
     *
     */
    public boolean isOpen()
    {
    return (this.dbf != 0);
    }

    /** Compact the database file - not necessary for TDB.
     */
    public void reorganize()
    throws TDBJavaException
    {
    // Not applicable
    }

    /** Was used to define key Packing mechanism - no longer used as TDB always
     * uses String to byte array.
     */
    public void setKeyPacking(Object packing)
    {
    // Not applicable
    }

    /** Was used to define value Packing mechanism - no longer used as TDB
     * always uses byte array to String
     */
    public void setValuePacking(Object packing)
    {
    // Not applicable
    }

    /** Flush changes to disk - not necessary for TDB.
     */
    public void sync()
     throws TDBJavaException
    {
    // Not applicable
    }

    /** Retrieve the value corresponding to a particular key.
     *
     * @param key the string identifying the record to be retrieved
     *
     * @return the value of the record with the specified key; or
     * null if the key is not present in the database.
     */
    public String fetch(String key)
    throws TDBJavaException
    {
    if (!this.isOpen()) {
        throw new TDBJavaException("Database is not open: " + this.filename);
    }
    byte[] key_bytes = this.toBytes(key);
    byte[] value_bytes = this.tdbFetch(this.dbf, key_bytes);
    if (null == value_bytes) {
        throw new TDBJavaException("Key not found: \"" + key + "\"");
    }
    String value = this.fromBytes(value_bytes);
    return value;
    }

    /** Indicate whether the specified key is in the database,
     * without returning the value.
     *
     * @param key the key of the record to be retrieved
     *
     * @return true if a record with the specified key is present;
     * otherwise false.
     */
    public boolean exists(String key)
    throws TDBJavaException
    {
    if (!this.isOpen()) {
        throw new TDBJavaException("Database is not open: " + this.filename);
    }
    byte[] key_bytes = this.toBytes(key);
    return this.tdbExists(this.dbf, key_bytes);
    }

    /** Store a value in the database, replacing any existing value with the
     * same key.
     *
     * @param key key under which to store the value
     *
     * @param value value to be stored
     *
     * @exception TDBJavaException if an IO error occurs
     */
    public void store(String key, String value)
    throws TDBJavaException
    {
    if (!this.isOpen()) {
        throw new TDBJavaException("Database is not open: " + this.filename);
    }
    if (!this.isWritable()) {
        throw new TDBJavaException("Database is read only: " + this.filename);
    }
    byte[] key_bytes = this.toBytes(key);
    byte[] value_bytes = this.toBytes(value);
    this.tdbStore(this.dbf, key_bytes, value_bytes, true);
    }

    /** Remove a record from the database.
     *
     * @param key key of the record to be removed
     *
     * @exception TDBJavaException if there is no record with the specified key; or
     * if an IO error occurs.
     */
    public void delete(String key)
    throws TDBJavaException
    {
    if (!this.isOpen()) {
        throw new TDBJavaException("Database is not open: " + this.filename);
    }
    if (!this.isWritable()) {
        throw new TDBJavaException("Database is read only: " + this.filename);
    }
    byte[] key_bytes = this.toBytes(key);
    this.tdbDelete(this.dbf, key_bytes);
    }

    /** Return an enumeration which will return all of the keys for the
     * database of the file in (apparently) random order.
     *
     * <P><B>Caution:</B> If the database is modified while
     * an enumeration is in progress,
     * then changes in the hash table may cause the enumeration to
     * miss some records.
     */
    public Enumeration keys()
    throws TDBJavaException
    {
    if (!this.isOpen()) {
        throw new TDBJavaException("Database is not open: " + this.filename);
    }
    // Return an inner class which will do the iteration in the
    // context of this GdbmFile object.
    Enumeration keys = new TDBJavaKeyEnumeration(this);
    return keys;
    }

    /** Start a visit to all keys in the hashtable.
     *
     * @return the first key in the hash table as a String; or null if
     * the database is empty. */
    String getFirstKey()
    throws TDBJavaException
    {
    if (!this.isOpen()) {
        throw new TDBJavaException("Database is not open: " + this.filename);
    }
    byte[] first_key_bytes = this.tdbFirstKey(this.dbf);
    String first_key = null;
    if (null != first_key_bytes) {
        first_key = this.fromBytes(first_key_bytes);
    }
    return first_key;
    }
    /** getFirstKey() **/


    /** Find and read the next key in the hashtable.
     *
     * @return the next key; or null if given the last key in the hashtable.
     */
    String getNextKey(String current_key)
    throws TDBJavaException
    {
    if (!this.isOpen()) {
        throw new TDBJavaException("Database is not open: " + this.filename);
    }
    byte[] current_key_bytes = this.toBytes(current_key);
    byte[] next_key_bytes = this.tdbNextKey(this.dbf, current_key_bytes);
    String next_key = null;
    if (null != next_key_bytes) {
        next_key = this.fromBytes(next_key_bytes);
    }
    return next_key;
    }
    /** getNextKey(String) **/


    /* ===== Private and Protected Functions ===== */

    /** Convert String to byte array - simplified replacement for Packing
     * mechanism in GDBMJava.
     */
    protected byte[] toBytes(String input_string)
    {
    byte[] output_bytes;
    try {
        output_bytes = input_string.getBytes("UTF-8");
    }
    catch (Exception e) {
        System.err.println("TDBJava::toBytes() - UTF-8 encoding not supported");
        output_bytes = input_string.getBytes();
    }
    return output_bytes;
    }

    /** Convert bytes array to String - simplified replacement for Packing
     * mechanism in GDBMJava.
     */
    protected String fromBytes(byte[] input_bytes)
    {
    String output_string;
    try {
        output_string = new String(input_bytes, "UTF-8");
    }
    catch (Exception e) {
        System.err.println("TDBJava::fromBytes() - UTF-8 encoding not supported");
        output_string = new String(input_bytes);
    }
    return output_string;
    }
}