[uima-uimafit] 01/01: [UIMA-6021] Add selectSingleFS method to CasUtil

[re...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rec pushed a commit to branch feature/UIMA-6021-Add-selectSingleFS-method-to-CasUtil
in repository https://gitbox.apache.org/repos/asf/uima-uimafit.git

commit 7a1c78ca5c05e2311fde78d6a623bf079e7673ce
Author: Richard Eckart de Castilho <re...@apache.org>
AuthorDate: Wed Apr 10 19:43:44 2019 +0200

    [UIMA-6021] Add selectSingleFS method to CasUtil
    
    - Renamed the existing CasUtil.selectSingle to selectSingleFS
    - Added a new CasUtil.selectSingle returning AnnotationFS
    - Added a note about changed signatures to the migration guide
---
 .../java/org/apache/uima/fit/util/CasUtil.java     | 30 ++++++++++++++++++++--
 .../java/org/apache/uima/fit/util/JCasUtil.java    |  2 +-
 .../src/docbook/tools.uimafit.migration.xml        |  8 +++++-
 3 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/uimafit-core/src/main/java/org/apache/uima/fit/util/CasUtil.java b/uimafit-core/src/main/java/org/apache/uima/fit/util/CasUtil.java
index ea7520e..50beb52 100644
--- a/uimafit-core/src/main/java/org/apache/uima/fit/util/CasUtil.java
+++ b/uimafit-core/src/main/java/org/apache/uima/fit/util/CasUtil.java
@@ -943,7 +943,7 @@ public final class CasUtil {
   }
 
   /**
-   * Get the single instance of the specified type from the JCas.
+   * Get the single instance of the specified type from the CAS.
    * 
    * @param cas
    *          a CAS containing the annotation.
@@ -952,7 +952,33 @@ public final class CasUtil {
    * @return the single instance of the given type. throws IllegalArgumentException if not exactly
    *         one instance if the given type is present.
    */
-  public static FeatureStructure selectSingle(CAS cas, Type type) {
+  public static AnnotationFS selectSingle(CAS cas, Type type) {
+    FSIterator<AnnotationFS> iterator = cas.getAnnotationIndex(type).iterator();
+
+    if (!iterator.hasNext()) {
+      throw new IllegalArgumentException("CAS does not contain any [" + type.getName() + "]");
+    }
+
+    AnnotationFS result = iterator.next();
+
+    if (iterator.hasNext()) {
+      throw new IllegalArgumentException("CAS contains more than one [" + type.getName() + "]");
+    }
+
+    return result;
+  }
+  
+  /**
+   * Get the single instance of the specified type from the CAS.
+   * 
+   * @param cas
+   *          a CAS containing the annotation.
+   * @param type
+   *          a UIMA type.
+   * @return the single instance of the given type. throws IllegalArgumentException if not exactly
+   *         one instance if the given type is present.
+   */
+  public static FeatureStructure selectSingleFS(CAS cas, Type type) {
     FSIterator<FeatureStructure> iterator = cas.getIndexRepository().getAllIndexedFS(type);
 
     if (!iterator.hasNext()) {
diff --git a/uimafit-core/src/main/java/org/apache/uima/fit/util/JCasUtil.java b/uimafit-core/src/main/java/org/apache/uima/fit/util/JCasUtil.java
index 9d0cbb2..c2ffb95 100644
--- a/uimafit-core/src/main/java/org/apache/uima/fit/util/JCasUtil.java
+++ b/uimafit-core/src/main/java/org/apache/uima/fit/util/JCasUtil.java
@@ -590,7 +590,7 @@ public final class JCasUtil {
    */
   @SuppressWarnings("unchecked")
   public static <T extends TOP> T selectSingle(JCas jCas, Class<T> type) {
-    return (T) CasUtil.selectSingle(jCas.getCas(), getType(jCas, type));
+    return (T) CasUtil.selectSingleFS(jCas.getCas(), getType(jCas, type));
   }
 
   /**
diff --git a/uimafit-docbook/src/docbook/tools.uimafit.migration.xml b/uimafit-docbook/src/docbook/tools.uimafit.migration.xml
index 2f76442..9937753 100644
--- a/uimafit-docbook/src/docbook/tools.uimafit.migration.xml
+++ b/uimafit-docbook/src/docbook/tools.uimafit.migration.xml
@@ -28,8 +28,14 @@
       compatible with UIMA 2.x anyway, the legacy module was removed now.</para>
     </formalpara>
     <formalpara>
+      <title>Method signatures changed</title>
+      <para>Several method signatures have changed to be better usable with generics (e.g. in  
+      <literal>FSCollectionFactory</literal>) or to align better with the overall 
+      method naming scheme (e.g. in <literal>FSCollectionFactory</literal>).</para>
+    </formalpara>
+    <formalpara>
       <title>Version requirements</title>
-      <para>Depends on UIMA 3.0.0, Spring Framework 3.2.16 and Java 7.</para>
+      <para>Depends on UIMA 3.0.1, Spring Framework 4.3.22 and Java 8.</para>
     </formalpara>
   </section>
   <section>