You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2012/12/12 16:07:36 UTC
svn commit: r1420735 [16/16] - in /uima/sandbox/trunk/uimaFIT: ./ scripts/
uimaFIT-examples/ uimaFIT-examples/src/ uimaFIT-examples/src/main/
uimaFIT-examples/src/main/java/ uimaFIT-examples/src/main/java/org/
uimaFIT-examples/src/main/java/org/uimafit...
Added: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/factory/testCrs/SingleFileXReader.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/factory/testCrs/SingleFileXReader.xml?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/factory/testCrs/SingleFileXReader.xml (added)
+++ uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/factory/testCrs/SingleFileXReader.xml Wed Dec 12 15:07:07 2012
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<collectionReaderDescription xmlns="http://uima.apache.org/resourceSpecifier">
+ <frameworkImplementation>org.apache.uima.java</frameworkImplementation>
+ <implementationName>org.uimafit.factory.testCrs.SingleFileXReader</implementationName>
+ <processingResourceMetaData>
+ <name>SingleFileXReader</name>
+ <description>/*
+ Copyright 2009 Regents of the University of Colorado.
+ All rights reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/</description>
+ <version>1.0</version>
+ <vendor/>
+ <configurationParameters>
+ <configurationParameter>
+ <name>org.uimafit.factory.testCrs.SingleFileXReader.fileName</name>
+ <type>String</type>
+ <multiValued>false</multiValued>
+ <mandatory>true</mandatory>
+ </configurationParameter>
+ <configurationParameter>
+ <name>org.uimafit.factory.testCrs.SingleFileXReader.xmlScheme</name>
+ <type>String</type>
+ <multiValued>false</multiValued>
+ <mandatory>false</mandatory>
+ </configurationParameter>
+ </configurationParameters>
+ <configurationParameterSettings/>
+ <typeSystemDescription/>
+ <typePriorities/>
+ <fsIndexCollection/>
+ <capabilities>
+ <capability>
+ <inputs/>
+ <outputs/>
+ <languagesSupported/>
+ </capability>
+ </capabilities>
+ <operationalProperties>
+ <modifiesCas>true</modifiesCas>
+ <multipleDeploymentAllowed>false</multipleDeploymentAllowed>
+ <outputsNewCASes>true</outputsNewCASes>
+ </operationalProperties>
+ </processingResourceMetaData>
+ <resourceManagerConfiguration/>
+</collectionReaderDescription>
Propchange: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/factory/testCrs/SingleFileXReader.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/index/AutoImportableIndex.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/index/AutoImportableIndex.xml?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/index/AutoImportableIndex.xml (added)
+++ uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/index/AutoImportableIndex.xml Wed Dec 12 15:07:07 2012
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<fsIndexCollection xmlns="http://uima.apache.org/resourceSpecifier">
+ <fsIndexes>
+ <fsIndexDescription>
+ <label>Automatically Scanned Index</label>
+ <typeName>org.uimafit.type.Token</typeName>
+ <kind>sorted</kind>
+ <keys>
+ <fsIndexKey>
+ <featureName>begin</featureName>
+ <comparator>reverse</comparator>
+ </fsIndexKey>
+ <fsIndexKey>
+ <featureName>end</featureName>
+ <comparator>standard</comparator>
+ </fsIndexKey>
+ </keys>
+ </fsIndexDescription>
+ </fsIndexes>
+</fsIndexCollection>
\ No newline at end of file
Propchange: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/index/AutoImportableIndex.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/AnalyzedText.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/AnalyzedText.xml?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/AnalyzedText.xml (added)
+++ uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/AnalyzedText.xml Wed Dec 12 15:07:07 2012
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<typeSystemDescription xmlns="http://uima.apache.org/resourceSpecifier">
+ <name>AnalyzedText</name>
+ <description/>
+ <version>1.0</version>
+ <vendor/>
+ <types>
+ <typeDescription>
+ <name>org.uimafit.type.AnalyzedText</name>
+ <description/>
+ <supertypeName>uima.tcas.Annotation</supertypeName>
+ <features>
+ <featureDescription>
+ <name>text</name>
+ <description/>
+ <rangeTypeName>uima.cas.String</rangeTypeName>
+ </featureDescription>
+ </features>
+ </typeDescription>
+ </types>
+</typeSystemDescription>
Propchange: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/AnalyzedText.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Sentence.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Sentence.xml?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Sentence.xml (added)
+++ uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Sentence.xml Wed Dec 12 15:07:07 2012
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<typeSystemDescription xmlns="http://uima.apache.org/resourceSpecifier">
+ <name>Sentence</name>
+ <description> Copyright 2009 Regents of the University of Colorado.
+ All rights reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+</description>
+ <version>1.0</version>
+ <vendor/>
+ <types>
+ <typeDescription>
+ <name>org.uimafit.type.Sentence</name>
+ <description/>
+ <supertypeName>uima.tcas.Annotation</supertypeName>
+ </typeDescription>
+ </types>
+</typeSystemDescription>
Propchange: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Sentence.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Token.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Token.xml?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Token.xml (added)
+++ uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Token.xml Wed Dec 12 15:07:07 2012
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<typeSystemDescription xmlns="http://uima.apache.org/resourceSpecifier">
+ <name>Token</name>
+ <description> Copyright 2009 Regents of the University of Colorado.
+ All rights reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+</description>
+ <version>1.0</version>
+ <vendor/>
+ <types>
+ <typeDescription>
+ <name>org.uimafit.type.Token</name>
+ <description/>
+ <supertypeName>uima.tcas.Annotation</supertypeName>
+ <features>
+ <featureDescription>
+ <name>pos</name>
+ <description/>
+ <rangeTypeName>uima.cas.String</rangeTypeName>
+ </featureDescription>
+ <featureDescription>
+ <name>stem</name>
+ <description/>
+ <rangeTypeName>uima.cas.String</rangeTypeName>
+ </featureDescription>
+ </features>
+ </typeDescription>
+ </types>
+</typeSystemDescription>
Propchange: uima/sandbox/trunk/uimaFIT/uimaFIT/src/test/resources/org/uimafit/type/Token.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/trunk/uimaFIT/wiki/ConfigurationParameters.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/ConfigurationParameters.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/ConfigurationParameters.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/ConfigurationParameters.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,77 @@
+<h1>Configuration Parameters</h1>
+
+<wiki:toc max_depth="2" />
+
+uimaFIT defines the `@ConfigurationParameter` annotation which can be used to annotate the fields of an analysis engine or collection reader. The purpose of this annotation is twofold:
+
+ * injection of parameters from the UIMA context into fields
+ * declaration of parameter metadata (mandatory, default value, description) which can be used to generate XML descriptors
+
+In a regular UIMA component, parameters need to be manually extracted from the UIMA context, typically requiring a type cast.
+
+{{{
+class MyAnalysisEngine extends CasAnnotator_ImplBase {
+ public static final String PARAM_SOURCE_DIRECTORY = "sourceDirectory";
+ private File sourceDirectory;
+
+ public void initialize(UimaContext context) throws ResourceInitializationException {
+ sourceDirectory = new File((String) context.getConfigParameterValue(PARAM_SOURCE_DIRECTORY));
+ }
+}
+}}}
+
+The component has no way to declare a default value or to declare if a parameter is optional or mandatory. In addition, any documentation needs to be maintained in !JavaDoc and in the XML descriptor for the component.
+
+With uimaFIT, all this information can be declared in the component using the `@ConfigurationParameter` annotation.
+
+*`@ConfigurationParameter`*
+|| *Parameter* || *Description* || *Default* ||
+|| _name_ || Parameter name || classname.field ||
+|| _description_ || Description of the parameter || ||
+|| _mandatory_ ||Â Wether a value must be specified ||Â false ||
+|| _defaultValue_ || The defaul value if no value is specified ||Â ||
+
+
+{{{
+class MyAnalysisEngine extends org.uimafit.component.CasAnnotator_ImplBase {
+ public static final String PARAM_SOURCE_DIRECTORY = "sourceDirectory";
+ @ConfigurationParameter(name=PARAM_SOURCE_DIRECTORY, mandatory=true, defaultValue=".",
+ description="Directory to read the data from")
+ private File sourceDirectory;
+}
+}}}
+
+Note, that it is no longer necessary to implement the initialize() method. uimaFIT takes care of locating the parameter "sourceDirectory" in the UIMA context. It recognizes that the File class has a String constructor and uses that to instantiate a new File object from the parameter. If a mandatory parameter is not specified in the context, an exception is thrown.
+
+The other information (defaultValue and description) are used when generating an UIMA component description from the class. It should be pointed out in particular, that uimaFIT does not make use of the default value when injecting parameters into fields. For this reason, it is possible to have a parameter that is mandatory but does have a default value. The default value is used as a parameter value when a component description is generated via the uimaFIT factories unless a parameter is specified in the factory call. If a component description in created manually without specifying a value for a mandatory parameter, uimaFIT will generate an exception.
+
+
+The parameter injection mechanism is implemented in the `ConfigurationParameterInitializer` class. uimaFIT provides several base classes that already come with an `initialize()` method using the initializer:
+
+ * `CasAnnotator_ImplBase`
+ * `CasCollectionReader_ImplBase`
+ * `CasConsumer_ImplBase`
+ * `CasFlowController_ImplBase`
+ * `CasMultiplier_ImplBase`
+ * `JCasAnnotator_ImplBase`
+ * `JCasCollectionReader_ImplBase`
+ * `JCasConsumer_ImplBase`
+ * `JCasFlowController_ImplBase`
+ * `JCasMultiplier_ImplBase`
+ * `Resource_ImplBase`
+
+The `ConfigurationParameterInitializer` can also be used with shared resources:
+
+{{{
+class MySharedResourceObject implements SharedResourceObject {
+ public static final String PARAM_VALUE = "Value";
+ @ConfigurationParameter(name = PARAM_VALUE, mandatory = true)
+ private String value;
+
+ public void load(DataResource aData) throws ResourceInitializationException {
+ ConfigurationParameterInitializer.initialize(this, aData);
+ }
+}
+}}}
+
+Fields that can be annotated with the `@ConfigurationParameter` annotation are any array or collection types of primitive types (`int`, `boolean`, `float`, `double`), any enum types, any types that define a constructor accepting a single `String` (e.g. `File`), as well as, fields of the types `Pattern` and `Locale`.
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/CreatingARelease.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/CreatingARelease.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/CreatingARelease.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/CreatingARelease.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,103 @@
+Here is the current (but not perfect) procedure for creating a release:
+
+= Prerequisites =
+
+ * GnuPG installed and configured and your public key uploaded to one of the key servers. uimaFIT is deployed to Maven Central, which requires that digitial signatures are in place.
+ * Maven 2.2.1+
+ * `settings.xml` file set up as explained in the [https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide Sonatype OSS Maven Repository Usage Guide]
+
+= CHANGES and README =
+
+Be sure that the CHANGES and README files are up-to-date. At least all fixed issues that are tagged with the milestone that is designated to be released should be in the file.
+
+= Maven release =
+
+Prepare the release.
+
+{{{
+$ cd uimafit-parent
+$ mvn release:prepare
+}}}
+
+The !JavaDoc has been regenerated during the prepare step, but not committed. Commit it and then move it to the tag:
+
+{{{
+$ svn commit -m "Updated JavaDoc" apidocs
+$ svn delete -m "Remove old JavaDoc" https://uimafit.googlecode.com/svn/tags/uimafit-parent-VERSION/apidocs
+$ svn copy -m "Add release JavaDoc" https://uimafit.googlecode.com/svn/trunk/apidocs https://uimafit.googlecode.com/svn/tags/uimafit-parent-VERSION/apidocs
+}}}
+
+Now continue with the perform step.
+
+{{{
+$ mvn release:perform
+}}}
+
+Build and upload the distribution archive to Google Code (the release checkout is still there from the perform step).
+
+{{{
+$ cd target/checkout/uimaFIT
+$ mvn assembly:assembly
+}}}
+
+Now the archive is built in target/uimafit-VERSION-plus-dependencies.zip - upload it with your browser.
+
+If you run into login or signing problems, try specificing your username, password and keyname like this. Mind that if you do that on a machine with other users, it may leak your password via the process list and shell history. So better do this on a private machine.
+
+{{{
+$ mvn -Dusername=GOOGLECODE_USERNAME -Dpassword=GOOGLECODE_PASSWORD -Darguments="-Dkeyname=GOOGLECODE_USERNAME" release:prepare
+}}}
+
+If "mvn release:perform" appears to hang check to see if it is asking for your GPG password. Enter is carefully if so.
+
+= Deploy to Maven Central via Sonatype OSS =
+
+ * Go to the [https://oss.sonatype.org Nexus OSS repository] and log in with your Sonatype JIRA account.
+ * Open the *Staging Repositories* page, select *uimaFIT* from the list, select the release you have just performed from the lower part
+ * Select it and click *Close* in the action bar above the list. Enter a meaningful comment, e.g. "uimaFIT 0.9.14 release".
+ * Select it again and click *Release*. Again enter e meaningful comment, e.g. "uimaFIT 0.9.14 release".
+ * wait an hour or so for the sync process to run. Check that the new version is available [http://repo1.maven.org/maven2/org/uimafit/uimafit/ here].
+
+=Update googlecode project=
+
+*Javadoc*:
+ * Update the Javadoc link on the main page via the [http://code.google.com/p/uimafit/admin admin interface]
+ * Also update the Javadoc link in the wiki at [Documentation]
+ * ... both should point to the new release, e.g. to
+{{{
+http://uimafit.googlecode.com/svn/tags/uimafit-parent-0.9.14/uimaFIT/apidocs/index.html
+}}}
+
+*Project artifacts*: The new artifacts have not yet been uploaded to googlecode via the release steps. Uploading the new downloadable files can be done by clicking on the Downloads tab above and following the instructions. The files should be located in the target directory.
+
+*Update current version*: One final thing to do is edit the front page to have the correct xml for a project's pom file - i.e. edit the snippet
+{{{
+<version>0.9.14</version>
+}}}
+so that it is up-to-date.
+
+= Send an announcement =
+After all of the above steps are complete, send an announcement to uimafit-users@googlegroups.com. Here is a template for the email:
+
+{{{
+The uimaFIT development team is pleased to announce the release of uimaFIT 1.3.0.
+
+Changes in brief
+
+- ...
+
+To view the release notes for this release, please visit:
+http://code.google.com/p/uimafit/wiki/ReleaseNotes_1_3_0
+
+To view the full list of changes for this release, please visit:
+http://code.google.com/p/uimafit/source/browse/tags/uimafit-parent-1.3.0/uimaFIT/CHANGES
+
+To view the readme for this release, please visit:
+http://code.google.com/p/uimafit/source/browse/tags/uimafit-parent-1.3.0/uimaFIT/README
+
+Please visit the project home page for information about how to add uimaFIT as a dependency to your Maven built project:
+http://uimafit.googlecode.com
+
+If you do not use Maven, the latest version of uimaFIT can be obtained from the downloads page:
+http://code.google.com/p/uimafit/downloads/list
+}}}
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/DeveloperSetup.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/DeveloperSetup.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/DeveloperSetup.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/DeveloperSetup.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,60 @@
+<wiki:toc max_depth="3" />
+
+= Building uimaFIT from source =
+
+== Eclipse & Plugins ==
+
+It is not necessary to build uimaFIT with the following tools as you can do everything from the command line with subversion and maven clients. However, we use Eclipse along with two plugins, subclipse and m2eclipse, and we encourage you to do the same. Here are the tools that we use:
+
+ * [http://eclipse.org/ Eclipse] 3.5 or higher. You can download "Eclipse IDE for Java Developers"
+ * [http://subclipse.tigris.org/ Subclipse] 1.6.x
+ * update site: http://subclipse.tigris.org/update_1.6.x
+ * [http://m2eclipse.sonatype.org/ m2eclipse] 0.10.0 or higher.
+ * update site: http://m2eclipse.sonatype.org/sites/m2e
+ * Maven SCM handler for Subclipse. This helps m2eclipse integrate with Subclipse and will be necessary for correctly checking out uimaFIT from the subversion repository.
+ * update site: http://m2eclipse.sonatype.org/sites/m2e-extras
+
+== Checking out ==
+
+ * Open the SVN Repositories perspective in Eclipse (Menu -> Window -> Show View -> Other... -> SVN -> SVN Repositories)
+ * Add a SVN repository with the URL http://uimafit.googlecode.com/svn
+ * Expand the uimaFIT repository node in the SVN Repositories view
+ * Right-click on *trunk* and select *Check out as Maven project* and select *Finish*.
+
+Eclipse will set up three projects: uimafit-parent, uimafit and uimafit-examples. Notice that the latter two are physically nested within the former in the directory structure. However, Eclipse displays them as projects at the same node level as uimafit-parent in the "Package Explorer" view.
+
+== Compiling for the first time ==
+
+When you check out uimaFIT, Eclipse will automatically try to build the three projects. You will see errors in the uimaFIT project because code that is generated by UIMA's JCasGen tool is missing. (Note that uimaFIT does not provide a type system except for a toy example type system used only by the test code - which is where the errors occur.) To generate the necessary type system java files do the following:
+
+ * Right-click on the *uimafit* project and select *Run as -> Maven install*.
+
+If compile errors still persist, then perform a clean compile on the project containing errors.
+
+= Misc. =
+
+== Subversion Properties ==
+All java files added to the repository should have the subversion property "svn:eol-style" set to the value "native". This can be accomplished from the commandline with the following:
+
+{{{
+svn propset svn:eol-style native MyUimaFitClass.java
+}}}
+
+Similarly, there are several file extensions for which the mime type should be set. For example, files with the extension *.txt should be of type text/plain and *.html should be of type text/html. See below for the other assignments. This is important so that the generated API docs render correctly in a browser.
+
+Setting these properties is very easy to forget, so you are encouraged to update your subversion config file to include the following lines:
+
+{{{
+enable-auto-props = yes
+[auto-props]
+*.txt = svn:mime-type=text/plain
+*.html = svn:mime-type=text/html
+*.css = svn:mime-type=text/css
+*.png = svn:mime-type=image/png
+*.jpg = svn:mime-type=image/jpeg
+*.java = svn:eol-style=native
+}}}
+
+== Formatting Conventons ==
+
+All `*.java` files should conform to the project's Java formatting conventions. This can be done by simply executing "Menu -> Source -> Format" in Eclipse. You are encouraged to auto-format when you save a file. This can be done by opening the Eclipse Properties for the uimaFIT project and selecting "Java Editor -> Save Actions" and enabling project specific settings and turning on the radio button labeled "Format all lines" under "Format source code". For additional discussing about our formatting conventions, please see issue #28.
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/Documentation.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/Documentation.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/Documentation.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/Documentation.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,43 @@
+= User Documentation =
+
+ The following list provides links to various resources for learning more about uimaFIT. If you can not find an answer to your question, then please send
+ email to [mailto:uimafit-users@googlegroups.com uimafit-users@googlegroups.com].
+
+== Introduction ==
+
+ * [UserSetup User setup instructions]
+ * [TwoSidesOfUimaFIT Conceptual Overview]
+ * [GettingStarted Getting started tutorial]
+
+== Features ==
+
+ * [Pipelines Pipelines]
+ * [TypeDescriptorDetection Type systems]
+ * [ConfigurationParameters Configuration parameters]
+ * [ExternalResources External resources]
+ * [WorkingWithSofaViews Sofas/Views]
+
+== Use cases ==
+
+ * [WritingTests Writing tests]
+ * [RunningExperiments Running experiments]
+
+== Examples, Tests and Reference Documentation ==
+
+ * [http://code.google.com/p/uimafit/source/browse/#svn/trunk/uimaFIT-examples/src/main/java/org/uimafit/examples Examples project] provides a number of examples.
+ * The [http://code.google.com/p/uimafit/source/browse/#svn/trunk/uimaFIT/src/test/java/org/uimafit%3Fstate%3Dclosed unit tests] are fairly complete and provide a lot of code examples that should be helpful.
+ * [http://uimafit.googlecode.com/svn/tags/uimafit-parent-1.4.0/apidocs/index.html Javadocs]
+
+= Developer Documentation =
+
+ * [DeveloperSetup Developer setup instructions] page provides instructions for checking out the uimaFIT code and building it within eclipse. These instructions may also be useful if you want to e.g. build and run code in the uimafit-examples project.
+ * [CreatingARelease Release instructions] page provides instructions for creating a new release of uimaFIT.
+ * [Issues Issues]
+
+= Releases =
+
+ * [http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT/CHANGES CHANGES]
+ * [ReleaseNotes_1_3_0 uimaFIT 1.3.0 release notes]
+ * [ReleaseNotes_1_3_1 uimaFIT 1.3.1 release notes]
+ * [ReleaseNotes_1_4_0 uimaFIT 1.4.0 release notes]
+
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/ExternalResources.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/ExternalResources.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/ExternalResources.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/ExternalResources.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,187 @@
+<h1>External Resources</h1>
+
+<wiki:toc max_depth="2" />
+
+An analysis engine often uses some data model. This may be as simple as word frequency counts or as complex as the model of a parser. Often these models can become quite large. If an analysis engine is deployed multiple times in the same pipeline or runs on multiple CPU cores, memory can be saved by using a shared instance of the data model. UIMA supports such a scenario by so-called external resources. The following sections illustrates how external resources can be used with uimaFIT.
+
+First create a class for the shared data model. Usually this class would load its data from some URI and then expose it via its methods. An example would be to load word frequency counts and to provide a `getFrequency()` method. In our simple example we do not load anything from the provided URI - we just offer a method to get the URI from which data be loaded.
+
+{{{
+// Simple model that only stores the URI it was loaded from. Normally data
+// would be loaded from the URI instead and made accessible through methods
+// in this class. This simple example only allows to access the URI.
+public static final class SharedModel implements SharedResourceObject {
+ private String uri;
+
+ public void load(DataResource aData) throws ResourceInitializationException {
+ uri = aData.getUri().toString();
+ }
+
+ public String getUri() { return uri; }
+}
+}}}
+
+== Resource injection ==
+
+=== Regular UIMA components ===
+
+When an external resource is used in a regular UIMA component, it is usually fetched from the context, cast and copied to a class member variable.
+
+{{{
+class MyAnalysisEngine extends CasAnnotator_ImplBase {
+ final static String MODEL_KEY = "Model";
+ private SharedModel model;
+
+ public void initialize(UimaContext context) throws ResourceInitializationException {
+ configuredResource = (SharedModel) getContext().getResourceObject(MODEL_KEY);
+ }
+}
+}}}
+
+uimaFIT can be used to inject external resources into such traditional components using the `createDependencyAndBind()` method. To show that this works with any off-the-shelf UIMA component, the following example uses uimaFIT to configure the OpenNLP Tokenizer:
+
+{{{
+// Create descriptor
+AnalysisEngineDescription tokenizer = createPrimitiveDescription(Tokenizer.class,
+ UimaUtil.TOKEN_TYPE_PARAMETER, Token.class.getName(),
+ UimaUtil.SENTENCE_TYPE_PARAMETER, Sentence.class.getName());
+
+// Create the external resource dependency for the model and bind it
+createDependencyAndBind(tokenizer, UimaUtil.MODEL_PARAMETER,
+ TokenizerModelResourceImpl.class,
+ "http://opennlp.sourceforge.net/models-1.5/en-token.bin");
+}}}
+
+=== uimaFIT-aware components ===
+
+uimaFIT provides the `@ExternalResource` annotation to inject external resources directly into class member variables.
+
+*`@ExternalResource`*
+|| *Parameter* || *Description* || *Default* ||
+|| _key_ || Resource key || field type ||
+|| _api_ || Used when the external resource type is different from the field type, e.g. when using an ExternalResourceLocator || field type ||
+|| _mandatory_ ||Â Whether a value must be specified ||Â true ||
+
+{{{
+// Example annotator that uses the SharedModel. In the process() we only test
+// if the model was properly initialized by uimaFIT
+public static class Annotator extends org.uimafit.component.JCasAnnotator_ImplBase {
+ final static String MODEL_KEY = "Model";
+ @ExternalResource(key = MODEL_KEY)
+ private SharedModel model;
+
+ public void process(JCas aJCas) throws AnalysisEngineProcessException {
+ assertTrue(model.getUri().endsWith("gene_model_v02.bin"));
+ // Prints the instance ID to the console - this proves the same instance
+ // of the SharedModel is used in both Annotator instances.
+ System.out.println(model);
+ }
+}}}
+
+Note, that it is no longer necessary to implement the initialize() method. uimaFIT takes care of locating the external resource "Model" in the UIMA context and assigns it to the field `model`. If a mandatory resource is not present in the context, an exception is thrown.
+
+The resource injection mechanism is implemented in the `ExternalResourceInitializer` class. uimaFIT provides several base classes that already come with an `initialize()` method using the initializer:
+
+ * `CasAnnotator_ImplBase`
+ * `CasCollectionReader_ImplBase`
+ * `CasConsumer_ImplBase`
+ * `CasFlowController_ImplBase`
+ * `CasMultiplier_ImplBase`
+ * `JCasAnnotator_ImplBase`
+ * `JCasCollectionReader_ImplBase`
+ * `JCasConsumer_ImplBase`
+ * `JCasFlowController_ImplBase`
+ * `JCasMultiplier_ImplBase`
+ * `Resource_ImplBase`
+
+When building a pipeline, external resources can be set of a component just like configuration parameters. External resources and configuration parameters can be mixed and appear in any order when creating a component description.
+
+Note that in the following example, we create only one external resource description and use it to configure two different analysis engines. Because we only use a single description, also only a single instance of the external resource is created and shared between the two engines.
+
+{{{
+ExternalResourceDescription extDesc = createExternalResourceDescription(
+ SharedModel.class, new File("somemodel.bin"));
+
+// Binding external resource to each Annotator individually
+AnalysisEngineDescription aed1 = createPrimitiveDescription(Annotator.class,
+ Annotator.MODEL_KEY, extDesc);
+ AnalysisEngineDescription aed2 = createPrimitiveDescription(Annotator.class,
+ Annotator.MODEL_KEY, extDesc);
+
+ // Check the external resource was injected
+ AnalysisEngineDescription aaed = createAggregateDescription(aed1, aed2);
+ AnalysisEngine ae = createAggregate(aaed);
+ ae.process(ae.newJCas());
+}}}
+
+[http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT-examples/src/main/java/org/uimafit/examples/resource/ExternalResourceExample.java This example] is given as a full JUnit-based example in the the uimaFIT-examples project.
+
+=== Resources extending `Resource_ImplBase` ===
+
+One kind of resources extend `Resource_ImplBase`. These are the easiest to handle, because uimaFIT's version of `Resource_ImplBase` already implements the necessary logic. Just be sure to call `super.initialize()` when overriding `initialize()`. Also mind that external resources are not available yet when `initialize()` is called. For any initialization logic that requires resources, override and implement `afterResourcesInitialized()`. Other than that, injection of external resources works as usual.
+
+{{{
+public static class ChainableResource extends Resource_ImplBase {
+ public final static String PARAM_CHAINED_RESOURCE = "chainedResource";
+ @ExternalResource(key = PARAM_CHAINED_RESOURCE)
+ private ChainableResource chainedResource;
+
+ public void afterResourcesInitialized() {
+ // init logic that requires external resources
+ }
+}
+}}}
+
+=== Resources implementing `SharedResourceObject` ===
+
+The other kind of resources implement `SharedResourceObject`. Since this is an interface, uimaFIT cannot provide the initialization logic, so you have to implement a couple of things in the resource:
+
+ * implement `ExternalResourceAware`
+ * declare a configuration parameter `ExternalResourceFactory.PARAM_RESOURCE_NAME` and return its value in `getResourceName()`
+ * invoke `ConfigurationParameterInitializer.initialize()` in the `load()` method.
+
+Again, mind that external resource not properly initialized until uimaFIT invokes `afterResourcesInitialized()`.
+
+{{{
+public class TestSharedResourceObject implements SharedResourceObject, ExternalResourceAware {
+ @ConfigurationParameter(name=ExternalResourceFactory.PARAM_RESOURCE_NAME)
+ private String resourceName;
+
+ public final static String PARAM_CHAINED_RESOURCE = "chainedResource";
+ @ExternalResource(key = PARAM_CHAINED_RESOURCE)
+ private ChainableResource chainedResource;
+
+ public String getResourceName() {
+ return resourceName;
+ }
+
+ public void load(DataResource aData) throws ResourceInitializationException {
+ ConfigurationParameterInitializer.initialize(this, aData);
+ // rest of the init logic that does not require external resources
+ }
+
+ public void afterResourcesInitialized() {
+ // init logic that requires external resources
+ }
+}
+}}}
+
+=== Note on injecting resources into resources ===
+
+Nested resources are only initialized if they are used in a pipeline which contains at least one component that calls `ConfigurationParameterInitializer.initialize()`. Any component extending uimaFIT's component base classes qualifies. If you use nested resources in a pipeline without any uimaFIT-aware components, you can just add uimaFIT's `NoopAnnotator` to the pipeline.
+
+== Resource locators ==
+
+Normally, in UIMA an external resource needs to implement either `SharedResourceObject` or `Resource`. In order to inject arbitrary objects, uimaFIT has the concept of `ExternalResourceLocator`. When a resource implements this interface, not the resource itself is injected, but the method getResource() is called on the resource and the result is injected. The following example illustrates how to inject an object from JNDI into a UIMA component:
+
+{{{
+class MyAnalysisEngine2 extends JCasAnnotator_ImplBase {
+ static final String RES_DICTIONARY = "dictionary";
+ @ExternalResource(key = RES_DICTIONARY)
+ Dictionary dictionary;
+}
+
+AnalysisEngineDescription desc = createPrimitiveDescription(MyAnalysisEngine2.class);
+bindResource(desc, MyAnalysisEngine2.RES_DICTIONARY, JndiResourceLocator.class,
+ JndiResourceLocator.PARAM_NAME, "dictionaries/german");
+}}}
Added: uima/sandbox/trunk/uimaFIT/wiki/GettingStarted.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/GettingStarted.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/GettingStarted.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/GettingStarted.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,80 @@
+<h1>Getting Started</h1>
+
+<wiki:toc max_depth="2" />
+
+This quick start tutorial demonstrates how to use uimaFIT to define and set a configuration parameter in an analysis engine, run it, and generate a descriptor file for it. The complete code for this example can be found *[http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT-examples/src/main/java/org/uimafit/examples/getstarted here]*.
+
+== A simple analysis engine implementation ==
+
+Here is the complete analysis engine implementation for this example.
+
+{{{
+public class GetStartedQuickAE extends org.uimafit.component.JCasAnnotator_ImplBase {
+ public static final String PARAM_STRING = "stringParam";
+ @ConfigurationParameter(name = PARAM_STRING)
+ private String stringParam;
+
+ @Override
+ public void process(JCas jCas) throws AnalysisEngineProcessException {
+ System.out.println("Hello world! Say 'hi' to " + stringParam);
+ }
+}
+}}}
+
+The first thing to note is that the member variable 'stringParam' is annotated with `@ConfigurationParameter` which tells uimaFIT that this is an analysis engine configuration parameter. It is best practice to create a public constant for the parameter name, here `PARAM_STRING` The second thing to note is that we extend uimaFIT's version of the `JCasAnnotator_ImplBas. The initialize method of this super class calls:
+
+{{{
+ConfigurationParameterInitializer.initializeConfigurationParameters(Object, UimaContext)
+}}}
+
+which populates the configuration parameters with the appropriate contents of the !UimaContext. If you do not want to extend uimaFIT's `JCasAnnotator_ImplBase`, then you can call this method directly in the initialize method of your analysis engine or any class that implements [http://uimafit.googlecode.com/svn/trunk/uimaFIT/apidocs/org/uimafit/factory/initializable/Initializable.html org.uimafit.factory.initializable.Initializable]. You can call this method for an instance of any class that has configuration parameters.
+
+== Running the analysis engine ==
+
+The following lines of code demonstrate how to instantiate and run the analysis engine from a main method:
+
+{{{
+JCas jCas = JCasFactory.createJCas();
+
+AnalysisEngine analysisEngine =
+ AnalysisEngineFactory.createPrimitive(GetStartedQuickAE.class,
+ GetStartedQuickAE.PARAM_STRING, "uimaFIT");
+
+analysisEngine.process(jCas);
+}}}
+
+In a more involved example, we would probably instantiate a collection reader and run this analysis engine over a collection of documents. Here, it suffices to simply create a JCas. Line 3 instantiates the analysis engine using `AnalysisEngineFactory` and sets the string parameter named "stringParam" to the value "uimaFIT". Running this simple program sends the following output to the console:
+
+{{{
+Hello world! Say 'hi' to uimaFIT
+}}}
+
+Normally you would be using a type system with your analysis components. When using uimaFIT, it is easiest to keep your type system descriptors in your source folders and make them known to uimaFIT. To do so, create a file `META-INF/org.uimafit/types.txt` in a source folder and add references to all your type descriptors to the file, one per line. You can also use wildcards. For example:
+
+{{{
+classpath*:org/uimafit/examples/type/Token.xml
+classpath*:org/uimafit/examples/type/Sentence.xml
+classpath*:org/uimafit/examples/tutorial/type/*.xml
+}}}
+
+== Generate a descriptor file ==
+
+The following lines of code demonstrate how a descriptor file can be generated using the class definition:
+
+{{{
+AnalysisEngine analysisEngine =
+ AnalysisEngineFactory.createPrimitive(GetStartedQuickAE.class,
+ GetStartedQuickAE.PARAM_STRING, "uimaFIT");
+
+analysisEngineDescription.toXML(new FileOutputStream("GetStartedQuickAE.xml"));
+}}}
+
+If you open the resulting descriptor file you will see that the configuration parameter "stringParam" is defined with the value set to "uimaFIT". We could now instantiate an analysis engine using this descriptor file with a line of code like this:
+
+{{{
+AnalysisEngineFactory.createAnalysisEngine("GetStartedQuickAE");
+}}}
+
+But, of course, we really wouldn't want to do that now that we can instantiate analysis engines using the class definition as was done above!
+
+This page, of course, did not demonstrate every feature of uimaFIT which provides support for annotating external resources, creating aggregate engines, running pipelines, testing components, among others.
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/Issues.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/Issues.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/Issues.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/Issues.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,31 @@
+<h1>External Resources</h1>
+
+<wiki:toc max_depth="2" />
+
+= Context injection =
+
+There are several issues with the context injection as it is currently implemented in uimaFIT:
+
+ * The field types supported by the parameter injection mechanism are not extensible. To address this, we imagine to support Java Bean PropertyEditors (Issue 79)
+ * Default parameters cannot be overwritten by sub-classes. (Issue 69)
+ * No warning if the context contains a parameter that the component does not know (Issue 7)
+ * Default names for parameters and resources should be the name of the annotated field (Issue 70, Issue 71)
+ * Parameters and resources should be mandatory by default (Issue 72)
+
+== Relation to other dependency injection frameworks ==
+
+JSR 250 defines the `@Resource` annotation. This could be used as an alternative for `@ConfigurationParameter` and `@ExternalResource`, but it does not support all the information provided by the two and provides some that we do not need in UIMA.
+
+|| `@Resource` || `@ConfigurationParameter` || `@ExternalResource` ||
+|| name ||Â name ||Â key ||
+|| type || -- || api ||
+|| shareable || -- || ||
+||Â mappedName || -- || -- ||
+|| description || description || -- ||
+|| authenticationType || -- || -- ||
+|| -- || mandatory || mandatory ||
+|| -- || defaultValue || -- ||
+
+The Spring Framework defines an annotation [http://static.springsource.org/spring/docs/2.0.x/api/org/springframework/beans/factory/annotation/Required.html @Required] which can probably be used in conjunction with `@Resource` to incidate that a value is mandatory (I didn't try this out, but I expect it should work). [http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/spi/Required.html Apache Camel] seems to define a similar annotation.
+
+We do not know of any substitute for defaultValue. However, this information is not used during injection, only during descriptor generation. It may be sensible to have a separate annotation (like `@Required` for 'mandatory') if a JSR 250 compatible approach is desired.
Added: uima/sandbox/trunk/uimaFIT/wiki/Pipelines.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/Pipelines.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/Pipelines.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/Pipelines.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,29 @@
+<h1>Pipelines</h1>
+
+UIMA is a component-based architecture that allows to compose various processing components into a complex processing pipeline. A pipeline typically involves a `CollectionReader` which ingests
+documents and `AnalysisEngines` that do the actual processing.
+
+Normally, you would run a pipeline using a UIMA Collection Processing Engine or using UIMA AS.
+uimaFIT offers a third alternative that is much simpler to use and well suited for embedding
+UIMA pipelines into applications or for writing tests.
+
+As uimaFIT does not supply any readers or processing components, we just assume that we have written three components:
+
+ * TextReader - reads text files from a directory
+ * Tokenizer - annotates tokens
+ * TokenFrequencyWriter - writes a list of tokens and their frequency to a file
+
+We create descriptors for all components and run them as a pipeline:
+
+{{{
+CollectionReaderDescription reader = CollectionReaderFactory.createDescription(
+ TextReader.class, TextReader.PARAM_INPUT, "/home/uimafit/documents");
+
+AnalysisEngineDescription tokenizer = AnalysisEngineFactory.createPrimitiveDescription(
+ Tokenizer.class);
+
+AnalysisEngineDescription tokenFrequencyWriter = AnalysisEngineFactory.createPrimitiveDescription(
+ TokenFrequencyWriter.class, TokenFrequencyWriter.PARAM_OUTPUT, "counts.txt");
+
+SimplePipeline.runPipeline(reader, tokenizer, writer);
+}}}
Added: uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_3_0.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_3_0.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_3_0.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_3_0.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,41 @@
+#summary Release notes for 1.3.0
+
+uimaFIT 1.3.0 is a minor feature release. It should be binary backwards compatible with 1.2.0 and provides new features some of which we introduce next. For a complete list of changes see the [https://uimafit.googlecode.com/svn/tags/uimafit-parent-1.3.0/uimaFIT/CHANGES CHANGES] file
+
+== External resources ==
+
+External resources can now be bound to a component just like you would set a configuration parameter if the component uses the uimaFIT `@ExternalResource` annotation to declare a resource dependency. So if the component declares an external resource like
+
+{{{
+final static String RES_MODEL = "Model";
+@ExternalResource(key = RES_MODEL)
+private Model model;
+}}}
+
+you can set the resource like
+
+{{{
+AnalysisEngineDescription desc = createPrimitiveDescription(Annotator.class,
+ Annotator.PARAM_STRICT, true,
+ Annotator.RES_MODEL, createExternalResourceDescription(
+ Model.class, "path/to/my/model"));
+}}}
+
+== Logging ==
+
+uimaFIT now provides a more convenient logging API similar to Apache Commons Logging and Log4J when using the uimaFIT component base classes:
+
+{{{
+getLogger().error("Unable to read file", e);
+}}}
+
+== selectBetween ==
+
+This new method allows to select all annotations of a specific type located between two boundary annotations:
+
+{{{
+Collection<Token> tokens = selectBetween(Token.class,
+ leftBoundaryAnnotation, rightBoundaryAnnotation);
+}}}
+
+A typical use case would be for relation extraction where you want to extract, say, all tokens between two named entity mentions.
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_3_1.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_3_1.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_3_1.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_3_1.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,20 @@
+#summary Release notes for 1.3.1
+
+uimaFIT 1.3.1 is a minor feature release. It should be binary backwards compatible with 1.3.0 and provides new features some of which we introduce next. For a complete list of changes see the [https://uimafit.googlecode.com/svn/tags/uimafit-parent-1.3.1/uimaFIT/CHANGES CHANGES] file
+
+== Nested external resources ==
+
+Resources can now be injected into other resources.
+
+{{{
+AnalysisEngineDescription descriptor = AnalysisEngineFactory.createPrimitiveDescription(
+ TestAnalysisEngine2.class,
+ TestAnalysisEngine2.PARAM_RESOURCE, createExternalResourceDescription(
+ TestExternalResource2.class,
+ TestExternalResource2.PARAMETER, "value",
+ TestExternalResource2.PARAM_RESOURCE, createExternalResourceDescription(
+ TestExternalResource.class,
+ TestExternalResource.PARAMETER, "value")));
+}}}
+
+Nested resources are only initialized if they are used in a pipeline which contains at least one component that calls `ConfigurationParameterInitializer.initialize()`. Any component extending uimaFIT's component base classes qualifies. If you use nested resources in a pipeline without any uimaFIT-aware components, you can just add uimaFIT's `NoopAnnotator` to the pipeline.
Added: uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_4_0.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_4_0.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_4_0.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/ReleaseNotes_1_4_0.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,31 @@
+#summary Release notes for 1.4.0
+#labels Featured
+
+uimaFIT 1.4.0 is a feature release. It should is source backwards compatible but not binary backwards compatible with 1.3.1 (see issue 104) and provides new features some of which we introduce next. For a complete list of changes see the [https://uimafit.googlecode.com/svn/tags/uimafit-parent-1.4.0/uimaFIT/CHANGES CHANGES] file
+
+== Non-standard parameter types support ==
+
+It is now possible to use parameter values other than the basic ones supported by UIMA (String, int, float, boolean) when setting parameter values with the uimaFIT factory methodes. For example, before you needed to write
+
+{{{
+ createPrimitive(MyComponent.class, PARAM_INPUT_FILE, new File("myfile").getPath());
+}}}
+
+now you can write
+
+{{{
+ createPrimitive(MyComponent.class, PARAM_INPUT_FILE, new File("myfile"));
+}}}
+
+In the background, uimaFIT uses the Java PropertyEditor framework and Spring to perform conversions of values unsupported by UIMA to strings. This should work out-of-the-box for types that come with a String-only constructor, for any primitive types, for enums, and for a number of other types (e.g. Locale). Also collections and array of these types are supported.
+
+== Multi-threaded pipeline support ==
+
+uimaFIT now has a very basic support for running multi-threaded UIMA CPE pipelines. The simplest way to use the new feature is the !CpePipeline class. Forthcoming versions of uimaFIT are likely to further improve on this feature and offer more configuration options.
+
+== New select methods ==
+
+New select methods have been added:
+
+ * selectAll - select all annotations/feature structures from as JCas/CAS.
+ * selectRelative - select a single annotation relative to another annotation.
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/RunningExperiments.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/RunningExperiments.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/RunningExperiments.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/RunningExperiments.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,14 @@
+#summary helpful hints on running NLP experiments in UIMA
+
+The [http://code.google.com/p/uimafit/source/browse/#svn/trunk/uimaFIT-examples/src/main/java/org/uimafit/examples uimafit-examples] project contains a package org.uimafit.examples.experiment.pos which demonstrates a very simple experimental setup for testing a part-of-speech tagger. You may find this example more accessible if you check out the code from subversion and build it in your own environment. Instructions for doing this can be found [DeveloperSetup here].
+
+The documentation for this example can be found in the code itself. Please refer to [http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT-examples/src/main/java/org/uimafit/examples/experiment/pos/RunExperiment.java RunExperiment.java] as a starting point. The following is copied from the javadoc comments of that file:
+
+RunExperiment.java demonstrates a very common (though simplified) experimental setup in which gold standard data is available for some task and you want to evaluate how well your analysis engine works against that data. Here we are evaluating "!BaselineTagger" which is a (ridiculously) simple part-of-speech tagger against the part-of-speech tags found in "src/main/resources/org/uimafit/examples/pos/sample.txt.pos".
+
+The basic strategy is as follows:
+ * post the data "as is" into the default view
+ * parse the gold-standard tokens and part-of-speech tags and put the results into another view we will call GOLD_VIEW
+ * create another view called SYSTEM_VIEW and copy the text and Token annotations from the GOLD_VIEW into this view
+ * Run the !BaselineTagger on the SYSTEM_VIEW over the copied Token annoations
+ * Evaluate the part-of-speech tags found in the SYSTEM_VIEW with those in the GOLD_VIEW
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/TwoSidesOfUimaFIT.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/TwoSidesOfUimaFIT.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/TwoSidesOfUimaFIT.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/TwoSidesOfUimaFIT.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,60 @@
+= Introduction =
+
+While uimaFIT provides many features for a UIMA developer, there are two overarching themes that most features fall under. These two sides of uimaFIT are, while complementary, largely independent of each other. One of the beauties of uimaFIT is that a developer that uses one side of uimaFIT extensively is not required to use the other side at all.
+
+= Simplify Component Implementation =
+
+The first broad theme of uimaFIT provides features that *simplify component implementation*. Our favorite example of this is the @!ConfigurationParameter annotation which allows you to annotate a member variable as a configuration parameter. This annotation in combination with the method !ConfigurationParameterInitializer.initialize completely automates the process of initializing member variables with values from the !UimaContext passed into your analysis engine's initialize method. Similarly, the annotation @!ExternalResource annotation in combination with the method !ExternalResourceInitializer.initialize completely automates the binding of an external resource as defined in the !UimaContext to a member variable. Dispensing with manually writing the code that performs these two tasks reduces effort, eliminates verbose and potentially buggy boiler-plate code, and makes implementing a UIMA component more enjoyable. Consider, for example, a member variable that is of ty
pe 'Locale'. With uimaFIT you can simply annotate the member variable with '@!ConfigurationParameter' and have your initialize method automatically initialize the variable correctly with a string value in the !UimaContext such as "en_US".
+
+= Simplify Component Instantiation =
+
+The second broad theme of uimaFIT provides features that *simplify component instantiation*. Working with UIMA, have you ever said to yourself "but I just want to tag some text!?" What does it take to "just tag some text?" Here's a list of things you must do with the traditional approach:
+
+ * wrap your tagger as a UIMA analysis engine
+ * write a descriptor file for your analysis engine
+ * write a CAS consumer that produces the desired output
+ * write another descriptor file for the CAS consumer
+ * write a descriptor file for a collection reader
+ * write a descriptor file that describes a pipeline
+ * invoke the Collection Processing Manager with your pipeline descriptor file
+
+Each of these steps has its own pitfalls and can be rather time consuming. This is a rather unsatisfying answer to our simple desire to just tag some text. With uimaFIT you can literally eliminate all of these steps. Here's a simple snippet of Java code that demonstrates "tagging some text" with uimaFIT:
+
+{{{
+
+TypeSystemDescription typeSystemDescription = createTypeSystemDescription();
+
+JCas jCas = createJCas(typeSystemDescription);
+
+jCas.setDocumentText("some text");
+
+AnalysisEngine tokenizer = createPrimitive(MyTokenizer.class, typeSystemDescription);
+
+AnalysisEngine tagger = createPrimitive(MyTagger.class, typeSystemDescription);
+
+runPipeline(jCas, tokenizer, tagger);
+
+for(Token token : iterate(jCas, Token.class)){
+ System.out.println(token.getTag());
+}
+
+}}}
+
+This code assumes several static method imports (e.g. createTypeSystemDescription) provided by uimaFIT for brevity. And while the terseness of this code won't make a python programmer blush - it is certainly much easier than the seven steps outlined above!
+
+uimaFIT provides mechanisms to instantiate and run UIMA components programmatically with or without descriptor files. For example, if you have a descriptor file for your analysis engine defined by !MyTagger.java (as shown above), then you can instead instantiate the analysis engine with:
+
+{{{
+AnalysisEngine tagger = createAnalysisEngine("mypackage.MyTagger");
+}}}
+
+This will find the descriptor file 'mypackage/!MyTagger.xml' by name. Similarly, you can find a descriptor file by location with createAnalysisEngineFromPath(). However, if you want to dispense with XML descriptor files altogether (and you probably do), you can use the method createPrimitive() as shown above. One of the driving motivations for creating the second side of uimaFIT is our frustration with descriptor files and our desire to eliminate them. Descriptor files are difficult to maintain because they are generally tightly coupled with java code, they decay without warning, they are wearisome to test, and they proliferate, among other reasons.
+
+= Is this cheating? =
+
+One question that is often raised by new uimaFIT users is whether or not it breaks the "UIMA way". That is, does adopting uimaFIT lead me down a path of creating UIMA components and systems that are incompatible with the traditional UIMA approach? The answer to this question is no. For starters, uimaFIT does not skirt the UIMA mechanism of describing components - it only skips the XML part of it. For example, when the method createPrimitive is called (as shown above) an !AnalysisEngineDescription is created for the !AnalysisEngine. This is the same object type that is instantiated when a descriptor file is used. So, instead of parsing XML to instantiate an !AnalysisEngineDescription, uimaFIT uses a factory method to instantiate it from method parameters. One of the happy benefits of this approach is that for a given !AnalysisEnginedDescription (which can be obtained directly with createPrimitiveDescription) you can generate an XML descriptor file using !AnalysisEngine
Description.toXML(). So, uimaFIT actually provides a very simple and direct path for *generating* XML descriptor files rather than manually creating and maintaining them!
+
+It is also useful to clarify that if you only want to use one side or the other of uimaFIT, then you are free to do so. This is possible precisely because uimaFIT does not workaround UIMA's mechanisms for describing components but rather uses them directly. For example, if the only thing you want to use in uimaFIT is the '@!ConfigurationParameter', then you can do so without worrying about what effect this will have on your descriptor files. This is because your analysis engine will be initialized with exactly the same !UimaContext regardless of whether you instantiate your analysis engine in the "UIMA way" or use one of uimaFIT's factory methods. Similarly, a UIMA component does not need to be annotated with @!ConfiguratioParameter for you to make use of the createPrimitive method. This is because when you pass configuration parameter values in to the createPrimitive method, they are added to an !AnalysisEngineDescription which is used by UIMA to populate a !UimaContex
t - just as it would if you used a descriptor file.
+
+= Conclusion =
+Because uimaFIT can be used to simplify component implementation and instantiation it is easy to assume that you can't do one without the other. This page has demonstrated that while these two sides of uimaFIT complement each other, they are not coupled together and each can be effectively used without the other. Similarly, by understanding how uimaFIT uses the UIMA component description mechanisms directly, one can be assured that uimaFIT enables UIMA development that is compatible and consistent with the UIMA standard and APIs.
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/TypeDescriptorDetection.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/TypeDescriptorDetection.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/TypeDescriptorDetection.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/TypeDescriptorDetection.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,106 @@
+<h1>External Resources</h1>
+
+<wiki:toc max_depth="2" />
+
+UIMA requires that types that are used in the CAS are defined in XML files - so-called type system descriptions (TSD). Whenever a UIMA component is created, it must be associated with such a type system. While it is possible to manually load the type system descriptors and pass them to each
+UIMA component and to each created CAS, it is quite inconvenient to do so. For this reason, uimaFIT supports the automatic detection of such files in the classpath. Thus is becomes possible for a UIMA component provider to have component's type automatically detected and thus the components becomes immediately usable by adding it to the classpath.
+
+= Making types auto-detectable =
+
+The provider of a type system should create a file `META-INF/org.uimafit/types.txt` in the classpath. This file should define the locations of the type system descriptions. Assume that a type `org.uimafit.type.Token` is specified in the TSD `org/uimafit/type/Token.xml`, then the file should have the following contents:
+
+{{{
+classpath*:org/uimafit/type/Token.xml
+}}}
+
+To specify multiple TSDs, add additonal lines to the file. If you have a large number of TSDs, you may prefer to add a pattern. Assume that we have a large number of TSDs under `org/uimafit/type`, we can use the following pattern which recursively scans the package `org.uimafit.type` and all sub-packages for XML files and tries to load them as TSDs.
+
+{{{
+classpath*:org/uimafit/type/**/*.xml
+}}}
+
+Try to design your packages structure in a way that TSDs and JCas wrapper classes generated from them are separate from the rest of your code.
+
+If it is not possible or inconvenient to add the `types.txt` file, patterns can also be specified using a system property. Multiple patterns may be specified separated by semicolon:
+
+{{{
+org.uimafit.type.import_pattern=classpath*:org/uimafit/type/**/*.xml
+}}}
+
+= Using type auto-detection =
+
+The auto-detected type system can be obtained from the `TypeSystemDescriptionFactory`:
+
+{{{
+TypeSystemDescription tsd = TypeSystemDescriptionFactory.createTypeSystemDescription()
+}}}
+
+Popular factory methods also support auto-detection:
+
+{{{
+AnalysisEngine ae = createPrimitive(MyEngine.class);
+}}}
+
+= Multiple `META-INF/org.uimafit/types.txt` files =
+
+uimaFIT supports multiple `types.txt` files in the classpath (e.g. in differnt JARs).
+
+The `types.txt` files are located via Spring using the classpath search pattern:
+
+{{{
+TYPE_MANIFEST_PATTERN = "classpath*:META-INF/org.uimafit/types.txt"
+}}}
+
+This resolves to a list URLs pointing to ALL `types.txt`files. The resolved URLs are unique and will point either to a specific point in the file system or into a specific JAR. These URLs can be handled by the standard Java URL loading mechanism.
+
+Example:
+
+{{{
+jar:/path/to/syntax-types.jar!/META-INF/org.uimafit/types.txt
+jar:/path/to/token-types.jar!/META-INF/org.uimafit/types.txt
+}}}
+
+uimaFIT then reads all patters from all of these URLs and uses these to search the classpath again. The patterns now resolve to a list of URLs pointing to the individual type system XML descriptors. All of these URLs are collected in a set to avoid duplicate loading (for performance optimization - not strictly necessary because the UIMA type system merger can handle compatible duplicates). Then the descriptors are loaded into memory and merged using the standard UIMA type system merger (`CasCreationUtils.mergeTypeSystems()`).
+
+Example:
+
+{{{
+jar:/path/to/syntax-types.jar!/desc/types/Syntax.xml
+jar:/path/to/token-types.jar!/org/foobar/typesystems/Tokens.xml
+}}}
+Voilá, the result is a type system covering all types could be found in the classpath.
+
+I recommend
+ # to put type system descriptors into packages resembling a namespace you "own" and to use a package-scoped wildcard search
+{{{
+classpath*:org/uimafit/type/**/*.xml`
+}}}
+ # or when putting descriptors into a "well-known" package like `desc.type`, that `types.txt` file should explicitly list all type system descriptors instead of using a wildcard search or
+{{{
+classpath*:desc/type/Token.xml
+classpath*:desc/type/Syntax.xml
+}}}
+
+Method 1 should be preferred. Both methods can be mixed.
+
+= Performance note and caching =
+
+Currently uimaFIT evaluates the patterns for TSDs once and caches the locations, but not the actual merged type system description. A rescan can be forced using `TypeSystemDescriptionFactory.forceTypeDescriptorsScan()`. This may change in future.
+
+= Potential problems =
+
+The mechanism works fine. However, there are specific issues with Java in general that one should be aware of.
+
+== m2eclipse fails to copy descriptors to target/classes ==
+
+There seems to be a bug in m2eclipse that causes resources not always to be copied to `target/classes`. If UIMA complains about type definitions missing at runtime, try to clean/rebuild your project and carefully check the m2eclipse console in the console view for error messages that might cause m2eclipse to abort.
+
+== Class version conflicts ==
+
+A problem can occur if you end up having multiple incompatible versions of the same type system in the classpath. This is a general problem and not related to the auto-detection feature. It is the same as when you have incompatible version of a particular class (e.g. JCas wrapper or some third-party-library) in the classpath. The behavior of the Java Classloader is undefined in that case. The detection will do its best to try and load everything it can find, but the UIMA type system merger may barf or you may end up with undefined behavior at runtime because one of the class versions is used at random.
+
+== Classes and resources in the default package ==
+
+It is bad practice to place classes into the default (unnamed) package. In fact it is not possible to import classes from the default package in another class. Similarly it is a bad idea to put resources at the root of the classpath. The Spring documentation on resources [http://static.springsource.org/spring/docs/3.0.x/reference/resources.html#resources-app-ctx-wildcards-in-resource-paths explains this in detail].
+
+For this reason the `types.txt` resides in `/META-INF/org.uimafit` and I suggest that type system descriptors reside either in a proper package like `/org/foobar/typesystems/XXX.xml` or in `/desc/types/XXX.xml`.
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/UserSetup.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/UserSetup.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/UserSetup.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/UserSetup.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,19 @@
+The following instructions describe how to add uimaFIT to your project's classpath.
+
+= Maven Users =
+
+If you use Maven, then uimaFIT can be added to your project by simply adding uimaFIT as a project dependency by adding the following snippet of XML to your pom.xml file:
+
+{{{
+<dependency>
+ <groupId>org.uimafit</groupId>
+ <artifactId>uimafit</artifactId>
+ <version>(version-number-here)</version>
+</dependency>
+}}}
+
+Please see the project [http://uimafit.googlecode.com front page] for the current version number. uimaFIT distributions are hosted by Maven Central and so no repository needs to be added to your pom.xml file.
+
+= Non-maven Users =
+
+If you do not build with Maven, then download uimaFIT from the [http://code.google.com/p/uimafit/downloads/list downloads page]. The file name should be uimafit-(version)-plus-dependencies.zip. Download and unpack this file. The contents of the resulting upacked directory will contain a directory called "lib". Add all of the files in this directory to your classpath.
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/WorkingWithSofaViews.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/WorkingWithSofaViews.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/WorkingWithSofaViews.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/WorkingWithSofaViews.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,53 @@
+#summary Describes nuances of Sofas, CASes and CAS Views (in development)
+
+= Introduction =
+
+There are some use-cases for copying text and annotations between CASes, and views. There are various Annotators and classes that help deal with these situations available from the different projects:
+
+ * UIMA has the CasCopier that copies annotations between separate CASes, preserving view names.
+ * uimaFit has the ViewTextCopierAnnotator that copies text between views in the same CAS.
+ * Phillip Wetzler has progress on code that copies annotations documented in an issue at uimaFIT (46), and ClearTK (175). The code is attached to the uimaFIT issue. It needs test code.
+
+This page describes the problems and the tools. A glossary is included.
+
+
+= Details =
+
+==CASes, Views and Multi-Cas==
+
+In a simple UIMA annotator, a CAS is a structure that contains FeatureSets and the text or the Sofa, the subject of Annotation.
+
+A more involved annotator can work with a CAS that has more than one view on the CAS. Such an annotator uses a Multi-View CAS and is said to be sofa aware. A Multi-View CAS is a base CAS that contains views, but has no Sofa or indeces (or FeatureSets). Each view has a sofa, indeces and FeatureSets. The name sofa-aware comes from a variable in PrimitiveAnalysisEngine_impl (mSofaAware). An annotator written for single view CASes can be passed a Multi-CAS: it will always access the _InitialView because the surrounding AnalysisComponent picks it out and sends it to the AnalysisEngine. An annotator written for multi-view CAS, when passed a single-view CAS will only have the _InitialView available.
+
+An annotator's process(Jcas) method is applicable to both types of CASes (single and multi-view).
+
+An annotator is sofa-aware if it has been annotated as such with sofaCapabilities (see 6.2.3 of UTDG) . A sofa-aware annotator must get a view to work on since the top-level CAS has no sofa or featureSets. This is accomplished with jcas.getView("_InitialView"). A sofa-unaware annotator is always passed the _InitialView, the default.
+
+Any annotator, sofa-aware or sofa-unaware, can say jcas.getView("_InitialView") whether sofa-aware or not.
+
+Don't be lulled into a false sense of control when writing pipelines in uimaFIT. Just because you can pass a view to the process method of an annotator, does not mean that view will be available inside the process method. When anntoation engines are created in uimaFIT, like in UIMA, it is actually an analysis component that surrounds the analysis engine that is created. The process method of the component works to pass the right view to the analysis engine in case it is a cas-unaware or single-view component. The name sofa-aware comes from a a member variable, mSofaAware, in PrimitiveAnalysisEngine_impl. (personal experience)
+
+When copying annotations from one view to another, using clone() for eample, make sure the sofa feature set is changed to indicate the new view. (need details on exactly how to do this)
+
+
+==Related Tools==
+
+ * *CasCopier* use this to copy between distinct CASes
+ * *....ViewCreator* use this to safely create views
+ * *ViewTextCopierAnnotator* use this to copy text between views
+ * *foo* use this to copy annotations between views. (untested)
+
+----
+=Glossary=
+ * *CAS* Common Annotation/Analysis Structure, an array of FeatureSets, various indeces, and the DocumentText (Ch. 1 UTDG)
+ * *base CAS* a base CAS is the top-level CAS that contains views. It is different from a simple CAS that contains no views in that the base-CAS has no sofa or indexes.
+ * *JCas* A Java interface to a CAS (Ch. 1 UTDG)
+ * *FeatureStructure* Cas Feature Structure type, types of annotations described in a TypeSystem.
+ * *Feature*, attributes of a FeatureStructure (?)
+ * *Sofa Subject of Annotation* The Sofa is the text under consideration. The view is the Sofa and related annotations. They are often used interchangeably.
+ * *multi-View*, *multiple CAS views* UIMA supports a kind of CAS that hs more than one view. Each view has its own Sofa and related FeatureStructures. (Ch. 6 "Mutliple CAS Views of an Artifact" in the UTDG)
+ * *sofa-aware* A sofa-aware annotator can work with different views. A non sofa-aware, or sofa-unaware, annotator will always work on the default view, _InitialView. The name comes from a member variable in ______ in UIMA.
+ * *subview*
+
+
+UTDG: UIMA Tutorial and Developer's Guide
\ No newline at end of file
Added: uima/sandbox/trunk/uimaFIT/wiki/WritingTests.wiki
URL: http://svn.apache.org/viewvc/uima/sandbox/trunk/uimaFIT/wiki/WritingTests.wiki?rev=1420735&view=auto
==============================================================================
--- uima/sandbox/trunk/uimaFIT/wiki/WritingTests.wiki (added)
+++ uima/sandbox/trunk/uimaFIT/wiki/WritingTests.wiki Wed Dec 12 15:07:07 2012
@@ -0,0 +1,26 @@
+#summary helpful suggestions for writing tests
+
+*under construction*
+
+= Introduction =
+
+Writing tests without uimaFIT can be a laborious process that results in fragile tests that are ver verbose and break easily when code is refactored. This page demonstrates how you can write tests that are both concise and robust. Here's an outline of how you might create a test for a UIMA component _*without*_ uimaFIT:
+
+ # write a descriptor file that configures your component appropriately for the test. This requires a minimum of 30-50 lines of XML.
+ # begin a test with 5-10 lines of code that instantiate the e.g. analysis engine.
+ # run the analysis engine against some text and test the contents of the CAS.
+ # repeat steps 1-3 for your next test usually by copying the descriptor file, renaming it, and changing e.g. configuration parameters.
+
+If you have gone through the pain of creating tests like these and then decided you should refactor your code, then you know how tedious it is to maintain them.
+
+Instead of pasting variants of the setup code (see step 2) into other tests we began to create a library of utility methods that we could call which helped shorten our code. We extended these methods so that we could instantiate our components directly without a descriptor file. These utility methods became the initial core of uimaFIT.
+
+= Examples =
+
+ * There are a number of examples of unit tests in both the test suite for the uimafit project and the uimafit-examples project. In particular, there are some well-documented unit tests in the latter which can be found in [http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT-examples/src/test/java/org/uimafit/examples/tutorial/ex1/RoomNumberAnnotator1Test.java RoomNumberAnnotator1Test.java]
+ * You can improve your testing strategy by introducing a !TestBase class such as the one found in [http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT-examples/src/test/java/org/uimafit/examples/tutorial/ExamplesTestBase.java ExamplesTestBase.java]. This class is intended as a super class for your other test classes and sets up a JCas that is always ready to use along with a !TypeSystemDescription and a !TypePriorities. An example test that subclasses from !ExamplesTestBase is [http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT-examples/src/test/java/org/uimafit/examples/tutorial/ex1/RoomNumberAnnotator2Test.java RoomNumberAnnotator2Test.java]
+ * Most !AnalysisEngines that you want to test will generally be downstream of many other components that add annotations to the CAS. These annotations will likely need to be in the CAS so that a downstream !AnalysisEngine will do something sensible. This poses a problem for tests because it may be undesirable to set up and run an entire pipeline every time you want to test a downstream !AnalysisEngine. Furthermore, such tests can become fragile in the face of behavior changes to upstream components. For this reason, it can be advantageous to serialize a CAS as an XMI file and use this as a starting point rather than running an entire pipeline. An example of this approach can be found in [http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT-examples/src/test/java/org/uimafit/examples/xmi/XmiTest.java XmiTest.java].
+
+= Tips & Tricks =
+The package org.uimafit.testing provides some utility classes that can be handy when writing tests for UIMA components. You may find the following suggestions useful:
+ * add a org.uimafit.testing.factory.!TokenBuilder instance to your !TestBase class. An example of this can be found in [http://code.google.com/p/uimafit/source/browse/trunk/uimaFIT/src/test/java/org/uimafit/ComponentTestBase.java ComponentTestBase.java]. This makes it easy to add tokens and sentences to the CAS you are testing which is a common task for many tests.
\ No newline at end of file