gate.util.persistence
Class PersistenceManager

java.lang.Object
  gate.util.persistence.PersistenceManager

public class PersistenceManager
extends Object

This class provides utility methods for saving resources through serialisation via static methods. It now supports both native and xml serialization.

Nested Class Summary

private static class	PersistenceManager.BooleanFlag
static class	PersistenceManager.ClassComparator
static class	PersistenceManager.NotComparableException Thrown by a comparator when the values provided for comparison are not comparable.
protected static class	PersistenceManager.ObjectHolder A reference to an object; it uses the identity hashcode and the equals defined by object identity.
static class	PersistenceManager.SlashDevSlashNull This class is used as a marker for types that should NOT be serialised when saving the state of a gate object.
static class	PersistenceManager.URLHolder URLs get upset when serialised and deserialised so we need to convert them to strings for storage.

Field Summary

private static PersistenceManager.ClassComparator	classComparator
private static boolean	DEBUG
private static ThreadLocal<LinkedList<Map>>	existingPersistentReplacements Stores the persistent replacements created during a transaction in order to avoid creating two different persistent copies for the same object.
private static ThreadLocal<LinkedList<Map>>	existingTransientValues Stores the transient values obtained from persistent replacements during a transaction in order to avoid creating two different transient copies for the same persistent replacement.
private static ThreadLocal<LinkedList<PersistenceManager.BooleanFlag>>	haveWarnedAboutGateHome
(package private) static ThreadLocal<LinkedList<File>>	persistenceFile The file currently used to write the persisten representation.
(package private) static ThreadLocal<LinkedList<URL>>	persistenceURL The URL currently used to read the persistent representation when reading from a URL.
private static Map	persistentReplacementTypes A dictionary mapping from java type (Class) to the type (Class) that can be used to store persistent data for the input type.
private static String[]	STARTOFXMLAPPLICATIONFILES
private static ThreadLocal<LinkedList<Boolean>>	useGateHome
private static ThreadLocal<LinkedList<Boolean>>	warnAboutGateHome

Constructor Summary

PersistenceManager()

Method Summary

private static void	clearCurrentTransients() Clear the current list of transient replacements without popping them off the stack.
private static PersistenceManager.BooleanFlag	currentHaveWarnedAboutGateHome()
private static File	currentPersistenceFile() Get the file currently being saved by this thread.
private static URL	currentPersistenceURL() Get the URL currently being loaded by this thread.
private static Boolean	currentUseGateHome()
private static Boolean	currentWarnAboutGateHome()
private static void	finishedLoading() Clean up the thread-local state at the end of a loading run.
private static void	finishedPersisting() Clean up the thread-local state for the current persistence run.
protected static Class	getMostSpecificPersistentType(Class type) Finds the most specific persistent replacement type for a given class.
static Serializable	getPersistentRepresentation(Object target) Recursively traverses the provided object and replaces it and all its contents with the appropriate persistent equivalent classes.
static String	getRelativePath(URL context, URL target) Calculates the relative path for a file: URL starting from a given context which is also a file: URL.
static Object	getTransientRepresentation(Object target)
private static boolean	isXmlApplicationFile(URL url) Determine whether the URL contains a GATE application serialized using XML.
static Object	loadObjectFromFile(File file)
static Object	loadObjectFromUrl(URL url)
static Class	registerPersistentEquivalent(Class transientType, Class persistentType) Sets the persistent equivalent type to be used to (re)store a given type of transient objects.
static Class	registerPersitentEquivalent(Class transientType, Class persistentType) Deprecated. Use registerPersistentEquivalent(Class,Class) instead
static void	saveObjectToFile(Object obj, File file)
static void	saveObjectToFile(Object obj, File file, boolean usegatehome, boolean warnaboutgatehome)
private static void	startLoadingFrom(URL url) Set up the thread-local state for the current loading run.
private static void	startPersistingTo(File file) Set up the thread-local state for a new persistence run.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEBUG

private static final boolean DEBUG

See Also:

Constant Field Values

STARTOFXMLAPPLICATIONFILES

private static final String[] STARTOFXMLAPPLICATIONFILES

persistentReplacementTypes

private static Map persistentReplacementTypes

A dictionary mapping from java type (Class) to the type (Class) that can be used to store persistent data for the input type.

existingPersistentReplacements

private static ThreadLocal<LinkedList<Map>> existingPersistentReplacements

Stores the persistent replacements created during a transaction in order to avoid creating two different persistent copies for the same object. The keys used are PersistenceManager.ObjectHolders that contain the transient values being converted to persistent equivalents.

existingTransientValues

private static ThreadLocal<LinkedList<Map>> existingTransientValues

Stores the transient values obtained from persistent replacements during a transaction in order to avoid creating two different transient copies for the same persistent replacement. The keys used are PersistenceManager.ObjectHolders that hold persistent equivalents. The values are the transient values created by the persisten equivalents.

classComparator

private static PersistenceManager.ClassComparator classComparator

persistenceFile

static ThreadLocal<LinkedList<File>> persistenceFile

The file currently used to write the persisten representation. Will only have a non-null value during storing operations.

persistenceURL

static ThreadLocal<LinkedList<URL>> persistenceURL

The URL currently used to read the persistent representation when reading from a URL. Will only be non-null during restoring operations.

useGateHome

private static ThreadLocal<LinkedList<Boolean>> useGateHome

warnAboutGateHome

private static ThreadLocal<LinkedList<Boolean>> warnAboutGateHome

haveWarnedAboutGateHome

private static ThreadLocal<LinkedList<PersistenceManager.BooleanFlag>> haveWarnedAboutGateHome

Constructor Detail

PersistenceManager

public PersistenceManager()

Method Detail

getPersistentRepresentation

public static Serializable getPersistentRepresentation(Object target)
                                                throws PersistenceException

Recursively traverses the provided object and replaces it and all its contents with the appropriate persistent equivalent classes.

Parameters:

target - the object to be analysed and translated into a persistent equivalent.

Returns:

the persistent equivalent value for the provided target

Throws:

PersistenceException

getTransientRepresentation

public static Object getTransientRepresentation(Object target)
                                         throws PersistenceException,
                                                ResourceInstantiationException

Throws:

PersistenceException

ResourceInstantiationException

getMostSpecificPersistentType

protected static Class getMostSpecificPersistentType(Class type)

Finds the most specific persistent replacement type for a given class. Look for a type that has a registered persistent equivalent starting from the provided class continuing with its superclass and implemented interfaces and their superclasses and implemented interfaces and so on until a type is found. Classes are considered to be more specific than interfaces and in situations of ambiguity the most specific types are considered to be the ones that don't belong to either java or GATE followed by the ones that belong to GATE and followed by the ones that belong to java. E.g. if there are registered persistent types for Resource and for LanguageResource than such a request for a Document will yield the registered type for LanguageResource.

getRelativePath

public static String getRelativePath(URL context,
                                     URL target)

Calculates the relative path for a file: URL starting from a given context which is also a file: URL.

Parameters:

context - the URL to be used as context.

target - the URL for which the relative path is computed.

Returns:

a String value representing the relative path. Constructing a URL from the context URL and the relative path should result in the target URL.

saveObjectToFile

public static void saveObjectToFile(Object obj,
                                    File file)
                             throws PersistenceException,
                                    IOException

Throws:

PersistenceException

IOException

saveObjectToFile

public static void saveObjectToFile(Object obj,
                                    File file,
                                    boolean usegatehome,
                                    boolean warnaboutgatehome)
                             throws PersistenceException,
                                    IOException

Throws:

PersistenceException

IOException

startPersistingTo

private static void startPersistingTo(File file)

Set up the thread-local state for a new persistence run.

currentPersistenceFile

private static File currentPersistenceFile()

Get the file currently being saved by this thread.

currentWarnAboutGateHome

private static Boolean currentWarnAboutGateHome()

currentUseGateHome

private static Boolean currentUseGateHome()

currentHaveWarnedAboutGateHome

private static PersistenceManager.BooleanFlag currentHaveWarnedAboutGateHome()

finishedPersisting

private static void finishedPersisting()

Clean up the thread-local state for the current persistence run.

loadObjectFromFile

public static Object loadObjectFromFile(File file)
                                 throws PersistenceException,
                                        IOException,
                                        ResourceInstantiationException

Throws:

PersistenceException

IOException

ResourceInstantiationException

loadObjectFromUrl

public static Object loadObjectFromUrl(URL url)
                                throws PersistenceException,
                                       IOException,
                                       ResourceInstantiationException

Throws:

PersistenceException

IOException

ResourceInstantiationException

startLoadingFrom

private static void startLoadingFrom(URL url)

Set up the thread-local state for the current loading run.

clearCurrentTransients

private static void clearCurrentTransients()

Clear the current list of transient replacements without popping them off the stack.

currentPersistenceURL

private static URL currentPersistenceURL()

Get the URL currently being loaded by this thread.

finishedLoading

private static void finishedLoading()

Clean up the thread-local state at the end of a loading run.

isXmlApplicationFile

private static boolean isXmlApplicationFile(URL url)
                                     throws IOException

Determine whether the URL contains a GATE application serialized using XML.

Parameters:

url - The URL to check.

Returns:

true if the URL refers to an xml serialized application, false otherwise.

Throws:

IOException

registerPersitentEquivalent

public static Class registerPersitentEquivalent(Class transientType,
                                                Class persistentType)
                                         throws PersistenceException

Deprecated. Use registerPersistentEquivalent(Class,Class) instead

Throws:

PersistenceException

registerPersistentEquivalent

public static Class registerPersistentEquivalent(Class transientType,
                                                 Class persistentType)
                                          throws PersistenceException

Sets the persistent equivalent type to be used to (re)store a given type of transient objects.

Parameters:

transientType - the type that will be replaced during serialisation operations

persistentType - the type used to replace objects of transient type when serialising; this type needs to extend Persistence.

Returns:

the persitent type that was used before this mapping if such existed.

Throws:

PersistenceException