com.larvalabs.megamap
Class MegaMapManager

java.lang.Object
  com.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