blob: 886f746a684fc6c4e7996d9eb30419f94e70340d [file] [log] [blame]
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you 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
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
<chapter id="">
<title>Configuration Parameters</title>
<para>uimaFIT defines the <classname>@ConfigurationParameter</classname> annotation which can be
used to annotate the fields of an analysis engine or collection reader. The purpose of this
annotation is twofold:<itemizedlist>
<para>injection of parameters from the UIMA context into fields</para>
<para>declaration of parameter metadata (mandatory, default value, description) which can be
used to generate XML descriptors</para>
</itemizedlist>In a regular UIMA component, parameters need to be manually extracted from the
UIMA context, typically requiring a type cast. </para>
<programlisting format="linespecific">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(
<para>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.</para>
<para>With uimaFIT, all this information can be declared in the component using the
<classname>@ConfigurationParameter</classname> annotation.<table frame="all">
<title><classname>@ConfigurationParameter</classname> annotation</title>
<tgroup cols="3">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c3" colnum="3" colwidth="1.0*"/>
<entry>parameter name</entry>
<entry>name of annotated field</entry>
<entry>description of the parameter</entry>
<entry>whether a non-null value must be specified </entry>
<entry>the default value if no value is specified</entry>
<programlisting>class MyAnalysisEngine
extends {
* Directory to read the data from.
public static final String PARAM_SOURCE_DIRECTORY = "sourceDirectory";
@ConfigurationParameter(name=PARAM_SOURCE_DIRECTORY, defaultValue=".")
private File sourceDirectory;
<para>Note, that it is no longer necessary to implement the <methodname>initialize()</methodname>
method. uimaFIT takes care of locating the parameter <parameter>sourceDirectory</parameter> in
the UIMA context. It recognizes that the <classname>File</classname> class has a
<classname>String</classname> constructor and uses that to instantiate a new
<classname>File</classname> object from the parameter. A parameter is mandatory unless
specified otherwise. If a mandatory parameter is not specified in the context, an exception is
<para>The <parameter>defaultValue</parameter> is 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.</para>
<para>You can use the <emphasis>enhance</emphasis> goal of the uimaFIT Maven plugin to pick up
the parameter description from the JavaDoc and post it to the
<parameter>description</parameter> field of the
<classname>@ConfigurationParameter</classname> annotation. This should be preferred to
specifying the description explicitly as part of the annotation.</para>
<para>The parameter injection mechanism is implemented in the
<classname>ConfigurationParameterInitializer</classname> class. uimaFIT provides several base
classes that already come with an <methodname>initialize()</methodname> method using the
<para>The <classname>ConfigurationParameterInitializer</classname> can also be used with shared
<programlisting>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);
<para>Fields that can be annotated with the <classname>@ConfigurationParameter</classname>
annotation are any array or collection types of primitive types (<type>int</type>,
<type>boolean</type>, <type>float</type>, <type>double</type>), any enum types, any types that
define a constructor accepting a single <classname>String</classname> (e.g.
<classname>File</classname>), as well as, fields of the types <classname>Pattern</classname>
and <classname>Locale</classname>.</para>