| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" |
| "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[ |
| <!ENTITY imgroot "images/tools/tools.jcasgen/" > |
| <!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" > |
| %uimaents; |
| ]> |
| <!-- |
| 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. |
| --> |
| <chapter id="tools.uimafit.maven"> |
| <title>uimaFIT Maven Plugin</title> |
| |
| <para>uimaFIT dynamically generates UIMA component descriptions from annotations in the Java |
| source code. The uimaFIT Maven plugin provides the ability to automatically create such |
| annotations in already compiled classes and to automatically generate XML descriptors from the |
| annotated classes.</para> |
| <section> |
| <title>enhance goal</title> |
| <para>The goal enhance allows automatically augmenting compiled classes with uimaFIT |
| annotations. Information like vendor, copyright, or version can be obtained from the Maven |
| POM. Additionally, descriptions for parameters and components can be generated from Javadoc |
| comments. Existing annotations are not overwritten unless forced. </para> |
| <programlisting><plugin> |
| <groupId>org.apache.uima</groupId> |
| <artifactId>uimafit-maven-plugin</artifactId> |
| <version><?eval ${project.version}?></version> <!-- change to latest version --> |
| <configuration> |
| <!-- OPTIONAL --> |
| <!-- Override component description in generated descriptors. --> |
| <overrideComponentDescription>false</overrideComponentDescription> |
| |
| <!-- OPTIONAL --> |
| <!-- Override version in generated descriptors. --> |
| <overrideComponentVersion>false</overrideComponentVersion> |
| |
| <!-- OPTIONAL --> |
| <!-- Override vendor in generated descriptors. --> |
| <overrideComponentVendor>false</overrideComponentVendor> |
| |
| <!-- OPTIONAL --> |
| <!-- Override copyright in generated descriptors. --> |
| <overrideComponentCopyright>false</overrideComponentCopyright> |
| |
| <!-- OPTIONAL --> |
| <!-- Version to use in generated descriptors. --> |
| <componentVersion>${project.version}</componentVersion> |
| |
| <!-- OPTIONAL --> |
| <!-- Vendor to use in generated descriptors. --> |
| <componentVendor>Apache Foundation</componentVendor> |
| |
| <!-- OPTIONAL --> |
| <!-- Copyright to use in generated descriptors. --> |
| <componentCopyright>Apache Foundation 2013</componentCopyright> |
| |
| <!-- OPTIONAL --> |
| <!-- Source file encoding. --> |
| <encoding>${project.build.sourceEncoding}</encoding> |
| |
| <!-- OPTIONAL --> |
| <!-- Generate a report of missing meta data in |
| $project.build.directory/uimafit-missing-meta-data-report.txt --> |
| <generateMissingMetaDataReport>true</generateMissingMetaDataReport> |
| |
| <!-- OPTIONAL --> |
| <!-- Fail on missing meta data. This setting has no effect unless |
| generateMissingMetaDataReport is enabled. --> |
| <failOnMissingMetaData>false</failOnMissingMetaData> |
| |
| <!-- OPTIONAL --> |
| <!-- Constant name prefixes used for parameters and external resources, |
| e.g. "PARAM_". --> |
| <parameterNameConstantPrefixes> |
| <prefix>PARAM_<prefix/> |
| </parameterNameConstantPrefixes> |
| |
| <!-- OPTIONAL --> |
| <!-- Fail on missing meta data. This setting has no effect unless |
| generateMissingMetaDataReport is enabled. --> |
| <externalResourceNameConstantPrefixes> |
| <prefix>KEY_<prefix/> |
| <prefix>RES_<prefix/> |
| </externalResourceNameConstantPrefixes> |
| </configuration> |
| <executions> |
| <execution> |
| <id>default</id> |
| <phase>process-classes</phase> |
| <goals> |
| <goal>enhance</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin></programlisting> |
| <para>When generating descriptions for configuration parameters or external resources, the |
| plugin supports a common practice of placing the Javadoc on a constant field instead of the |
| parameter or external resource field. Per default, parameter name constants must be prefixed |
| with <code>PARAM_</code> and external resource key constants must be prefixed with <code>RES_ |
| </code>or <code>KEY_</code>.</para> |
| <programlisting>/** |
| * Enable or disable my feature. |
| */ |
| public static final String PARAM_ENABLE_FEATURE = "enableFeature"; |
| @ConfigurationParameter(name=PARAM_ENABLE_FEATURE) |
| private boolean enableFeature; |
| |
| /** |
| * My external resource. |
| */ |
| public static final String RES_MY_RESOURCE = "resource"; |
| @ExternalResource(key=RES_MY_RESOURCE) |
| private MyResource resource;</programlisting> |
| <para>By enabling <code>generateMissingMetaDataReport</code>, the build can be made to fail if |
| meta data such as parameter descriptions are missing. A report about the missing data is |
| generated in <filename>uimafit-missing-meta-data-report.txt</filename> in the project build |
| directory.</para> |
| </section> |
| <section> |
| <title>generate goal</title> |
| <para>The generate goal generates XML component descriptors for UIMA components. </para> |
| <programlisting><plugin> |
| <groupId>org.apache.uima</groupId> |
| <artifactId>uimafit-maven-plugin</artifactId> |
| <version><?eval ${project.version}?></version> <!-- change to latest version --> |
| <configuration> |
| <!-- OPTIONAL --> |
| <!-- Path where the generated resources are written. --> |
| <outputDirectory> |
| ${project.build.directory}/generated-sources/uimafit |
| </outputDirectory> |
| |
| <!-- OPTIONAL --> |
| <!-- Skip generation of META-INF/org.apache.uima.fit/components.txt --> |
| <skipComponentsManifest>false</skipComponentsManifest> |
| |
| <!-- OPTIONAL --> |
| <!-- Source file encoding. --> |
| <encoding>${project.build.sourceEncoding}</encoding> |
| </configuration> |
| <executions> |
| <execution> |
| <id>default</id> |
| <phase>process-classes</phase> |
| <goals> |
| <goal>generate</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin></programlisting> |
| <para>In addition to the XML descriptors, a manifest file is written to |
| <filename>META-INF/org.apache.uima.fit/components.txt</filename>. This file can be used to |
| conveniently locate the XML descriptors, which are written in the packages next to the classes |
| they |
| describe.<programlisting>classpath*:org/apache/uima/fit/examples/ExampleComponent.xml</programlisting></para> |
| <para>It is recommended to use both, the enhance and the generate goal. Both goals should be |
| specified in the same execution, first enhance, then generate:</para> |
| <programlisting><execution> |
| <id>default</id> |
| <phase>process-classes</phase> |
| <goals> |
| <goal>enhance</goal> |
| <goal>generate</goal> |
| </goals> |
| </execution></programlisting> |
| </section> |
| |
| </chapter> |