Author: rec
Date: Fri May 10 11:31:15 2013
New Revision: 1480983
URL: http://svn.apache.org/r1480983
Log:
[UIMA-2892] Improve/clean up JavaDoc (and Exceptions)
- Improved AnalysisEngineFactory
- Added discussion on why descriptors are better than instances
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/AnalysisEngineFactory.java
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/ResourceCreationSpecifierFactory.java
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/package-info.java
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/AnalysisEngineFactory.java
URL:
http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/AnalysisEngineFactory.java?rev=1480983&r1=1480982&r2=1480983&view=diff
==============================================================================
---
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/AnalysisEngineFactory.java
(original)
+++
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/AnalysisEngineFactory.java
Fri May 10 11:31:15 2013
@@ -38,11 +38,11 @@ import java.util.Map;
import java.util.Map.Entry;
import org.apache.uima.Constants;
-import org.apache.uima.UIMAException;
import org.apache.uima.UIMAFramework;
import org.apache.uima.analysis_component.AnalysisComponent;
import org.apache.uima.analysis_engine.AnalysisEngine;
import org.apache.uima.analysis_engine.AnalysisEngineDescription;
+import org.apache.uima.analysis_engine.AnalysisEngineProcessException;
import org.apache.uima.analysis_engine.impl.AggregateAnalysisEngine_impl;
import org.apache.uima.analysis_engine.impl.AnalysisEngineDescription_impl;
import org.apache.uima.analysis_engine.metadata.AnalysisEngineMetaData;
@@ -53,6 +53,8 @@ import org.apache.uima.analysis_engine.m
import
org.apache.uima.analysis_engine.metadata.impl.FlowControllerDeclaration_impl;
import org.apache.uima.cas.CAS;
import org.apache.uima.fit.component.initialize.ExternalResourceInitializer;
+import org.apache.uima.fit.descriptor.SofaCapability;
+import org.apache.uima.fit.descriptor.TypeCapability;
import
org.apache.uima.fit.factory.ConfigurationParameterFactory.ConfigurationData;
import org.apache.uima.fit.internal.ReflectionUtil;
import org.apache.uima.flow.FlowControllerDescription;
@@ -69,14 +71,20 @@ import org.apache.uima.resource.metadata
import org.apache.uima.resource.metadata.TypeSystemDescription;
import org.apache.uima.resource.metadata.impl.Import_impl;
import org.apache.uima.util.FileUtils;
+import org.apache.uima.util.InvalidXMLException;
/**
+ * A collection of static methods for creating UIMA {@link
AnalysisEngineDescription
+ * AnalysisEngineDescriptions} and {@link AnalysisEngine AnalysisEngines}.
+ *
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
*/
public final class AnalysisEngineFactory {
private AnalysisEngineFactory() {
// This class is not meant to be instantiated
}
-
+
/**
* Get an AnalysisEngine from the name (Java-style, dotted) of an XML
descriptor file, and a set
* of configuration parameters.
@@ -86,10 +94,20 @@ public final class AnalysisEngineFactory
* @param configurationData
* Any additional configuration parameters to be set. These should
be supplied as (name,
* value) pairs, so there should always be an even number of
parameters.
- * @return The AnalysisEngine created from the XML descriptor and the
configuration parameters.
+ * @return the {@link AnalysisEngine} created from the XML descriptor and
the configuration
+ * parameters.
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
*/
public static AnalysisEngine createAnalysisEngine(String descriptorName,
- Object... configurationData) throws UIMAException, IOException {
+ Object... configurationData) throws InvalidXMLException, IOException,
+ ResourceInitializationException {
AnalysisEngineDescription aed =
createAnalysisEngineDescription(descriptorName,
configurationData);
return UIMAFramework.produceAnalysisEngine(aed);
@@ -99,12 +117,22 @@ public final class AnalysisEngineFactory
* Provides a way to create an AnalysisEngineDescription using a descriptor
file referenced by
* name
*
+ * @param descriptorName
+ * The fully qualified, Java-style, dotted name of the XML
descriptor file.
* @param configurationData
* should consist of name value pairs. Will override configuration
parameter settings in
* the descriptor file
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return a description for this analysis engine.
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
*/
public static AnalysisEngineDescription
createAnalysisEngineDescription(String descriptorName,
- Object... configurationData) throws UIMAException, IOException {
+ Object... configurationData) throws InvalidXMLException, IOException
{
Import_impl imprt = new Import_impl();
imprt.setName(descriptorName);
URL url = imprt.findAbsoluteUrl(UIMAFramework.newDefaultResourceManager());
@@ -117,10 +145,17 @@ public final class AnalysisEngineFactory
* This method provides a convenient way to instantiate an AnalysisEngine
where the default view
* is mapped to the view name passed into the method.
*
+ * @param analysisEngineDescription
+ * the analysis engine description from which the engine is
instantiated
* @param viewName
* the view name to map the default view to
* @return an aggregate analysis engine consisting of a single component
whose default view is
* mapped to the the view named by viewName.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ * @see AggregateBuilder
*/
public static AnalysisEngine createAnalysisEngine(
AnalysisEngineDescription analysisEngineDescription, String viewName)
@@ -131,17 +166,28 @@ public final class AnalysisEngineFactory
}
/**
- * Get an AnalysisEngine from an XML descriptor file and a set of
configuration parameters.
+ * Get an {@link AnalysisEngine} from an XML descriptor file and a set of
configuration
+ * parameters.
*
* @param descriptorPath
* The path to the XML descriptor file.
* @param configurationData
* Any additional configuration parameters to be set. These should
be supplied as (name,
* value) pairs, so there should always be an even number of
parameters.
- * @return The AnalysisEngine created from the XML descriptor and the
configuration parameters.
+ * @return The {@link AnalysisEngine} created from the XML descriptor and
the configuration
+ * parameters.
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
*/
public static AnalysisEngine createAnalysisEngineFromPath(String
descriptorPath,
- Object... configurationData) throws UIMAException, IOException {
+ Object... configurationData) throws InvalidXMLException, IOException,
+ ResourceInitializationException {
AnalysisEngineDescription desc =
createAnalysisEngineDescriptionFromPath(descriptorPath,
configurationData);
return UIMAFramework.produceAnalysisEngine(desc);
@@ -158,9 +204,14 @@ public final class AnalysisEngineFactory
* value) pairs, so there should always be an even number of
parameters.
* @return The {@link AnalysisEngineDescription} created from the XML
descriptor and the
* configuration parameters.
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
*/
public static AnalysisEngineDescription
createAnalysisEngineDescriptionFromPath(
- String descriptorPath, Object... configurationData) throws
UIMAException, IOException {
+ String descriptorPath, Object... configurationData) throws
InvalidXMLException,
+ IOException {
ResourceSpecifier specifier;
specifier =
ResourceCreationSpecifierFactory.createResourceCreationSpecifier(descriptorPath,
configurationData);
@@ -168,17 +219,21 @@ public final class AnalysisEngineFactory
}
/**
- * Get an AnalysisEngine from an OperationalProperties class, a type system
and a set of
- * configuration parameters. The type system is detected automatically using
- * {@link TypeSystemDescriptionFactory#createTypeSystemDescription()}.
+ * Create and configure a primitive {@link AnalysisEngine}. The type system
is detected
+ * automatically using {@link
TypeSystemDescriptionFactory#createTypeSystemDescription()}.
*
* @param componentClass
- * The class of the OperationalProperties to be created as an
AnalysisEngine.
+ * a class that extends {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
* @param configurationData
* Any additional configuration parameters to be set. These should
be supplied as (name,
* value) pairs, so there should always be an even number of
parameters.
- * @return The AnalysisEngine created from the OperationalProperties class
and initialized with
- * the type system and the configuration parameters.
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
*/
public static AnalysisEngine createPrimitive(Class<? extends
AnalysisComponent> componentClass,
Object... configurationData) throws ResourceInitializationException {
@@ -187,18 +242,22 @@ public final class AnalysisEngineFactory
}
/**
- * Get an AnalysisEngine from an OperationalProperties class, a type system
and a set of
- * configuration parameters.
+ * Create and configure a primitive {@link AnalysisEngine}.
*
* @param componentClass
- * The class of the OperationalProperties to be created as an
AnalysisEngine.
+ * a class that extends {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
* @param typeSystem
- * A description of the types used by the OperationalProperties
(may be null).
+ * A description of the types (may be null).
* @param configurationData
* Any additional configuration parameters to be set. These should
be supplied as (name,
* value) pairs, so there should always be an even number of
parameters.
- * @return The AnalysisEngine created from the OperationalProperties class
and initialized with
- * the type system and the configuration parameters.
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
*/
public static AnalysisEngine createPrimitive(Class<? extends
AnalysisComponent> componentClass,
TypeSystemDescription typeSystem, Object... configurationData)
@@ -206,22 +265,51 @@ public final class AnalysisEngineFactory
return createPrimitive(componentClass, typeSystem, (TypePriorities) null,
configurationData);
}
+ /**
+ * Create and configure a primitive {@link AnalysisEngine}.
+ *
+ * @param componentClass
+ * a class that extends {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities as an array of type names (may be null).
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ */
public static AnalysisEngine createPrimitive(Class<? extends
AnalysisComponent> componentClass,
- TypeSystemDescription typeSystem, String[] prioritizedTypeNames,
- Object... configurationData) throws ResourceInitializationException {
- TypePriorities typePriorities = TypePrioritiesFactory
- .createTypePriorities(prioritizedTypeNames);
- return createPrimitive(componentClass, typeSystem, typePriorities,
configurationData);
+ TypeSystemDescription typeSystem, String[] typePriorities, Object...
configurationData)
+ throws ResourceInitializationException {
+ TypePriorities tp = null;
+ if (typePriorities != null) {
+ tp = TypePrioritiesFactory.createTypePriorities(typePriorities);
+ }
+ return createPrimitive(componentClass, typeSystem, tp, configurationData);
}
/**
- * A simple factory method for creating a primitive
AnalysisEngineDescription for a given class,
- * type system, and configuration parameter data
+ * Create and configure a primitive {@link AnalysisEngine}.
*
* @param componentClass
- * a class that extends AnalysisComponent e.g.
+ * a class that extends {@link AnalysisComponent} e.g. via
* {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return a description for this analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
*/
public static AnalysisEngineDescription createPrimitiveDescription(
Class<? extends AnalysisComponent> componentClass,
TypeSystemDescription typeSystem,
@@ -231,13 +319,18 @@ public final class AnalysisEngineFactory
}
/**
- * A simple factory method for creating a primitive
AnalysisEngineDescription for a given class,
- * type system, and configuration parameter data The type system is detected
automatically using
- * {@link TypeSystemDescriptionFactory#createTypeSystemDescription()}.
+ * Create and configure a primitive {@link AnalysisEngine}. The type system
is detected
+ * automatically using {@link
TypeSystemDescriptionFactory#createTypeSystemDescription()}.
*
* @param componentClass
- * a class that extends AnalysisComponent e.g.
+ * a class that extends {@link AnalysisComponent} e.g. via
* {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return a description for this analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
*/
public static AnalysisEngineDescription createPrimitiveDescription(
Class<? extends AnalysisComponent> componentClass, Object...
configurationData)
@@ -246,6 +339,23 @@ public final class AnalysisEngineFactory
return createPrimitiveDescription(componentClass, tsd, (TypePriorities)
null, configurationData);
}
+ /**
+ * Create and configure a primitive {@link AnalysisEngine}.
+ *
+ * @param componentClass
+ * a class that extends {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return a description for this analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ */
public static AnalysisEngineDescription createPrimitiveDescription(
Class<? extends AnalysisComponent> componentClass,
TypeSystemDescription typeSystem,
TypePriorities typePriorities, Object... configurationData)
@@ -255,7 +365,32 @@ public final class AnalysisEngineFactory
}
/**
- * The factory methods for creating an AnalysisEngineDescription
+ * Create and configure a primitive {@link AnalysisEngine}.
+ *
+ * @param componentClass
+ * a class that extends {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param indexes
+ * the Feature Structure Index collection used by this analysis
engine to iterate over
+ * annotations in the {@link org.apache.uima.cas.CAS}. If this is
not null explicitly,
+ * any indexes declared via {@link
org.apache.uima.fit.descriptor.FsIndexCollection} in
+ * the class are ignored.
+ * @param capabilities
+ * the operations the component can perform in terms of consumed
and produced types, sofa
+ * names, and languages. If this is set explicitly here, any
capabilities declared via
+ * {@link SofaCapability} or {@link TypeCapability} in the class
are ignored.
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters. In addition to
+ * parameter names, external resource keys can also be specified.
The value has to be an
+ * {@link ExternalResourceDescription} in that case.
+ * @return a description for this analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
*/
public static AnalysisEngineDescription createPrimitiveDescription(
Class<? extends AnalysisComponent> componentClass,
TypeSystemDescription typeSystem,
@@ -276,6 +411,33 @@ public final class AnalysisEngineFactory
externalResources);
}
+ /**
+ * Create and configure a primitive {@link AnalysisEngine}.
+ *
+ * @param componentClass
+ * a class that extends {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param indexes
+ * the Feature Structure Index collection used by this analysis
engine to iterate over
+ * annotations in the {@link org.apache.uima.cas.CAS}. If this is
not null explicitly,
+ * any indexes declared via {@link
org.apache.uima.fit.descriptor.FsIndexCollection} in
+ * the class are ignored.
+ * @param capabilities
+ * the operations the component can perform in terms of consumed
and produced types, sofa
+ * names, and languages. If this is set explicitly here, any
capabilities declared via
+ * {@link SofaCapability} or {@link TypeCapability} in the class
are ignored.
+ * @param configurationParameters
+ * the configuration parameter declarations.
+ * @param configurationValues
+ * the configuration parameter values.
+ * @return a description for this analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ */
public static AnalysisEngineDescription createPrimitiveDescription(
Class<? extends AnalysisComponent> componentClass,
TypeSystemDescription typeSystem,
TypePriorities typePriorities, FsIndexCollection indexes,
Capability[] capabilities,
@@ -285,6 +447,35 @@ public final class AnalysisEngineFactory
capabilities, configurationParameters, configurationValues, null);
}
+ /**
+ * Create and configure a primitive {@link AnalysisEngine}.
+ *
+ * @param componentClass
+ * a class that extends {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param indexes
+ * the Feature Structure Index collection used by this analysis
engine to iterate over
+ * annotations in the {@link org.apache.uima.cas.CAS}. If this is
set explicitly here,
+ * any indexes declared via {@link
org.apache.uima.fit.descriptor.FsIndexCollection} in
+ * the class are ignored.
+ * @param capabilities
+ * the operations the component can perform in terms of consumed
and produced types, sofa
+ * names, and languages. If this is set explicitly here, any
capabilities declared via
+ * {@link SofaCapability} or {@link TypeCapability} in the class
are ignored.
+ * @param configurationParameters
+ * the configuration parameter declarations.
+ * @param configurationValues
+ * the configuration parameter values.
+ * @param externalResources
+ * external resources to bind to the analysis engine. (may be null)
+ * @return a description for this analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ */
public static AnalysisEngineDescription createPrimitiveDescription(
Class<? extends AnalysisComponent> componentClass,
TypeSystemDescription typeSystem,
TypePriorities typePriorities, FsIndexCollection indexes,
Capability[] capabilities,
@@ -319,7 +510,7 @@ public final class AnalysisEngineFactory
// set parameters
setParameters(desc, componentClass, configurationParameters,
configurationValues);
-
+
// set the type system
if (typeSystem != null) {
desc.getAnalysisEngineMetaData().setTypeSystem(typeSystem);
@@ -364,17 +555,52 @@ public final class AnalysisEngineFactory
return desc;
}
+ /**
+ * Create and configure a primitive {@link AnalysisEngine}.
+ *
+ * @param componentClass
+ * a class that extends {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ */
public static AnalysisEngine createPrimitive(Class<? extends
AnalysisComponent> componentClass,
TypeSystemDescription typeSystem, TypePriorities typePriorities,
- Object... configurationParameters) throws
ResourceInitializationException {
+ Object... configurationData) throws ResourceInitializationException {
AnalysisEngineDescription desc =
createPrimitiveDescription(componentClass, typeSystem,
- typePriorities, configurationParameters);
+ typePriorities, configurationData);
// create the AnalysisEngine, initialize it and return it
return createPrimitive(desc);
}
+ /**
+ * Create and configure a primitive {@link AnalysisEngine}.
+ *
+ * @param desc
+ * the descriptor to create the analysis engine from.
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ */
public static AnalysisEngine createPrimitive(AnalysisEngineDescription desc,
Object... configurationData) throws ResourceInitializationException {
AnalysisEngineDescription descClone = (AnalysisEngineDescription)
desc.clone();
@@ -382,42 +608,123 @@ public final class AnalysisEngineFactory
return UIMAFramework.produceAnalysisEngine(descClone);
}
+ /**
+ * Create and configure an aggregate {@link AnalysisEngine} from several
component classes.
+ *
+ * @param componentClasses
+ * a list of class that extend {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param sofaMappings
+ * The SofA mappings (may be null).
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ */
public static AnalysisEngine createAggregate(
List<Class<? extends AnalysisComponent>> componentClasses,
TypeSystemDescription typeSystem, TypePriorities typePriorities,
- SofaMapping[] sofaMappings, Object... configurationParameters)
+ SofaMapping[] sofaMappings, Object... configurationData)
throws ResourceInitializationException {
AnalysisEngineDescription desc =
createAggregateDescription(componentClasses, typeSystem,
- typePriorities, sofaMappings, configurationParameters);
+ typePriorities, sofaMappings, configurationData);
// create the AnalysisEngine, initialize it and return it
AnalysisEngine engine = new AggregateAnalysisEngine_impl();
engine.initialize(desc, null);
return engine;
}
+ /**
+ * Create and configure an aggregate {@link AnalysisEngine} from several
component classes.
+ *
+ * @param componentClasses
+ * a list of class that extend {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param sofaMappings
+ * The SofA mappings (may be null).
+ * @param flowControllerDescription
+ * the flow controller description to be used by this aggregate
(may be null).
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ */
public static AnalysisEngine createAggregate(
List<Class<? extends AnalysisComponent>> componentClasses,
TypeSystemDescription typeSystem, TypePriorities typePriorities,
SofaMapping[] sofaMappings, FlowControllerDescription
flowControllerDescription,
- Object... configurationParameters) throws
ResourceInitializationException {
+ Object... configurationData) throws ResourceInitializationException {
AnalysisEngineDescription desc =
createAggregateDescription(componentClasses, typeSystem,
- typePriorities, sofaMappings, configurationParameters,
flowControllerDescription);
+ typePriorities, sofaMappings, configurationData,
flowControllerDescription);
// create the AnalysisEngine, initialize it and return it
AnalysisEngine engine = new AggregateAnalysisEngine_impl();
engine.initialize(desc, null);
return engine;
}
+ /**
+ * Create an aggregate {@link AnalysisEngine}.
+ *
+ * @param desc
+ * the descriptor to create the analysis engine from.
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ */
public static AnalysisEngine createAggregate(AnalysisEngineDescription desc)
throws ResourceInitializationException {
// create the AnalysisEngine, initialize it and return it
return UIMAFramework.produceAnalysisEngine(desc, null, null);
}
+ /**
+ * Create and configure an aggregate {@link AnalysisEngine} from several
component classes.
+ *
+ * @param componentClasses
+ * a list of class that extend {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param sofaMappings
+ * The SofA mappings (may be null).
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return a description for this aggregate analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ */
public static AnalysisEngineDescription createAggregateDescription(
List<Class<? extends AnalysisComponent>> componentClasses,
TypeSystemDescription typeSystem, TypePriorities typePriorities,
- SofaMapping[] sofaMappings, Object... configurationParameters)
+ SofaMapping[] sofaMappings, Object... configurationData)
throws ResourceInitializationException {
List<AnalysisEngineDescription> primitiveEngineDescriptions = new
ArrayList<AnalysisEngineDescription>();
@@ -425,7 +732,7 @@ public final class AnalysisEngineFactory
for (Class<? extends AnalysisComponent> componentClass : componentClasses)
{
AnalysisEngineDescription primitiveDescription =
createPrimitiveDescription(componentClass,
- typeSystem, typePriorities, configurationParameters);
+ typeSystem, typePriorities, configurationData);
primitiveEngineDescriptions.add(primitiveDescription);
componentNames.add(componentClass.getName());
}
@@ -433,6 +740,25 @@ public final class AnalysisEngineFactory
sofaMappings, null);
}
+ /**
+ * Create and configure an aggregate {@link AnalysisEngine} from several
component descriptions.
+ *
+ * @param analysisEngineDescriptions
+ * a list of analysis engine descriptions from which the aggregate
engine is instantiated
+ * @param componentNames
+ * a list of names for the analysis engines in the aggregate. There
must be exactly one
+ * name for each analysis engine, given in the same order as the
descriptions.
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param sofaMappings
+ * The SofA mappings (may be null).
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ */
public static AnalysisEngine createAggregate(
List<AnalysisEngineDescription> analysisEngineDescriptions,
List<String> componentNames,
TypePriorities typePriorities, SofaMapping[] sofaMappings)
@@ -447,6 +773,15 @@ public final class AnalysisEngineFactory
}
+ /**
+ * Create and configure an aggregate {@link AnalysisEngine} from several
component descriptions.
+ *
+ * @param analysisEngineDescriptions
+ * a list of analysis engine descriptions from which the aggregate
engine is instantiated
+ * @return a description for this aggregate analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ */
public static AnalysisEngineDescription createAggregateDescription(
AnalysisEngineDescription... analysisEngineDescriptions)
throws ResourceInitializationException {
@@ -461,25 +796,67 @@ public final class AnalysisEngineFactory
null, null);
}
+ /**
+ * Create and configure an aggregate {@link AnalysisEngine} from several
component classes.
+ *
+ * @param componentClasses
+ * a list of class that extend {@link AnalysisComponent} e.g. via
+ * {@link org.apache.uima.fit.component.JCasAnnotator_ImplBase}
+ * @param typeSystem
+ * A description of the types (may be null).
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param sofaMappings
+ * The SofA mappings (may be null).
+ * @param flowControllerDescription
+ * the flow controller description to be used by this aggregate
(may be null).
+ * @param configurationData
+ * Any additional configuration parameters to be set. These should
be supplied as (name,
+ * value) pairs, so there should always be an even number of
parameters.
+ * @return a description for this aggregate analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ */
public static AnalysisEngineDescription createAggregateDescription(
List<Class<? extends AnalysisComponent>> componentClasses,
TypeSystemDescription typeSystem, TypePriorities typePriorities,
SofaMapping[] sofaMappings, FlowControllerDescription
flowControllerDescription,
- Object... configurationParameters) throws
ResourceInitializationException {
+ Object... configurationData) throws ResourceInitializationException {
List<AnalysisEngineDescription> primitiveEngineDescriptions = new
ArrayList<AnalysisEngineDescription>();
List<String> componentNames = new ArrayList<String>();
for (Class<? extends AnalysisComponent> componentClass : componentClasses)
{
AnalysisEngineDescription primitiveDescription =
createPrimitiveDescription(componentClass,
- typeSystem, typePriorities, configurationParameters);
+ typeSystem, typePriorities, configurationData);
primitiveEngineDescriptions.add(primitiveDescription);
componentNames.add(componentClass.getName());
}
- return createAggregateDescription(primitiveEngineDescriptions,
componentNames,
- typePriorities, sofaMappings, flowControllerDescription);
+ return createAggregateDescription(primitiveEngineDescriptions,
componentNames, typePriorities,
+ sofaMappings, flowControllerDescription);
}
+ /**
+ * Create and configure an aggregate {@link AnalysisEngine} from several
component descriptions.
+ *
+ * @param analysisEngineDescriptions
+ * a list of analysis engine descriptions from which the aggregate
engine is instantiated
+ * @param componentNames
+ * a list of names for the analysis engines in the aggregate. There
must be exactly one
+ * name for each analysis engine, given in the same order as the
descriptions.
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param sofaMappings
+ * The SofA mappings (may be null).
+ * @param flowControllerDescription
+ * the flow controller description to be used by this aggregate
(may be null).
+ * @return an {@link AnalysisEngine} created from the specified component
class and initialized
+ * with the configuration parameters.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @see <a href="package-summary.html#InstancesVsDescriptors">Why are
descriptors better than
+ * component instances?</a>
+ */
public static AnalysisEngine createAggregate(
List<AnalysisEngineDescription> analysisEngineDescriptions,
List<String> componentNames,
TypePriorities typePriorities, SofaMapping[] sofaMappings,
@@ -498,6 +875,14 @@ public final class AnalysisEngineFactory
/**
* A simplified factory method for creating an aggregate description for a
given flow controller
* and a sequence of analysis engine descriptions
+ *
+ * @param flowControllerDescription
+ * the flow controller description to be used by this aggregate
(may be null).
+ * @param analysisEngineDescriptions
+ * a list of analysis engine descriptions from which the aggregate
engine is instantiated
+ * @return a description for this aggregate analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
*/
public static AnalysisEngineDescription createAggregateDescription(
FlowControllerDescription flowControllerDescription,
@@ -517,9 +902,19 @@ public final class AnalysisEngineFactory
/**
* A factory method for creating an aggregate description.
*
- * @param analysisEngineDescriptions list of analysis engine descriptions.
- * @param componentNames list of component names - must be one name per
description!
- * @param typeSystem the type system to be used.
+ * @param analysisEngineDescriptions
+ * list of analysis engine descriptions.
+ * @param componentNames
+ * list of component names - must be one name per description!
+ * @param typePriorities
+ * The type priorities (may be null).
+ * @param sofaMappings
+ * The SofA mappings (may be null).
+ * @param flowControllerDescription
+ * the flow controller description to be used by this aggregate
(may be null).
+ * @return a description for this aggregate analysis engine.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
*/
public static AnalysisEngineDescription createAggregateDescription(
List<AnalysisEngineDescription> analysisEngineDescriptions,
List<String> componentNames,
@@ -534,7 +929,7 @@ public final class AnalysisEngineFactory
if (analysisEngineDescriptions == null) {
throw new IllegalArgumentException("Parameter
[analysisEngineDescriptions] cannot be null");
}
-
+
if (analysisEngineDescriptions.size() != componentNames.size()) {
throw new IllegalArgumentException("Number of descriptions ["
+ analysisEngineDescriptions.size() + "]does not match number of
component names ["
@@ -583,7 +978,7 @@ public final class AnalysisEngineFactory
if (sofaMappings != null) {
desc.setSofaMappings(sofaMappings);
}
-
+
return desc;
}
@@ -597,9 +992,18 @@ public final class AnalysisEngineFactory
* Either the path of a file to be loaded, or a string to use as
the text. If the string
* given is not a valid path in the file system, it will be assumed
to be text.
* @return A JCas object containing the processed document.
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @throws AnalysisEngineProcessException
+ * if a failure occurs during processing.
*/
- public static JCas process(String descriptorFileName, String fileNameOrText)
throws IOException,
- UIMAException {
+ public static JCas process(String descriptorFileName, String fileNameOrText)
+ throws InvalidXMLException, ResourceInitializationException,
IOException,
+ AnalysisEngineProcessException {
AnalysisEngine engine = createAnalysisEngine(descriptorFileName);
JCas jCas = process(engine, fileNameOrText);
engine.collectionProcessComplete();
@@ -615,9 +1019,15 @@ public final class AnalysisEngineFactory
* Either the path of a file to be loaded, or a string to use as
the text. If the string
* given is not a valid path in the file system, it will be assumed
to be text.
* @return A JCas object containing the processed document.
+ * @throws ResourceInitializationException
+ * if a failure occurred during production of the resource.
+ * @throws IOException
+ * if a file name was specified and the text could not be read
from the file.
+ * @throws AnalysisEngineProcessException
+ * if a failure occurs during processing.
*/
public static JCas process(AnalysisEngine analysisEngine, String
fileNameOrText)
- throws IOException, UIMAException {
+ throws ResourceInitializationException,
AnalysisEngineProcessException, IOException {
JCas jCas = analysisEngine.newJCas();
process(jCas, analysisEngine, fileNameOrText);
return jCas;
@@ -625,9 +1035,21 @@ public final class AnalysisEngineFactory
/**
* Provides a convenience method for running an AnalysisEngine over some
text with a given JCas.
+ *
+ * @param jCas
+ * the CAS to process.
+ * @param analysisEngine
+ * The AnalysisEngine object to process the text.
+ * @param fileNameOrText
+ * Either the path of a file to be loaded, or a string to use as
the text. If the string
+ * given is not a valid path in the file system, it will be assumed
to be text.
+ * @throws IOException
+ * if a file name was specified and the text could not be read
from the file.
+ * @throws AnalysisEngineProcessException
+ * if a failure occurs during processing.
*/
public static void process(JCas jCas, AnalysisEngine analysisEngine, String
fileNameOrText)
- throws IOException, UIMAException {
+ throws IOException, AnalysisEngineProcessException {
File textFile = new File(fileNameOrText);
String text;
if (textFile.exists()) {
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/ResourceCreationSpecifierFactory.java
URL:
http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/ResourceCreationSpecifierFactory.java?rev=1480983&r1=1480982&r2=1480983&view=diff
==============================================================================
---
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/ResourceCreationSpecifierFactory.java
(original)
+++
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/ResourceCreationSpecifierFactory.java
Fri May 10 11:31:15 2013
@@ -23,13 +23,13 @@ import java.lang.reflect.Array;
import java.net.URL;
import java.util.Collection;
-import org.apache.uima.UIMAException;
import org.apache.uima.UIMAFramework;
import org.apache.uima.resource.ResourceCreationSpecifier;
import org.apache.uima.resource.metadata.ConfigurationParameter;
import org.apache.uima.resource.metadata.ConfigurationParameterDeclarations;
import org.apache.uima.resource.metadata.ConfigurationParameterSettings;
import org.apache.uima.resource.metadata.ResourceMetaData;
+import org.apache.uima.util.InvalidXMLException;
import org.apache.uima.util.XMLInputSource;
import org.apache.uima.util.XMLParser;
@@ -51,9 +51,13 @@ public final class ResourceCreationSpeci
* value) pairs, so there should always be an even number of
parameters.
* @return The ResourceCreationSpecifier for the XML descriptor with all the
configuration
* parameters set.
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
*/
public static ResourceCreationSpecifier createResourceCreationSpecifier(URL
descriptorURL,
- Object[] parameters) throws UIMAException, IOException {
+ Object[] parameters) throws InvalidXMLException, IOException {
return createResourceCreationSpecifier(new XMLInputSource(descriptorURL),
parameters);
}
@@ -68,9 +72,11 @@ public final class ResourceCreationSpeci
* value) pairs, so there should always be an even number of
parameters.
* @return The ResourceCreationSpecifier for the XML descriptor with all the
configuration
* parameters set.
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
*/
public static ResourceCreationSpecifier
createResourceCreationSpecifier(XMLInputSource xmlInput,
- Object[] parameters) throws UIMAException, IOException {
+ Object[] parameters) throws InvalidXMLException {
ConfigurationParameterFactory.ensureParametersComeInPairs(parameters);
ResourceCreationSpecifier specifier;
@@ -92,9 +98,13 @@ public final class ResourceCreationSpeci
* value) pairs, so there should always be an even number of
parameters.
* @return The ResourceCreationSpecifier for the XML descriptor with all the
configuration
* parameters set.
+ * @throws IOException
+ * if an I/O error occurs
+ * @throws InvalidXMLException
+ * if the input XML is not valid or does not specify a valid
{@link ResourceSpecifier}
*/
public static ResourceCreationSpecifier
createResourceCreationSpecifier(String descriptorPath,
- Object[] parameters) throws UIMAException, IOException {
+ Object[] parameters) throws InvalidXMLException, IOException {
return createResourceCreationSpecifier(new XMLInputSource(descriptorPath),
parameters);
}
@@ -132,6 +142,13 @@ public final class ResourceCreationSpeci
/**
* This method passes through to
* {@link #setConfigurationParameters(ResourceMetaData,
ConfigurationParameter[], Object[])}
+ *
+ * @param specifier
+ * The ResourceCreationSpecifier whose parameters are to be set.
+ * @param configurationParameters
+ * the configuration parameter declarations.
+ * @param configurationValues
+ * the configuration parameter values.
*/
public static void setConfigurationParameters(ResourceCreationSpecifier
specifier,
ConfigurationParameter[] configurationParameters, Object[]
configurationValues) {
@@ -143,6 +160,8 @@ public final class ResourceCreationSpeci
* This method sets the configuration parameters of a resource. The length of
* configurationParameters and configurationValues should be equal
*
+ * @param metaData
+ * The ResourceMetaData whose parameters are to be set.
* @param configurationParameters
* an array of configuration parameters
* @param configurationValues
@@ -154,19 +173,20 @@ public final class ResourceCreationSpeci
.getConfigurationParameterDeclarations();
ConfigurationParameterSettings paramSettings =
metaData.getConfigurationParameterSettings();
for (int i = 0; i < configurationParameters.length; i++) {
- ConfigurationParameter decl = paramDecls.getConfigurationParameter(null,
configurationParameters[i].getName());
+ ConfigurationParameter decl = paramDecls.getConfigurationParameter(null,
+ configurationParameters[i].getName());
if (paramDecls != null && decl == null) {
paramDecls.addConfigurationParameter(configurationParameters[i]);
decl = configurationParameters[i];
}
-
+
// Upgrade single-value to multi-value if necessary
Object value = configurationValues[i];
if ((value != null) && decl.isMultiValued() && !isMultiValue(value)) {
value = Array.newInstance(value.getClass(), 1);
Array.set(value, 0, configurationValues[i]);
}
-
+
paramSettings.setParameterValue(configurationParameters[i].getName(),
value);
}
}
@@ -177,8 +197,7 @@ public final class ResourceCreationSpeci
private static boolean isMultiValue(Object aObject) {
if (aObject != null) {
return (aObject instanceof Collection) || aObject.getClass().isArray();
- }
- else {
+ } else {
return false;
}
}
Modified:
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/package-info.java
URL:
http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/package-info.java?rev=1480983&r1=1480982&r2=1480983&view=diff
==============================================================================
---
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/package-info.java
(original)
+++
uima/sandbox/uimafit/trunk/uimafit/src/main/java/org/apache/uima/fit/factory/package-info.java
Fri May 10 11:31:15 2013
@@ -18,6 +18,36 @@
*/
/**
* Factories to create different kinds of UIMA resource specifiers.
+ *
+ * <h3><a name="InstancesVsDescriptors">Why are descriptors better than
component instances?</a></h3>
+ *
+ * It is recommended to avoid instantiating components with uimaFIT outside of
a running pipeline,
+ * unless necessary and unless you are aware of the consequences.
+ *
+ * When run within a pipeline, such as {@link
org.apache.uima.fit.pipeline.SimplePipeline} or
+ * within a Collection Processing Engine, the pipeline logic takes care of
invoking the life-cycle
+ * methods on a component, such as:
+ *
+ * <ul>
+ * <li>initialize</li>
+ * <li>collectionProcessComplete</li>
+ * <li>destroy</li>
+ * <li>...</li>
+ * </ul>
+ *
+ * When components are created manually, it is the responsability of the
caller to explicitly invoke
+ * the life-cycle methods. The only method that uimaFIT may call is
<em>initialize</em> to provide
+ * an {@link org.apache.uima.UimaContext} with the desired parametrization of
the component.
+ *
+ * Not letting UIMA/uimaFIT manage the life-cycle of a component can, thus,
have some unexpected
+ * effects. For example, a {@link org.apache.uima.collection.CollectionReader}
cannot be reused
+ * after it has been passed to a {@link
org.apache.uima.fit.pipeline.SimplePipeline#runPipeline(org.apache.uima.collection.CollectionReader,
org.apache.uima.analysis_engine.AnalysisEngine...)}.
+ * The pipeline reads all files from the reader instance, and when it is
complete, the reader does
+ * not have any more data to produce. Passing the reader to subsequent {@code
runPipeline} methods will not
+ * produce any results. When a {@link
org.apache.uima.collection.CollectionReaderDescription}
+ * is passed instead, the reader is created, initalized, and destroyed inside
the
+ * {@code runPipeline} method. The description can be passed to multiple
{@code runPipeline} calls
+ * and each time, it will behave the same way, producing all its data.
*/
package org.apache.uima.fit.factory;
