/*
 * Copyright (c) 1998 The Regenstrief Institute.  All rights reserved.
 *
 * 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.
 *
 * Written by Gunther Schadow.
 *
 * $Id: Database.java,v 1.2 1999/05/14 17:37:33 schadow Exp $
 */
package jdbm;

import java.lang.*;
import java.io.*;

/**
 * This is the Java adapter for GDBM database files.  It basically
 * mirrors GDBM's functionality. To learn more about GDBM see
 * gdbm(3).
 *
 * @author Gunther Schadow
 * @version $Revision: 1.2 $ $Date: 1999/05/14 17:37:33 $
 */
public class Database
  implements Serializable
{
  /** Opens database file as a reader */
  public static final int O_READER = 0;
  /** Opens database file as a writer */
  public static final int O_WRITER = 1;
  /** Opens database file as a writer and creates a new database file
   *  if it does not already exist. 
   */
  public static final int O_CREATE = 2;
  /** Opens database file as a writer and creates a new database file
   *  regardless whether or not it already exists.
   */
  public static final int O_NEWDB  = 3;
  /** Opens database file in fast update mode. */
  public static final int O_FAST   = 16;

  /** Raises KeyExistsException if a data is attempted to be stored by
   * a key that already exists.
   */
  public static final int S_INSERT  = 0;
  /** Overwrites the data of a key if the key exists. */
  public static final int S_REPLACE = 1;

  /** Opens a database file in the specified <CODE>O_</CODE> mode.
   *  @param file the database file.
   *  @param mode the <CODE>O_</CODE> mode.
   *  @exception IOException if a problem with the file occurs
   */
  public Database(File file, int mode) 
       throws IOException
  { 
    dbfile = file;
    omode  = mode;
    init(dbfile.getCanonicalPath(), omode);
  }
  
  /** Reads a serialized Database object and opens the GDBM database file
   *  that the Database object used before.
   *  @param in an input stream fed by a data field
   *  @exception IOException if a problem with the file occurs
   *  @exception ClassNotFoundException java internal exception,
   *                                            unlikely to occur
   */
  private void readObject(java.io.ObjectInputStream in)
       throws IOException, ClassNotFoundException
  { 
    in.defaultReadObject();
    init(dbfile.getCanonicalPath(), omode);
  }
  
  /** Opens a database file in the specified <CODE>O_</CODE> mode.
   *  @param filename the database file name.
   *  @param mode the <CODE>O_</CODE> mode.
   *  @exception IOException if a problem with the file occurs
   */
  public Database(String filename, int mode)
       throws IOException
  {
    this(new File(filename), mode);
  }

  /** Closes a data base */
  public synchronized native void close();

  /** Checks whether the given key exists in the data base 
   * @param key the bytes of the key.
   * @return true if key exists, false otherwise.
   */
  public synchronized native boolean exists(byte key[]);

  /** Checks whether the given key exists in the data base
   * @param key the bytes of the key.
   * @return true if key exists, false otherwise.
   */
  public boolean exists(String key) { return exists(key.getBytes()); }
    
  /** Fetch the data if the given key exists in the data base 
   * @param key the bytes of the key. 
   * @return the data bytes stored for the key.
   * @exception NoSuchKeyException if key was not in data base.
   */
  public synchronized native byte[] fetch(byte key[])
       throws NoSuchKeyException;

  /** Fetch the data if the given key exists in the data base 
   * @param key the bytes of the key. 
   * @return the data bytes stored for the key.
   * @exception NoSuchKeyException if key was not in data base.
   */
  public String fetch(String key)
       throws NoSuchKeyException
  {
    return new String(fetch(key.getBytes()));
  }

  /** Fetch the data if the given key exists in the data base 
   * @param key the bytes of the key. 
   * @return the data bytes stored for the key.
   * @exception NoSuchKeyException if key was not in data base.
   */
  public byte[] fetchBytes(String key)
       throws NoSuchKeyException
  {
    return fetch(key.getBytes());
  }

  /** Fetch the data if the given key exists in the data base 
   * @param key the bytes of the key. 
   * @return the data bytes stored for the key.
   * @exception NoSuchKeyException if key was not in data base.
   */
  public String fetchString(byte key[])
       throws NoSuchKeyException
  {
    return new String(fetch(key));
  }
       
  /** Store the data for the given key in the specified
   *  <CODE>S_</CODE> mode. 
   * @param key the bytes of the key. 
   * @param data the bytes of the key. 
   * @param mode the <CODE>S_</CODE> mode. 
   * @return the data bytes stored for the key.
   * @exception KeyExistsException if key is already in data base and 
   *       an <CODE>S_INSERT</CODE> store has been attempted.
   * @exception IllegalOperationError if database is in read mode.
   */
  public synchronized native void store(byte key[], byte data[], int mode)
       throws KeyExistsException, IllegalOperationError;

  /** Store the data for the given key in the specified
   *  <CODE>S_</CODE> mode. 
   * @param key the bytes of the key. 
   * @param data the bytes of the key. 
   * @param mode the <CODE>S_</CODE> mode. 
   * @return the data bytes stored for the key.
   * @exception KeyExistsException if key is already in data base and 
   *       an <CODE>S_INSERT</CODE> store has been attempted.
   * @exception IllegalOperationError if database is in read mode.
   */
  public void store(String key, byte data[], int mode)
       throws KeyExistsException, IllegalOperationError
  {
    store(key.getBytes(), data, mode);
  }

  /** Store the data for the given key in the specified
   *  <CODE>S_</CODE> mode. 
   * @param key the bytes of the key. 
   * @param data the bytes of the key. 
   * @param mode the <CODE>S_</CODE> mode. 
   * @return the data bytes stored for the key.
   * @exception KeyExistsException if key is already in data base and 
   *       an <CODE>S_INSERT</CODE> store has been attempted.
   * @exception IllegalOperationError if database is in read mode.
   */
  public void store(String key, String data, int mode)
       throws KeyExistsException, IllegalOperationError
  {
    store(key.getBytes(), data.getBytes(), mode);
  }

  /** Deletes a key data pair from the database. No exception is raised if
   * key does not exist. The purpose is that after calling this method the
   * key will not exist, regardless of whether or not it existed before.
   * @param key the bytes of the key. 
   * @exception IllegalOperationError if database is in read mode.
   */
  public synchronized native void delete(byte key[])
       throws IllegalOperationError;

  /** For iteration: get first key in database.  
   *  @return the bytes of the first key or <CODE>null</CODE> if
   *          database is empty.
   */ 
  public synchronized native byte[] firstkey();

  /** For iteration: get next key in database following the given key.
   *  @return the bytes of the next key or <CODE>null</CODE> if
   *          database is exhausted. 
   */
  public synchronized native byte[] nextkey(byte key[]);

  /** Frees space in the data base after data has been deleted.
   * @exception IllegalOperationError if database is in read mode.
   */
  public synchronized native void reorganize()
       throws IllegalOperationError;
       
  /** Synchronizes the data base on disk with recent updates in memory
   *  if database is in fast update mode. Otherwise <CODE>sync</CODE> does
   *  nothing.
   */
  public synchronized native void sync();

  /** Enables the fast mode for updates. */
  public synchronized native void enableFastUpdateMode();

  /** Disables the fast mode for updates. */
  public synchronized native void disableFastUpdateMode();

  /** Sets the bucket cache size. This may only be done once.
   * @param cachesize the cache size (default is 100).
   * @exception IllegalOperationError if cache size is set a second time.
   */
  public synchronized native void setCacheSize(int cachesize);
       
  /** PRIVATE STUFF ****************************************** */
  
  private File dbfile   = null;       
  private int  omode    = O_READER;       
  private int  handle   = 0;
  private native void init(String filename, int omode);

  public void finalize()
  {
    if(handle != 0)
      close();
  }

  /** Loads the shared library on initialization of this class. */
  static {
    System.loadLibrary("jdbm");
  }

  /* test function 
  public static void main(String args[])
       throws IOException, NoSuchKeyException, KeyExistsException   
  {
    Database db = new Database("testdsd.db", O_CREATE);
    db.setCacheSize(100);
    System.out.println(db.exists("akey"));
    db.store("akey", "somedata", Database.S_REPLACE);
    db.store("bkey", "somedata", Database.S_REPLACE);
    db.store("ckey", "somedata", Database.S_REPLACE);
    System.out.println(db.exists("akey"));
    for(byte[] key = db.firstkey(); key != null; key = db.nextkey(key))
      {
	System.out.print(new String(key));
	System.out.println(" -> " + db.fetchString(key));
      }
      
    db.close();
  }
  */
}