You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by re...@apache.org on 2013/08/18 16:47:52 UTC
svn commit: r1515123 - in
/uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook:
tools.uimafit.book.xml tools.uimafit.maven.xml
Author: rec
Date: Sun Aug 18 14:47:52 2013
New Revision: 1515123
URL: http://svn.apache.org/r1515123
Log:
[UIMA-3172] Document uimaFIT maven plugin
Added:
uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.maven.xml (with props)
Modified:
uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.book.xml
Modified: uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.book.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.book.xml?rev=1515123&r1=1515122&r2=1515123&view=diff
==============================================================================
--- uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.book.xml (original)
+++ uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.book.xml Sun Aug 18 14:47:52 2013
@@ -40,4 +40,6 @@ under the License.
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.uimafit.externalresources.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.uimafit.typesystem.xml"/>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.uimafit.maven.xml"/>
</book>
Added: uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.maven.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.maven.xml?rev=1515123&view=auto
==============================================================================
--- uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.maven.xml (added)
+++ uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.maven.xml Sun Aug 18 14:47:52 2013
@@ -0,0 +1,181 @@
+<?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><literal>enhance</literal> goal</title>
+ <para>The goal enhance allows to automatically augment 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>2.0.0</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>
+ <parameterNameConstantPrefix>PARAM_<parameterNameConstantPrefix/>
+ </parameterNameConstantPrefixes>
+
+ <!-- OPTIONAL -->
+ <!-- Fail on missing meta data. This setting has no effect unless
+ generateMissingMetaDataReport is enabled. -->
+ <externalResourceNameConstantPrefixes>
+ <externalResourceNameConstantPrefix>KEY_<externalResourceNameConstantPrefix/>
+ <externalResourceNameConstantPrefix>RES_<externalResourceNameConstantPrefix/>
+ </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><literal>generate</literal> 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>2.0.0</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>
\ No newline at end of file
Propchange: uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.maven.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: uima/sandbox/uimafit/trunk/uimafit-docbook/src/docbook/tools.uimafit.maven.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml