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

Nested Classes

Modifier and Type	Class and Description
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.RRPersistence
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.

Constructor Summary

Constructors

Constructor and Description
PersistenceManager()

Method Summary

Modifier and Type	Method and Description
static File	currentPersistenceFile() Get the file currently being saved by this thread.
static List<File>	currentPersistenceFileStack()
static ResourceReference	currentPersistenceURL() Get the URL currently being loaded by this thread.
static List<ResourceReference>	currentPersistenceURLStack()
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)
static Object	getTransientRepresentation(Object target, String containingControllerName, Map<String,Map<String,Object>> initParamOverrides)
static boolean	isContainedWithin(File file, File directory) This method can be used to determine if a specified file (or directory) is contained within a given directory.
static Object	loadObjectFromFile(File file)
static Object	loadObjectFromUri(URI uri)
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 void	saveObjectToFile(Object obj, File file) Save the given object to the file, without using $gatehome$.
static void	saveObjectToFile(Object obj, File file, boolean usegatehome, boolean warnaboutgatehome) Save the given object to the given file.

Methods inherited from class java.lang.Object

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

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

getTransientRepresentation

public static Object getTransientRepresentation(Object target,
                                                String containingControllerName,
                                                Map<String,Map<String,Object>> initParamOverrides)
                                         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.

isContainedWithin

public static boolean isContainedWithin(File file,
                                        File directory)

This method can be used to determine if a specified file (or directory) is contained within a given directory. This will check if the real location of file (with all symbolic links removed) is within the real location of directory with all symbolic links removed. If part of the file path is within the directory but eventually a symbolic link leads out of that directory, the file is considered to NOT be inside the directory.

NOTE: this accesses the file system to find the real locations for file and directory. However, if there is a problem accessing the file system, the method will fall back to using the literal path names for checking and NOT produce an error. This is done so that any saving operation during which this method is invoked is not aborted and proceeds, creating a file that may be correct apart from one or more serialized URLs.

Parameters:

file - is this file contained within

directory - this directory

Returns:

true if the file is contained within the directory, false otherwise

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

Save the given object to the file, without using $gatehome$. This is equivalent to saveObjectToFile(Object,File,boolean,boolean) with the third and fourth parameter set to false. This method exists with this definition to stay backwards compatible with code that was using this method before paths relative to $gatehome$ were supported.

Parameters:

obj - The object to persist

file - The file where to persists to

Throws:

PersistenceException

IOException

saveObjectToFile

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

Save the given object to the given file.

Parameters:

obj - The object to persist.

file - The file where to persist to

usegatehome - if true (recommended) use $gatehome$ and $resourceshome$ instead of $relpath$ in any saved path URLs if the location of that URL is inside GATE home or inside the resources home directory (if set).

warnaboutgatehome - if true, issue a warning message when a saved URL uses $gatehome$ or $resourceshome$.

Throws:

PersistenceException

IOException

currentPersistenceFile

public static File currentPersistenceFile()

Get the file currently being saved by this thread.

currentPersistenceFileStack

public static List<File> currentPersistenceFileStack()

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

loadObjectFromUri

public static Object loadObjectFromUri(URI uri)
                                throws PersistenceException,
                                       IOException,
                                       ResourceInstantiationException,
                                       URISyntaxException

Throws:

PersistenceException

IOException

ResourceInstantiationException

URISyntaxException

currentPersistenceURL

public static ResourceReference currentPersistenceURL()

Get the URL currently being loaded by this thread.

currentPersistenceURLStack

public static List<ResourceReference> currentPersistenceURLStack()

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