[UIMA-5764] augment RELEASE_NOTES with more details of changes. Add API Compatibility check report. Update the pom assembly to avoid duplicate calls. Document new features in users guide.
git-svn-id: https://svn.apache.org/repos/asf/uima/addons/trunk@1829548 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/ConceptMapper/RELEASE_NOTES.html b/ConceptMapper/RELEASE_NOTES.html
new file mode 100644
index 0000000..a8a6c51
--- /dev/null
+++ b/ConceptMapper/RELEASE_NOTES.html
@@ -0,0 +1,127 @@
+ <!--
+ ***************************************************************
+ * 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.
+ ***************************************************************
+ -->
+<html>
+<head>
+ <title>Apache UIMA Addon: Concept Mapper: Release Notes</title>
+</head>
+<body>
+<h1>Apache UIMA (Unstructured Information Management Architecture) Addon Concept Mapper v2.10.2 Release Notes</h1>
+
+<h2>Contents</h2>
+<p>
+<a href="#what.is.uima">What is UIMA?</a><br/>
+<a href="#what.is.concept.mapper">What is the Concept Mapper</a><br>
+<a href="#major.changes">Major Changes in this Release</a><br/>
+<a href="#get.involved">How to Get Involved</a><br/>
+<a href="#report.issues">How to Report Issues</a><br/>
+<a href="#list.issues">List of JIRA Issues Fixed in this Release</a><br/>
+</p>
+
+<h2><a id="what.is.uima">1. What is UIMA?</a></h2>
+
+ <p>
+ Unstructured Information Management applications are
+ software systems that analyze large volumes of
+ unstructured information in order to discover knowledge
+ that is relevant to an end user. UIMA is a framework and
+ SDK for developing such applications. An example UIM
+ application might ingest plain text and identify
+ entities, such as persons, places, organizations; or
+ relations, such as works-for or located-at. UIMA enables
+ such an application to be decomposed into components,
+ for example "language identification" -> "language
+ specific segmentation" -> "sentence boundary
+ detection" -> "entity detection (person/place names
+ etc.)". Each component must implement interfaces defined
+ by the framework and must provide self-describing
+ metadata via XML descriptor files. The framework manages
+ these components and the data flow between them.
+ Components are written in Java or C++; the data that
+ flows between components is designed for efficient
+ mapping between these languages. UIMA additionally
+ provides capabilities to wrap components as network
+ services, and can scale to very large volumes by
+ replicating processing pipelines over a cluster of
+ networked nodes.
+ </p>
+ <p>
+ Apache UIMA is an Apache-licensed open source
+ implementation of the UIMA specification (that
+ specification is, in turn, being developed concurrently
+ by a technical committee within
+ <a href="http://www.oasis-open.org">OASIS</a>,
+ a standards organization). We invite and encourage you
+ to participate in both the implementation and
+ specification efforts.
+ </p>
+ <p>
+ UIMA is a component framework for analysing unstructured
+ content such as text, audio and video. It comprises an
+ SDK and tooling for composing and running analytic
+ components written in Java and C++, with some support
+ for Perl, Python and TCL.
+ </p>
+
+<h2><a id="what.is.uima">2. What is the Concept Mapper?</a></h2>
+
+ <p>ConceptMapper is a highly configurable,
+ high performance dictionary lookup tool,
+ implemented as a UIMA component.
+ <p>
+ Using one of several matching algorithms,
+ it maps entries in a dictionary onto input documents, producing UIMA annotations.
+ <p> The reference manual is
+ <a target="_blank" href="https://uima.apache.org/d/uima-addons-current/ConceptMapper/ConceptMapperAnnotatorUserGuide.html">here</a>.
+
+<h2><a id="major.changes">Major Changes in this Release</a></h2>
+<p>This release updates the Concept Mapper to use the current UIMA annotator APIs.
+It also adds the improvements:
+<ul>
+ <li>configures buffered I/O for compiled dictionaries</li>
+ <li>adds the ability to specify the tokenizer descriptor by using a reference to a descriptor in the classpath</li>
+ <li>supports creating the compiled dictionary as a side effect of loading a non-compiled dictionary</li>
+</ul>
+Finally, an API Change report is included, documenting the changes in the APIs between this version and
+version 2.3.1. Most users will be unaffected by this, because they do not use the APIs, but rather
+configure and run the ConceptMapper as a UIMA Annotator.
+</p>
+<p>Changes were also made to build specification to allow this project to be separately released.
+The binary build was changed to use the normal Maven conventions for naming the JAR artifact.</p>
+
+<h2><a id="get.involved">How to Get Involved</a></h2>
+<p>
+The Apache UIMA project really needs and appreciates any contributions,
+including documentation help, source code and feedback. If you are interested
+in contributing, please visit
+<a href="http://uima.apache.org/get-involved.html">
+ http://uima.apache.org/get-involved.html</a>.
+</p>
+
+<h2><a id="report.issues">How to Report Issues</a></h2>
+<p>
+The Apache UIMA project uses JIRA for issue tracking. Please report any
+issues you find at
+<a href="http://issues.apache.org/jira/browse/uima">http://issues.apache.org/jira/browse/uima</a>
+</p>
+
+
+</body>
+</html>
\ No newline at end of file
diff --git a/ConceptMapper/marker-file-identifying-api-compatibility-check b/ConceptMapper/marker-file-identifying-api-compatibility-check
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/ConceptMapper/marker-file-identifying-api-compatibility-check
diff --git a/ConceptMapper/pom.xml b/ConceptMapper/pom.xml
index db3bcee..056fede 100644
--- a/ConceptMapper/pom.xml
+++ b/ConceptMapper/pom.xml
@@ -28,7 +28,7 @@
</parent>
<artifactId>ConceptMapper</artifactId>
- <version>2.10.3-SNAPSHOT</version>
+ <version>2.10.2-SNAPSHOT</version>
<name>Apache UIMA Annotator: ${project.artifactId}</name>
<description>Extracts concepts from a CAS</description>
<url>${uimaWebsiteUrl}</url>
@@ -199,4 +199,117 @@
</pluginManagement>
</build>
+
+ <profiles>
+ <profile>
+ <id>apache-release</id>
+
+ <build>
+ <!-- Run jira report -->
+ <!-- depends on having -DjiraVersion set -->
+ <plugins>
+ <plugin>
+ <artifactId>maven-changes-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>default-cli</id>
+ <configuration>
+ <fixVersionIds>${jiraVersion}</fixVersionIds>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+
+ <!-- ********** Backwards compatibility report generation profile ************** -->
+ <profile>
+ <id>enforce-compatibility</id>
+ <activation>
+ <file>
+ <exists>marker-file-identifying-api-compatibility-check</exists>
+ </file>
+ </activation>
+ <build>
+
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.rat</groupId>
+ <artifactId>apache-rat-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>default-cli</id>
+ <configuration>
+ <excludes combine.children="append">
+ <exclude>**/api-change-report/**/*.*</exclude>
+ </excludes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+
+ <plugins>
+ <!-- https://siom79.github.io/japicmp/MavenPlugin.html -->
+ <plugin>
+ <groupId>com.github.siom79.japicmp</groupId>
+ <artifactId>japicmp-maven-plugin</artifactId>
+ <version>0.9.4</version>
+ <configuration>
+ <oldVersion>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${api_check_oldVersion}</version>
+ </dependency>
+ </oldVersion>
+ <parameter>
+ <onlyModified>true</onlyModified>
+ <!-- filter out classes with impl in their package or class name -->
+ <postAnalysisScript>${project.basedir}/src/main/groovy/api-report.groovy</postAnalysisScript>
+ </parameter>
+ </configuration>
+ <executions>
+ <execution>
+ <phase>verify</phase>
+ <goals>
+ <goal>cmp</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+
+ <!-- This copy is to have the api change report included in the source distribution -->
+ <plugin>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy-API-change-report</id>
+ <phase>install</phase> <!-- must follow verify -->
+ <goals><goal>run</goal></goals>
+ <configuration>
+ <target>
+ <taskdef name="if" classname="net.sf.antcontrib.logic.IfTask" />
+ <if>
+ <available file="${project.build.directory}/japicmp/" />
+ <then>
+ <copy toDir="${basedir}/api-change-report">
+ <fileset dir="${project.build.directory}/japicmp" />
+ </copy>
+ </then>
+ </if>
+ </target>
+ </configuration>
+ </execution>
+ </executions>
+
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+
+ </profiles>
</project>
diff --git a/ConceptMapper/src/docbook/ConceptMapperAnnotatorUserGuide.xml b/ConceptMapper/src/docbook/ConceptMapperAnnotatorUserGuide.xml
index 9d10efe..eb56b1b 100644
--- a/ConceptMapper/src/docbook/ConceptMapperAnnotatorUserGuide.xml
+++ b/ConceptMapper/src/docbook/ConceptMapperAnnotatorUserGuide.xml
@@ -29,7 +29,8 @@
<preface id="intro">
<title>Introduction</title>
<para>
- ConceptMapper is a highly configurable, high performance dictionary lookup tool, implemented as a UIMA (Unstructured Information Management Architecture) component. Using one of several matching algorithms, it maps entries in a dictionary onto input documents, producing UIMA annotations.
+ ConceptMapper is a highly configurable, high performance dictionary lookup tool, implemented as a UIMA (Unstructured Information Management Architecture) component.
+ Using one of several matching algorithms, it maps entries in a dictionary onto input documents, producing UIMA annotations.
</para>
</preface>
<chapter id="usingcm">
@@ -104,17 +105,33 @@
this is partially mitigated by the fact that the dictionary is implemented as a UIMA shared resource
(see <xref linkend="ConceptMapper.res.dictionaryfile"/>).
This means that multiple annotators, such as multiple instances of ConceptMapper that are set up using different parameters,
- can all access it without having to load it more than once.
+ can all access it without having to load it more than once.
+ </para>
+ <para>
The dictionary loader is specified in the external resource section of the descriptor,
and is expected to implement the interface <interfacename>org.apache.uima.conceptMapper.support.dictionaryResource.DictionaryResource</interfacename>.
- Two implementations are included in the distribution,
- <classname>org.apache.uima.conceptMapper.support.dictionaryResource.DictionaryResource_impl</classname>,
- the standard implementation, which loads an XML version of a dictionary,
- and <classname>org.apache.uima.conceptMapper.support.dictionaryResource.CompiledDictionaryResource_impl</classname>
- which loads a pre-compiled version, for faster loading.
- The compiler is supplied as <classname>org.apache.uima.conceptMapper.dictionaryCompiler.CompileDictionary</classname>,
- which takes two arguments, a ConceptMapper analysis engine descriptor that loads the dictionary using the standard dictionary loader,
- and the name of the output file into which to write the compiled dictionary.
+ Two implementations are included in the distribution.
+ <itemizedlist>
+ <listitem>
+ <para><classname>org.apache.uima.conceptMapper.support.dictionaryResource.DictionaryResource_impl</classname>,
+ the standard implementation, which loads an XML version of a dictionary.
+ </para>
+ </listitem>
+ <listitem>
+ <para><classname>org.apache.uima.conceptMapper.support.dictionaryResource.CompiledDictionaryResource_impl</classname>
+ which loads a pre-compiled version, for faster loading.
+ </para>
+ <para>The compiler is supplied as <classname>org.apache.uima.conceptMapper.dictionaryCompiler.CompileDictionary</classname>,
+ which takes two arguments, a ConceptMapper analysis engine descriptor that loads the dictionary using the standard dictionary loader,
+ and the name of the output file into which to write the compiled dictionary.
+ </para>
+ <para>A compiled version of the dictionary can optionally be created while loading the non-compiled version, by
+ specifying the Java property <code>uima.conceptmapper.compiled_dictionary_directory</code>,
+ giving it the value of a path to a writable directory.
+ </para>
+ </listitem>
+ </itemizedlist>
+
</para>
</section>
<section id="tokenizer">
@@ -255,6 +272,7 @@
<varname id="ConceptMapper.param.tokenizerdescriptorpath" xreflabel="TokenizerDescriptorPath">TokenizerDescriptorPath</varname>: <emphasis>[Required]</emphasis> <type>String</type>
</para>
<para>Path to tokenizer Analysis Engine descriptor, which is used to tokenize dictionary entries.
+ This path may be a reference to a file in the file system, or a reference to an item in the classpath.
</para>
</listitem>
<listitem>
diff --git a/ConceptMapper/src/main/groovy/api-report.groovy b/ConceptMapper/src/main/groovy/api-report.groovy
new file mode 100644
index 0000000..8809e6c
--- /dev/null
+++ b/ConceptMapper/src/main/groovy/api-report.groovy
@@ -0,0 +1,27 @@
+/*
+ * 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.
+ */
+ def it = jApiClasses.iterator()
+ while (it.hasNext()) {
+ def jApiClass = it.next()
+ def fqn = jApiClass.getFullyQualifiedName()
+ if (fqn.contains("impl")) {
+ it.remove()
+ }
+ }
+ return jApiClasses
\ No newline at end of file
diff --git a/ConceptMapper/uima-single-project-bin2.xml b/ConceptMapper/uima-single-project-bin2.xml
new file mode 100644
index 0000000..98bdeae
--- /dev/null
+++ b/ConceptMapper/uima-single-project-bin2.xml
@@ -0,0 +1,119 @@
+<!--
+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.
+-->
+
+<assembly>
+ <id>bin</id>
+ <formats>
+ <format>tar.gz</format>
+ <format>zip</format>
+ </formats>
+
+ <includeBaseDirectory>true</includeBaseDirectory>
+
+ <baseDirectory>/apache-uima-addon-conceptmapper</baseDirectory>
+
+
+ <dependencySets>
+ <dependencySet>
+ <includes>
+ <include>org.apache.uima:ConceptMapper</include>
+ </includes>
+ <unpack>false</unpack>
+ <outputDirectory>lib</outputDirectory>
+ <useProjectArtifact>false</useProjectArtifact>
+ <fileMode>644</fileMode>
+ <directoryMode>755</directoryMode>
+ </dependencySet>
+ </dependencySets>
+
+ <!-- Add other files - scripts, documentation, examples -->
+ <fileSets>
+
+ <!-- copy standard top level files -->
+ <fileSet>
+ <directory>.</directory>
+ <outputDirectory></outputDirectory>
+ <fileMode>644</fileMode>
+ <directoryMode>755</directoryMode>
+ <includes>
+ <include>README*</include>
+ <include>readme*</include>
+ <include>RELEASE_NOTES*</include>
+ <include>Release-Notes*</include>
+ <include>issuesFixed/**</include>
+ </includes>
+ </fileSet>
+
+ <fileSet>
+ <directory>target/site/apidocs</directory>
+ <outputDirectory>docs/d/api</outputDirectory>
+ <excludes>
+ <exclude>options</exclude>
+ <exclude>packages</exclude>
+ <exclude>files</exclude>
+ <exclude>argfile</exclude>
+ </excludes>
+ <fileMode>444</fileMode>
+ <directoryMode>755</directoryMode>
+ </fileSet>
+
+ <!-- docbooks -->
+ <fileSet>
+ <directory>./target/site/</directory>
+ <outputDirectory>docs</outputDirectory>
+ <fileMode>644</fileMode>
+ <directoryMode>755</directoryMode>
+ </fileSet>
+
+ <!-- Copy the API Change reports -->
+ <fileSet>
+ <directory>api-change-report</directory>
+ <outputDirectory>api-change-report</outputDirectory>
+ <fileMode>644</fileMode>
+ <directoryMode>755</directoryMode>
+ </fileSet>
+ </fileSets>
+
+ <files>
+ <!-- copy bin distr license and notice -->
+ <file>
+ <source>LICENSE.txt</source>
+ <outputDirectory></outputDirectory>
+ <fileMode>644</fileMode>
+ </file>
+ <file>
+ <source>NOTICE.txt</source>
+ <outputDirectory></outputDirectory>
+ <fileMode>644</fileMode>
+ </file>
+
+ <file>
+ <source>readme.txt</source>
+ <outputDirectory></outputDirectory>
+ <fileMode>644</fileMode>
+ </file>
+
+ <file>
+ <source>RELEASE_NOTES.html</source>
+ <outputDirectory></outputDirectory>
+ <fileMode>644</fileMode>
+ </file>
+
+ </files>
+</assembly>
\ No newline at end of file
