com.larvalabs.megamap
Class MegaMapManager

java.lang.Object
  extended bycom.larvalabs.megamap.MegaMapManager

public class MegaMapManager
extends java.lang.Object

This the user's entry point to creating and managing MegaMaps.

Author:
John Watkinson
See Also:
createMegaMap(String, boolean, boolean), createMegaMap(String, String, boolean, boolean), shutdown()

Method Summary
 MegaMap createMegaMap(java.lang.String name, boolean persistent, boolean overwriteOld)
          Creates a new MegaMap (or loads a persisted MegaMap from disk).
 MegaMap createMegaMap(java.lang.String name, java.lang.String path, boolean persistent, boolean overwriteOld)
          Creates a new MegaMap (or loads a persisted MegaMap from disk) using the specified path for writing the MegaMap files.
 void deletePersistedMegaMap(java.lang.String name)
          Deletes a previously persisted MegaMap.
 void deletePersistedMegaMap(java.lang.String name, java.lang.String path)
          Deletes a previously persisted MegaMap.
protected  void finalize()
           
 MegaMap getMegaMap(java.lang.String name)
          Retrieves a previously-created MegaMap.
static MegaMapManager getMegaMapManager()
          Gets the (singleton) instance of the MegaMapManager.
 void removeMegaMap(java.lang.String name)
          Removes a MegaMap from the manager.
 void setDiskStorePath(java.lang.String diskStorePath)
          Sets the default path to which to store MegaMap files.
 void shutdown()
          Shuts down the MegaMapManager and all MegaMaps.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getMegaMapManager

public static MegaMapManager getMegaMapManager()
                                        throws MegaMapException
Gets the (singleton) instance of the MegaMapManager.

Throws:
MegaMapException - if unable to create the instance.

setDiskStorePath

public void setDiskStorePath(java.lang.String diskStorePath)
Sets the default path to which to store MegaMap files. If this method is not called, or if it is called with a null parameter then this will default to the default system temp directory (specified by the system property java.io.tmpdir.


createMegaMap

public MegaMap createMegaMap(java.lang.String name,
                             boolean persistent,
                             boolean overwriteOld)
                      throws MegaMapException
Creates a new MegaMap (or loads a persisted MegaMap from disk).

Parameters:
name - the name of the MegaMap. Must consist of letters, numbers and the underscore character only (A-Z, a-z, 1-9, _).
persistent - if true, then will persist the cache to disk between VM invocations. Note: It is very improtant that the shutdown() method is called upon shutdown of the application if any MegaMaps are created with persistent set to true. Otherwise, the integrity of the persisted data cannot be ensured.
Returns:
the created MegaMap.
Throws:
MegaMapException - if a MegaMap by the name given already exists, if the name given is invalid, or if the MegaMap is unable to write to the disk.

createMegaMap

public MegaMap createMegaMap(java.lang.String name,
                             java.lang.String path,
                             boolean persistent,
                             boolean overwriteOld)
                      throws MegaMapException
Creates a new MegaMap (or loads a persisted MegaMap from disk) using the specified path for writing the MegaMap files.

Parameters:
name - the name of the MegaMap. Must consist of letters, numbers and the underscore character only (A-Z, a-z, 1-9, _).
path - the directory in which to write the MegaMap files.
persistent - if true, then will persist the cache to disk between VM invocations. Note: It is very improtant that the shutdown() method is called upon shutdown of the application if any MegaMaps are created with persistent set to true. Otherwise, the integrity of the persisted data cannot be ensured.
Returns:
the created MegaMap.
Throws:
MegaMapException - if a MegaMap by the name given already exists, if the name given is invalid, or if the MegaMap is unable to write to the disk.

getMegaMap

public MegaMap getMegaMap(java.lang.String name)
Retrieves a previously-created MegaMap.

Parameters:
name - the name of the MegaMap.

removeMegaMap

public void removeMegaMap(java.lang.String name)
Removes a MegaMap from the manager. This causes the map to be flushed to disk (if persistent) and its supporting thread to be shut down. Note: This does not result in the deletion of a persistent cache. See deletePersistedMegaMap(String) and deletePersistedMegaMap(String, String) for that functionality.

Parameters:
name - the name of the cache to remove from management.

deletePersistedMegaMap

public void deletePersistedMegaMap(java.lang.String name)
                            throws MegaMapException
Deletes a previously persisted MegaMap. The MegaMap must not be active or an exception will be thrown.

Parameters:
name - the name of the MegaMap to delete (the current disk store path will be used).
Throws:
MegaMapException - if the named MegaMap is currently active.
See Also:
deletePersistedMegaMap(java.lang.String, java.lang.String)

deletePersistedMegaMap

public void deletePersistedMegaMap(java.lang.String name,
                                   java.lang.String path)
                            throws MegaMapException
Deletes a previously persisted MegaMap. The MegaMap must not be active or an exception will be thrown.

Parameters:
name - the name of the MegaMap to delete.
path - the path to the MegaMap files.
Throws:
MegaMapException - if the named MegaMap is currently active.
See Also:
deletePersistedMegaMap(java.lang.String)

shutdown

public void shutdown()
Shuts down the MegaMapManager and all MegaMaps. Persistent MegaMaps will all be saved to disk. There should be no more use of MegaMaps after this method is called. This method should be explicitly called upon shutdown of any application that makes use of persistent MegaMaps. It is not as important for non-persistent MegaMaps, but failing to call this will leave temporary files in the filesystem that otherwise would be deleted. The finalizer for MegaMapManager calls this method, so the call java.lang.System.runFinalizersOnExit(true) will ensure that is called. However, this method is deprecated with no replacement in recent versions of the JDK, so use the system call at your own risk.


finalize

protected void finalize()
                 throws java.lang.Throwable
Throws:
java.lang.Throwable