org.locomotive.util.cache
Class DBCache

java.lang.Object
  |
  +--org.locomotive.util.cache.DBCache

public class DBCache
extends java.lang.Object


Constructor Summary
DBCache()
          Default constructor for the database cache.
DBCache(Config config, DBConnectionPool connectionPool)
          Construct a database cache reading default values from a LocoConfig and with a specific connection pool.
DBCache(Config config, DBConnectionPool connectionPool, Log server_log)
          Construct a database cache reading default values from a Config and with a specific connection pool.
 
Method Summary
 void clearCacheForClass(java.lang.String short_class_name, boolean save_dirty_data)
          This method will remove all the items for this class from the cache.
 boolean contains(java.lang.String short_class_name, java.lang.Object key)
          Tells whether an Object is in the DBCache.
 boolean deleteSerializedObjectFromDB(java.lang.String short_class_name, java.lang.Object key)
          This method deletes an object from the database, but NOT from the cache.
 java.lang.Object get(java.lang.String short_class_name, int int_key)
          "convenience" get() method using an int key:
 java.lang.Object get(java.lang.String short_class_name, long long_key)
          "convenience" get() method using a long key:
 java.lang.Object get(java.lang.String short_class_name, java.lang.Object key)
          This method retrieves an object from the cache.
 int getAutoSaveSleepInterval()
           
 DBConnectionPool getConnectionPool()
          Get the connection pool for this cache.
 int getDefaultAutoSaveInterval()
           
 int getDefaultExpirationTime()
           
 int getExpirationSleepInterval()
           
 int getMaxEntries()
           
 int getMaxExpirationTime()
           
protected  java.lang.Object loadObject(org.locomotive.util.cache.MetaDataEntry class_data, java.lang.Object key)
           
protected  java.lang.Object loadSerializedObjectFromDB(org.locomotive.util.cache.MetaDataEntry class_data, java.lang.Object key)
           
 void log(int lev, java.lang.String s)
          log to the DBCache server log
static void main(java.lang.String[] argv)
           
 void put(java.lang.String short_class_name, java.lang.Object key, java.lang.Object new_object)
          This method puts an object in the cache.
 void register(java.lang.String short_class_name, java.lang.Class class_to_register)
          the default register method is:
 void register(java.lang.String short_class_name, java.lang.Class class_to_register, long expiration_frequency_in_seconds, long auto_save_frequency_in_seconds, boolean affects_other_sessions)
          The register() method allows you to register your Objects that you want to store in the database, with the DBCache.
 java.lang.Object remove(java.lang.String short_class_name, java.lang.Object key)
          This method removes an object from the cache.
 void saveRelationalObjectIfDirty(org.locomotive.util.cache.InstanceCacheEntry entry)
          This is just a convenience method for ExpirationThread and AutoSaveThread.
 void setAutoSaveSleepInterval(int autoSaveSleepInterval)
          how long the AutoSaveThread sleeps before waking up to check dirty data in objects, expressed in number of seconds
 void setConnectionPool(DBConnectionPool connectionPool)
          Set the connection pool this cache.
 void setDefaultAutoSaveInterval(int defaultAutoSaveInterval)
          how long the AutoSaveThread sleeps before waking up to check dirty data in objects, expressed in number of seconds
 void setDefaultExpirationTime(int defaultExpirationTime)
          the default frequency for how long an object can remain in the cache (used primarily by the ExpirationThread) expressed in number of seconds.
 void setExpirationSleepInterval(int expirationSleepInterval)
          how long the ExpirationThread sleeps before waking up to check whether objects have expired, expressed in number of seconds
 void setMaxEntries(int maxEntries)
           
 void setMaxExpirationTime(int maxExpirationTime)
          The maximum time that any object can remain in this cache, expressed in number of seconds.
 void startService()
          Startup the service.
 boolean writeSerializedObjectToDB(java.lang.String short_class_name, java.lang.Object key, java.lang.Object new_object)
           
 boolean writeToDB(java.lang.String short_class_name, java.lang.Object key, java.lang.Object new_object)
          This method will write an Object into the database, without saving it into the cache.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DBCache

public DBCache()
Default constructor for the database cache. The Connection pool and other parameters should be set using bean interface methods, and the startService() method should be used to start up the DBCache service.

DBCache

public DBCache(Config config,
               DBConnectionPool connectionPool,
               Log server_log)
Construct a database cache reading default values from a Config and with a specific connection pool.
Parameters:
config - The Config to get default values from.
connectionPool - The connection pool to use for this cache.

DBCache

public DBCache(Config config,
               DBConnectionPool connectionPool)
Construct a database cache reading default values from a LocoConfig and with a specific connection pool.
Parameters:
config - The LocoConfig to get default values from.
connectionPool - The connection pool to use for this cache.
Method Detail

startService

public void startService()
Startup the service. This should be called after the service has been configured properly.

setMaxEntries

public void setMaxEntries(int maxEntries)

getMaxEntries

public int getMaxEntries()

setDefaultExpirationTime

public void setDefaultExpirationTime(int defaultExpirationTime)
the default frequency for how long an object can remain in the cache (used primarily by the ExpirationThread) expressed in number of seconds.

getDefaultExpirationTime

public int getDefaultExpirationTime()

setMaxExpirationTime

public void setMaxExpirationTime(int maxExpirationTime)
The maximum time that any object can remain in this cache, expressed in number of seconds.

getMaxExpirationTime

public int getMaxExpirationTime()

setExpirationSleepInterval

public void setExpirationSleepInterval(int expirationSleepInterval)
how long the ExpirationThread sleeps before waking up to check whether objects have expired, expressed in number of seconds

getExpirationSleepInterval

public int getExpirationSleepInterval()

setDefaultAutoSaveInterval

public void setDefaultAutoSaveInterval(int defaultAutoSaveInterval)
how long the AutoSaveThread sleeps before waking up to check dirty data in objects, expressed in number of seconds

getDefaultAutoSaveInterval

public int getDefaultAutoSaveInterval()

setAutoSaveSleepInterval

public void setAutoSaveSleepInterval(int autoSaveSleepInterval)
how long the AutoSaveThread sleeps before waking up to check dirty data in objects, expressed in number of seconds

getAutoSaveSleepInterval

public int getAutoSaveSleepInterval()

setConnectionPool

public void setConnectionPool(DBConnectionPool connectionPool)
Set the connection pool this cache.
Parameters:
connectionPool - The connection pool to use for this cache.

getConnectionPool

public DBConnectionPool getConnectionPool()
Get the connection pool for this cache.
Returns:
Returns the connectionPool used by this cache;

register

public void register(java.lang.String short_class_name,
                     java.lang.Class class_to_register,
                     long expiration_frequency_in_seconds,
                     long auto_save_frequency_in_seconds,
                     boolean affects_other_sessions)
              throws CacheNamingException
The register() method allows you to register your Objects that you want to store in the database, with the DBCache. There are two benefits in registering:
Parameters:
short_class_name - should have only alphanumeric characters and '_'.
auto_save_frequency_in_seconds - how often the DBCache should check for dirty data for each RelationalObject, and write it to the database. Expressed as the number of seconds between each periodic check.
  • If this number is -1, then it means "never save to the database".
  • If this number is 0, then it means use DBCache's default auto-save frequency.
  • If this number is 1, then it means that the DBCache will check "as frequently as possible" -- that is, each time the DBCache wakes up, at the interval you specify.
  • If this number is > 3600, it will be treated as if it were 3600. In other words, we think that it makes sense to flush dirty information at least once per hour. if you want to flush dirty information at an interval longer than an hour, use -1 ("never save") and simply rely on your own scheduling algorithm.
expiration_in_seconds - how long, in seconds, an Object can remain in the cache, without being accessed by DBCache's get() or put() methods, before it is removed. We recommend that you make this number reasonably large, for example, at least 60 seconds, but more typically, 1800 (1/2 hour) or 3600 (1 hour). Otherwise, why bother using the DBCache at all?
  • If this number is -1, then it means "never expires".
  • If this number is 0, then it means use DBCache's default expiration period.
  • If this number is > 3600, it will be treated as if it were 3600. In other words, the DBCache only has room to store up to an hour's worth of data. Or, you can write your own expiration algorithm by combining -1 ("never expire") with the remove() method.
affects_other_sessions - if this is true, then it means that we will need to have a consistent view for this RelationalObject across multiple Locomotive servers. This is very complicated, and will be implemented later. for now, this argument is unused; it's just a placeholder.

register

public void register(java.lang.String short_class_name,
                     java.lang.Class class_to_register)
              throws CacheNamingException
the default register method is:

get

public java.lang.Object get(java.lang.String short_class_name,
                            java.lang.Object key)
                     throws java.sql.SQLException,
                            CacheNamingException
This method retrieves an object from the cache. This method will "refresh" this Object's expiration time; in other words, its expiration time in the cache will be pushed out.

loadObject

protected java.lang.Object loadObject(org.locomotive.util.cache.MetaDataEntry class_data,
                                      java.lang.Object key)
                               throws java.sql.SQLException

loadSerializedObjectFromDB

protected java.lang.Object loadSerializedObjectFromDB(org.locomotive.util.cache.MetaDataEntry class_data,
                                                      java.lang.Object key)
                                               throws java.sql.SQLException

get

public java.lang.Object get(java.lang.String short_class_name,
                            int int_key)
                     throws java.sql.SQLException,
                            CacheNamingException
"convenience" get() method using an int key:

get

public java.lang.Object get(java.lang.String short_class_name,
                            long long_key)
                     throws java.sql.SQLException,
                            CacheNamingException
"convenience" get() method using a long key:

put

public void put(java.lang.String short_class_name,
                java.lang.Object key,
                java.lang.Object new_object)
         throws java.sql.SQLException,
                CacheNamingException
This method puts an object in the cache. NOTE: if the item is dirty, this method will write it into the database immediately.

writeToDB

public boolean writeToDB(java.lang.String short_class_name,
                         java.lang.Object key,
                         java.lang.Object new_object)
                  throws java.sql.SQLException,
                         CacheNamingException
This method will write an Object into the database, without saving it into the cache. This method neither uses nor sets the dirty flag of a RelationalObject explicitly. NOTE: short_class_name must be registered with the DBCache.

writeSerializedObjectToDB

public boolean writeSerializedObjectToDB(java.lang.String short_class_name,
                                         java.lang.Object key,
                                         java.lang.Object new_object)
                                  throws java.sql.SQLException,
                                         CacheNamingException

remove

public java.lang.Object remove(java.lang.String short_class_name,
                               java.lang.Object key)
                        throws java.sql.SQLException,
                               CacheNamingException
This method removes an object from the cache. It does NOT delete the Object from the database. (To delete it from the database, call the deleteFromDB() method) NOTE: this Object will now no longer be auto-saved to the database, even if it has dirty data. That becomes your own responsibility.
See Also:
deleteFromDB()

deleteSerializedObjectFromDB

public boolean deleteSerializedObjectFromDB(java.lang.String short_class_name,
                                            java.lang.Object key)
                                     throws java.sql.SQLException,
                                            CacheNamingException
This method deletes an object from the database, but NOT from the cache. This method is in DBCache because DBCache seems like the only place with a general library for dealing with Object serialization I/O with the database. if you want to delete a RelationalObject instead of a serialized generic Object, then just call the delete() method for that RelationalObject.
Returns:
whether the Object was successfully deleted from the database.

contains

public boolean contains(java.lang.String short_class_name,
                        java.lang.Object key)
                 throws CacheNamingException
Tells whether an Object is in the DBCache. This method DOES NOT "refresh" this Object; in other words, its expiration time in the cache IS NOT updated.

clearCacheForClass

public void clearCacheForClass(java.lang.String short_class_name,
                               boolean save_dirty_data)
                        throws CacheNamingException
This method will remove all the items for this class from the cache.
Parameters:
save_dirty_data - if this is true, then each item will be auto-saved to the database if it has dirty data.

saveRelationalObjectIfDirty

public void saveRelationalObjectIfDirty(org.locomotive.util.cache.InstanceCacheEntry entry)
                                 throws java.sql.SQLException
This is just a convenience method for ExpirationThread and AutoSaveThread.

main

public static void main(java.lang.String[] argv)

log

public void log(int lev,
                java.lang.String s)
log to the DBCache server log
Parameters:
lev - the log level
s - a string to be logged