/* ----------------------------------------------------------------------------
   The Kiwi Toolkit - A Java Class Library
   Copyright (C) 1998-2004 Mark A. Lindner

   This library 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 library 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 library; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
   02111-1307, USA.
 
   The author may be contacted at: mark_a_lindner@yahoo.com
   ----------------------------------------------------------------------------
   $Log: PersistentObjectPool.java,v $
   Revision 1.6  2004/05/05 21:37:04  markl
   comment block updates

   Revision 1.5  2003/01/19 09:35:41  markl
   Javadoc & comment header updates.

   Revision 1.4  2001/03/12 05:58:46  markl
   Javadoc cleanup.

   Revision 1.3  2001/03/12 01:17:30  markl
   Source code cleanup.

   Revision 1.2  1999/08/03 04:49:57  markl
   Removed debug statements.

   Revision 1.1  1999/02/28 01:21:43  markl
   Initial revision
   ----------------------------------------------------------------------------
*/

package kiwi.db;

import java.sql.*;
import java.lang.reflect.*;
import java.util.*;

import kiwi.util.*;

/** This class is a fairly simple implementation of a caching mechanism for
  * <code>PersistentObject</code>s. An application generally uses some sort of
  * persistent store to save its data; this caching mechanism is meant to be
  * used with those applications that use a relational database (RDMBS) as
  * the perssitent store.
  * <p>
  * A problem domain object as represented by a Java class may have its state
  * persisted in one or more rows in one or more tables in the database. The
  * operations of writing an object's state to the RDBMS or reading it back
  * from the RDBMS may be costly, and therefore it should only be done when
  * absolutely necessary.
  * <p>
  * If a Java class needs access to a persistent object and that object is
  * already in memory, perhaps as the result of a restore operation by an
  * unrelated (and hence inaccessible) class, the class would be forced to load
  * the object again, creating a second instance of it in memory. This can be
  * very wasteful if it happens frequently. To alleviate this problem, a cache
  * such as <code>PersistentObjectPool</code> maintains references to all
  * <code>PersistentObject</code>s that are currently in memory. Whenever an
  * object is retrieved from the pool, it is <i>timestamped</i>. A
  * <code>PersistentObject</code> has a <i>ttl</i> (time to live) that
  * specifies how long it can remain in memory before it is discarded. If the
  * object ages past its <i>ttl</i> without being retrieved from the pool, it
  * is removed from the pool. A subsequent retrieval of the object from the
  * pool will cause it to be reloaded from the persistent store.
  * <p>
  * Even though an object has expired from the pool, other classes may still
  * have references to it. Those classes may continue to access (and modify)
  * the object, even though the object is not in memory as far as the pool is
  * concerned. In general this should not be a problem, but it will be possible
  * to alleviate it in Java 1.2 through the use of soft references.
  * <p>
  * If a <code>PersistentObject</code> is written to the persistent store while
  * it is still in the pool, retrievals of that object from the pool will
  * return the old copy of the object unless the old copy expires. To prevent
  * this problem, the object should be explicitly expired when it is stored.
  * See the documentation for <code>PersistentObject</code> for more
  * information.
  *
  * @see kiwi.db.PersistentObject
  *
  * @author Mark Lindner
  */

public class PersistentObjectPool
  {
  private Hashtable pool;
  private Object argList[] = new Object[1];
  private Class emptyTypeList[] = new Class[0];
  private Object emptyArgList[] = new Object[0];
  private Class idTypeList[] = { int.class };
  private static PersistentObjectPool instance = new PersistentObjectPool();
  private Thread gc;

  /* Private constructor. */
  
  private PersistentObjectPool()
    {
    pool = new Hashtable();

    gc = new GarbageCollector();
    gc.start();
    }

  /** Get a reference to the <code>PersistentObjectPool</code> singleton.
    */
  
  public static PersistentObjectPool getInstance()
    {
    return(instance);
    }

  /** Retrieve an object from the pool. If the object is not already in the
    * pool, it is retrieved from the persistent store.
    *
    * @param id The ID of the object.
    * @param type The type of the object.
    * @exception SQLException if the operation failed.
    * @return The object on success, or <code>null</code> if the object could
    * not be found.
    */
  
  public PersistentObject getObject(int id, Class type) throws SQLException
    {
    PersistentObject o = null;
    Integer key = new Integer(id);

    synchronized(pool)
      {
      o = (PersistentObject)pool.get(key);
      if(o == null)
        {
        o = loadObject(id, type);
        if(o != null)
          pool.put(key, o);
        }
      }

    if(o != null)
      o.timestamp();
    
    return(o);
    }

  /** Load a persistent object from the persistent store. Reflection is used to
   * locate the <code>restore()</code> method of the specified class. An
   * instance of the class is then created with the specified ID as an
   * argument, and then the object is restored via a call to the
   * <code>restore()</code> method.
   *
   * @param id The ID of the object to load.
   * @param type The type of the object that is being loaded.
   * @exception java.sql.SQLException If the operation failed.
   * @return The loaded object.
   */
  
  protected PersistentObject loadObject(int id, Class type) throws SQLException
    {
    PersistentObject p;
    Constructor idConstructor = null;
    Method loadMethod = null;

    try
      {
      idConstructor = type.getConstructor(idTypeList);
      loadMethod = type.getMethod("restore", emptyTypeList);
      }
    catch(Exception ex)
      {
      ex.printStackTrace();
      }
    
    try
      {
      argList[0] = new Integer(id);
      p = (PersistentObject)idConstructor.newInstance(argList);
      loadMethod.invoke(p, emptyArgList);
      }
    catch(InvocationTargetException ex)
      {
      Throwable te = ex.getTargetException();
      if(te instanceof SQLException)
        throw((SQLException)te);
      else
        {
        te.printStackTrace();
        p = null;
        }
      }
    catch(Exception ex)
      {
      ex.printStackTrace();
      p = null;
      }

    return(p);
    }

  /** Remove all objects from the pool that have expired by the specified time.
    * This method can be called directly, but it is called periodically by the
    * internal pool garbage collection thread.
    *
    * @param now The current time.
    */

  public void expireObjects(long now)
    {
    synchronized(pool)
      {
      Enumeration e = pool.keys();
      while(e.hasMoreElements())
        {
        Integer key = (Integer)e.nextElement();
        
        PersistentObject o = (PersistentObject)pool.get(key);
        if(o.isExpired(now))
          {
          pool.remove(key);
          // System.out.println("Dumping " + o + " from pool.");
          }
        }
      }
    }

  /* Garbage collector for expiring objects. */

  private class GarbageCollector extends Thread
    {
    public void run()
      {
      for(;;)
        {
        // sleep
        KiwiUtils.sleep(120);
        
        // work
        // System.out.println("Expiring objects...");
        expireObjects(System.currentTimeMillis());
        }
      }
    }
  
  }

/* end of source file */