gate
Class Factory

java.lang.Object
  gate.Factory

public abstract class Factory
extends Object

Provides static methods for the creation of Resources.

Nested Class Summary

static class

Factory.DuplicationContext Opaque memo object passed to CustomDuplication.duplicate methods to encapsulate the state of the current duplication run.

Constructor Summary

Factory()

Method Summary

static void	addCreoleListener(CreoleListener l) Add a listener
protected static void	checkDuplicationContext(Factory.DuplicationContext ctx) Throws an exception if the specified duplication context is null or not active.
static DataStore	createDataStore(String dataStoreClassName, String storageUrl) Create a new DataStore and open it.
static AnnotationSet	createImmutableAnnotationSet(Document document, Collection<Annotation> annotations) Utility method to create an immutable annotation set.
static Resource	createResource(String resourceClassName) Create an instance of a resource using default parameter values.
static Resource	createResource(String resourceClassName, FeatureMap parameterValues) Create an instance of a resource, and return it.
static Resource	createResource(String resourceClassName, FeatureMap parameterValues, FeatureMap features) Create an instance of a resource, and return it.
static Resource	createResource(String resourceClassName, FeatureMap parameterValues, FeatureMap features, String resourceName) Create an instance of a resource, and return it.
static Resource	defaultDuplicate(Resource res, Factory.DuplicationContext ctx) Implementation of the default duplication algorithm described in the comment for duplicate(Resource).
static void	deleteResource(Resource resource) Delete an instance of a resource.
static FeatureMap	duplicate(FeatureMap fm, Factory.DuplicationContext ctx) Construct a feature map that is a copy of the one provided except that any Resource values in the map are replaced by their duplicates.
static Resource	duplicate(Resource res) Create a duplicate of the given resource.
static Resource	duplicate(Resource res, Factory.DuplicationContext ctx) Create a duplicate of the given resource, using the provided context.
static ConstraintFactory	getConstraintFactory() Return the active ConstraintFactory for creating and initializing Jape Constraints.
static Class<ParseCpsl>	getJapeParserClass()
protected static DataStore	instantiateDataStore(String dataStoreClassName, String storageUrl) Instantiate a DataStore (not open or created).
static Corpus	newCorpus(String name) Create a new transient Corpus.
static Document	newDocument(String content) Create a new transient textual Document from a string.
static Document	newDocument(URL sourceUrl) Create a new transient Document from a URL.
static Document	newDocument(URL sourceUrl, String encoding) Create a new transient Document from a URL and an encoding.
static FeatureMap	newFeatureMap() Create a new FeatureMap.
static ParseCpsl	newJapeParser(Reader stream, Map existingMacros)
static ParseCpsl	newJapeParser(URL japeURL, String encoding)
static DataStore	openDataStore(String dataStoreClassName, String storageUrl) Open an existing DataStore.
static void	setJapeParserClass(Class newClass)

Methods inherited from class java.lang.Object

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

Constructor Detail

Factory

public Factory()

Method Detail

createResource

public static Resource createResource(String resourceClassName)
                               throws ResourceInstantiationException

Create an instance of a resource using default parameter values.

Throws:

ResourceInstantiationException

See Also:

createResource(String,FeatureMap)

createResource

public static Resource createResource(String resourceClassName,
                                      FeatureMap parameterValues)
                               throws ResourceInstantiationException

Create an instance of a resource, and return it. Callers of this method are responsible for querying the resource's parameter lists, putting together a set that is complete apart from runtime parameters, and passing a feature map containing these parameter settings.

Parameters:

resourceClassName - the name of the class implementing the resource.

parameterValues - the feature map containing intialisation time parameterValues for the resource.

Returns:

an instantiated resource.

Throws:

ResourceInstantiationException

createResource

public static Resource createResource(String resourceClassName,
                                      FeatureMap parameterValues,
                                      FeatureMap features)
                               throws ResourceInstantiationException

Create an instance of a resource, and return it. Callers of this method are responsible for querying the resource's parameter lists, putting together a set that is complete apart from runtime parameters, and passing a feature map containing these parameter settings.

Parameters:

resourceClassName - the name of the class implementing the resource.

parameterValues - the feature map containing intialisation time parameterValues for the resource.

features - the features for the new resource

Returns:

an instantiated resource.

Throws:

ResourceInstantiationException

createResource

public static Resource createResource(String resourceClassName,
                                      FeatureMap parameterValues,
                                      FeatureMap features,
                                      String resourceName)
                               throws ResourceInstantiationException

Create an instance of a resource, and return it. Callers of this method are responsible for querying the resource's parameter lists, putting together a set that is complete apart from runtime parameters, and passing a feature map containing these parameter settings. In the case of ProcessingResources they will have their runtime parameters initialised to their default values.

Parameters:

resourceClassName - the name of the class implementing the resource.

parameterValues - the feature map containing intialisation time parameterValues for the resource.

features - the features for the new resource or null to not assign any (new) features.

resourceName - the name to be given to the resource or null to assign a default name.

Returns:

an instantiated resource.

Throws:

ResourceInstantiationException

deleteResource

public static void deleteResource(Resource resource)

Delete an instance of a resource. This involves removing it from the stack of instantiations maintained by this resource type's resource data. Deletion does not guarantee that the resource will become a candidate for garbage collection, just that the GATE framework is no longer holding references to the resource.

Parameters:

resource - the resource to be deleted.

newCorpus

public static Corpus newCorpus(String name)
                        throws ResourceInstantiationException

Create a new transient Corpus.

Throws:

ResourceInstantiationException

newDocument

public static Document newDocument(URL sourceUrl)
                            throws ResourceInstantiationException

Create a new transient Document from a URL.

Throws:

ResourceInstantiationException

newDocument

public static Document newDocument(URL sourceUrl,
                                   String encoding)
                            throws ResourceInstantiationException

Create a new transient Document from a URL and an encoding.

Throws:

ResourceInstantiationException

newDocument

public static Document newDocument(String content)
                            throws ResourceInstantiationException

Create a new transient textual Document from a string.

Throws:

ResourceInstantiationException

createImmutableAnnotationSet

public static AnnotationSet createImmutableAnnotationSet(Document document,
                                                         Collection<Annotation> annotations)

Utility method to create an immutable annotation set. If the provided collection of annotations is null, the newly created set will be empty.

Parameters:

document - the document this set belongs to.

annotations - the set of annotations that should be contained in the returned AnnotationSet.

Returns:

an AnnotationSet that throws exceptions on all attempts to modify it.

duplicate

public static Resource duplicate(Resource res)
                          throws ResourceInstantiationException

Create a duplicate of the given resource. A duplicate is a an independent copy of the resource that has the same name and the same behaviour. It does not necessarily have the same concrete class as the original, but if the original resource implements any of the following interfaces then the duplicate can be assumed to implement the same ones:

• ProcessingResource
• LanguageAnalyser
• Controller
• CorpusController
• ConditionalController
• Gazetteer
• LanguageResource
• Ontology
• Document
• Corpus

The default duplication algorithm simply calls createResource with the type and name of the original resource, and with parameters and features which are copies of those from the original resource, but any Resource values in the maps will themselves be duplicated. A context is passed around all the duplicate calls that stem from the same call to this method so that if the same resource is referred to in different places, the same duplicate can be used in the corresponding places in the duplicated object graph.

This default behaviour is sufficient for most resource types (and is roughly the equivalent of saving the resource's state using the persistence manager and then reloading it), but individual resource classes can override it by implementing the CustomDuplication interface. This may be necessary for semantic reasons (e.g. controllers need to recursively duplicate the PRs they contain), or desirable for performance or memory consumption reasons (e.g. the behaviour of a DefaultGazetteer can be duplicated by a SharedDefaultGazetteer that shares the internal data structures).

Parameters:

res - the resource to duplicate

Returns:

an independent duplicate copy of the resource

Throws:

ResourceInstantiationException - if an exception occurs while constructing the duplicate.

duplicate

public static Resource duplicate(Resource res,
                                 Factory.DuplicationContext ctx)
                          throws ResourceInstantiationException

Create a duplicate of the given resource, using the provided context. This method is intended for use by resources that implement the CustomDuplication interface when they need to duplicate their child resources. Calls made to this method outside the scope of such a CustomDuplication.duplicate call will fail with a runtime exception.

Parameters:

res - the resource to duplicate

ctx - the current context as passed to the CustomDuplication.duplicate(gate.Factory.DuplicationContext) method.

Returns:

the duplicated resource

Throws:

ResourceInstantiationException - if an error occurs while constructing the duplicate.

See Also:

duplicate(Resource)

defaultDuplicate

public static Resource defaultDuplicate(Resource res,
                                        Factory.DuplicationContext ctx)
                                 throws ResourceInstantiationException

Implementation of the default duplication algorithm described in the comment for duplicate(Resource). This method is public for the benefit of resources that implement CustomDuplication but only need to do some post-processing after the default duplication algorithm; they can call this method to obtain an initial duplicate and then post-process it before returning. If they need to duplicate child resources they should call duplicate(Resource, DuplicationContext) in the normal way. Calls to this method made outside the context of a CustomDuplication.duplicate call will fail with a runtime exception.

Parameters:

res - the resource to duplicate

ctx - the current context

Returns:

a duplicate of the given resource, constructed using the default algorithm. In particular, if res implements CustomDuplication its own duplicate method will not be called.

Throws:

ResourceInstantiationException - if an error occurs while duplicating the given resource.

duplicate

public static FeatureMap duplicate(FeatureMap fm,
                                   Factory.DuplicationContext ctx)
                            throws ResourceInstantiationException

Construct a feature map that is a copy of the one provided except that any Resource values in the map are replaced by their duplicates. This method is public for the benefit of resources that implement CustomDuplication and will fail if called outside of a CustomDuplication.duplicate implementation.

Parameters:

fm - the feature map to duplicate

ctx - the current context

Returns:

a duplicate feature map

Throws:

ResourceInstantiationException - if an error occurs while duplicating any Resource in the feature map.

checkDuplicationContext

protected static void checkDuplicationContext(Factory.DuplicationContext ctx)

Throws an exception if the specified duplication context is null or not active. This is to ensure that the Factory helper methods that take a DuplicationContext parameter can only be called in the context of a duplicate(Resource) call.

Parameters:

ctx - the context to check.

Throws:

NullPointerException - if the provided context is null.

IllegalStateException - if the provided context is not active.

getJapeParserClass

public static Class<ParseCpsl> getJapeParserClass()

setJapeParserClass

public static void setJapeParserClass(Class newClass)

newJapeParser

public static ParseCpsl newJapeParser(Reader stream,
                                      Map existingMacros)

newJapeParser

public static ParseCpsl newJapeParser(URL japeURL,
                                      String encoding)
                               throws IOException

Throws:

IOException

getConstraintFactory

public static ConstraintFactory getConstraintFactory()

Return the active ConstraintFactory for creating and initializing Jape Constraints.

newFeatureMap

public static FeatureMap newFeatureMap()

Create a new FeatureMap.

openDataStore

public static DataStore openDataStore(String dataStoreClassName,
                                      String storageUrl)
                               throws PersistenceException

Open an existing DataStore.

Throws:

PersistenceException

createDataStore

public static DataStore createDataStore(String dataStoreClassName,
                                        String storageUrl)
                                 throws PersistenceException,
                                        UnsupportedOperationException

Create a new DataStore and open it. NOTE: for some data stores creation is an system administrator task; in such cases this method will throw an UnsupportedOperationException.

Throws:

PersistenceException

UnsupportedOperationException

instantiateDataStore

protected static DataStore instantiateDataStore(String dataStoreClassName,
                                                String storageUrl)
                                         throws PersistenceException

Instantiate a DataStore (not open or created).

Throws:

PersistenceException

addCreoleListener

public static void addCreoleListener(CreoleListener l)

Add a listener