uimafit-doc/src/main/asciidoc/tools.uimafit.configurationparameters.adoc

// 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
//
// 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.

[[_ugr.tools.uimafit.configurationparameters]]
= Configuration Parameters

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. 

[source,java]
----
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 [class]``@ConfigurationParameter`` annotation.

.`@ConfigurationParameter` annotation
[cols="1,1,1", frame="all", options="header"]
|===
| Parameter
| Description
| Default

|name
|parameter name
|name of annotated field

|description
|description of the parameter
|

|mandatory
|whether a non-null value must be specified 
|true

|defaultValue
|the default value if no value is specified
|
|===

[source,java]
----
class MyAnalysisEngine 
    extends org.apache.uima.fit.component.CasAnnotator_ImplBase {

  /**
   * Directory to read the data from.
   */
  public static final String PARAM_SOURCE_DIRECTORY = "sourceDirectory";
  @ConfigurationParameter(name=PARAM_SOURCE_DIRECTORY, defaultValue=".")
  private File sourceDirectory;
}
----

Note, that it is no longer necessary to implement the [method]``initialize()`` method.
uimaFIT takes care of locating the parameter [parameter]``sourceDirectory`` in the UIMA context.
It recognizes that the [class]``File`` class has a [class]``String`` constructor and uses that to instantiate a new [class]``File`` object from the parameter.
A parameter is mandatory unless specified otherwise.
If a mandatory parameter is not specified in the context, an exception is thrown.

The `defaultValue` 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.

[NOTE]
====
You can use the _enhance_ goal of the uimaFIT Maven plugin to pick up the parameter description from the JavaDoc and post it to the [parameter]``description`` field of the [class]``@ConfigurationParameter`` annotation.
This should be preferred to specifying the description explicitly as part of the annotation.
====

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:

[source,java]
----
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 (including if they are only typed via interfaces such as `List` or `Set`) of primitive types (`int`, `boolean`, `float`, `double`). Enum types, as well as, fields of the types `Charset`, `File`, `Locale`, `Pattern`, `URI`, and `URL` can also be used.
These can be initialized either using an object value (e.g. `StandardChartsets.UTF_8``) or a string value (e.g. `"UTF-8"`). Additionally it is possible to inject any fields of types that define a constructor accepting a single `String`.
These must be initialized from a string value.

Multi-valued parameters can be initialized from single values without having to wrap these into a container.