org.apache.uima.cas.impl

## Class CasCompare

- java.lang.Object
- - org.apache.uima.cas.impl.CasCompare

-     public class CasCompare
      extends Object

  Used by tests for Binary Compressed de/serialization code. Used by test app: XmiCompare. Compare 2 CASes, with perhaps different type systems. If the type systems are different, construct a type mapper and use that to selectively ignore types or features not in other type system The Mapper is from CAS1 -> CAS2 When computing the things to compare from CAS1, filter to remove feature structures not reachable via indexes or refs The index definitions are not compared. The indexes are used to locate the FSs to be compared. Reports are produced to System.out and System.err as a side effect System.out: status messages, type system comparison System.err: mismatch comparison information Usage: Use the static compareCASes method for default comparisons Use the multi-step approach for more complex comparisons: - Make an instance of this class, passing in the two CASes. - Set any additional configuration cc.compareAll(true) - continue comparing if mismatch found cc.compardIds(true) - compare ids (require ids to be ==) - Do any transformations needed on the CASes to account for known but allowed differences: -- These are transformations done on the CAS Feature Structures outside of this routine -- example: for certain type:feature string values, normalize to the same canonical value -- example: for certain type:feature string arrays, where the order is not important, sort them -- example: for certain type:feature FSArrays, where the order is not important, sort them --- using the sortFSArray method - Do any configuration to specify congruence sets for String values -- example: addStringCongruenceSet( type, feature, set-of-strings, -1 or int index if array) -- these are specific to type / feature specs -- range can be string or string array - if string array, the spec includes the index or -1 to indicate all indexes How it works Prepare arrays of all the FSs in the CAS - for each of 2 CASes to be compared - 2 arrays: -- all FSs in any index in any view -- the above, plus all FSs reachable via references -- but omit some types: only of interest when reached via ref, e.g. String/Int/Float/Boolean arrays The comparison of FSs is done, one FS at a time. - in order to determine the right FSs to compare with each other, the FSs for each CAS are sorted. The sort and the CAS compare both use a Compare method. - sorting skips items not in the other type system, including features - (only possible if comparing two CASes with different type systems, of course) Compare - used for two purposes: a) sorting FSs belonging to one CAS - can be used by caller to pre-sort any array values where the compare should be for set equality (in other words, ignore the order) b) comparing a FS in one CAS with a FS in the other CAS sort keys, in order: 1) type 2) if primitive array: sort based on - size - iterating thru all array items 3) All the features, considered in an order where non-refs are sorted before refs. comparing values: primitives - value comparison refs - compare the ref'd FS, while recording reference paths - stop when reach a compare point where the pair being compared has been seen - stop at any point if the two FSs compare unequal - at the stop point, if compare is equal, check the reference paths, and report unequal reference paths (different cycle lengths, or different total lengths, see the Prev data structure) Context information, reused across compares: prevCompare - if a particular pair of FSs compared equal -- used to speed up comparison -- used to stop recursive loops of references prev1, prev2 - reset for each top level FS compare - not reset for inner FS compares of fs-reference values) holds information about the reference path for chains of FS references

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CasCompare(CASImpl c1, CASImpl c2)` Make an instance of this class to set up a compare operation, and optionally use to configure the compare.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addStringCongruenceSet(String typeName, String featureBaseName, String[] set_of_strings_that_are_equivalent, int index)` Add a set of strings that should be considered equal when doing string comparisons.
    `void` | `applyToBoth(Consumer<CASImpl> c)` Many times some customation needs to be applied to both CASs being compared.
    `void` | `applyToTypeFeature(String typeName, String featureBaseName, org.apache.uima.internal.util.function.Consumer2<TOP,Feature> c)` Before comparing, you can adjust specific features of specific types, arbitrarily.
    `void` | `canonicalizeString(String typeName, String featureBaseName, String[] items_to_change, String canonical_value)` Before comparing, you can, for a selected type and feature which has a string value belonging to one of a set of strings, change the value to another (fixed) string which will of course compare equal.
    `void` | `compareAll(boolean v)` Continues the comparison after a miscompare (or not).
    `boolean` | `compareCASes()` This does the actual comparison operation of the previously specified CASes
    `static boolean` | `compareCASes(CASImpl c1, CASImpl c2)` Compare 2 CASes, with perhaps different type systems.
    `void` | `compareIds(boolean v)` Normally, compares ignore the Feature Structure ID when comparing.
    `static StringBuilder` | `compareNumberOfFSsByType(CAS cas1, CAS cas2)` Counts and compares the number of Feature Structures, by type, and generates a report
    `void` | `excludeCollectionsTypesFromIndexes()` The compare can find FeatureStructures to compare either from - being in some index in some view, or - being referenced through some chain which starts with the above.
    `void` | `excludeListTypesFromIndexes()` The compare can find FeatureStructures to compare either from - being in some index in some view, or - being referenced through some chain which starts with the above.
    `void` | `excludeRootTypesFromIndexes(Set<String> excluded_typeNames)` The compare can find FeatureStructures to compare either from - being in some index in some view, or - being referenced through some chain which starts with the above.
    `void` | `includeOnlyTheseTypesFromIndexes(List<String> includedTypeNames)` The compare can find FeatureStructures to compare either from - being in some index in some view, or - being referenced through some chain which starts with the above.
    `static void` | `showProgress()` call this to show progress of the compare - useful for long compares
    `List<Runnable>` | `sort_dedup_FSArray(String typeName, String featureBaseName)`
    `Runnable` | `sort_dedup_FSArray(TOP fs, Feature feat)` This is an optional pre-compare operation.
    `Runnable` | `sortFSArray(FSArray<?> fsArray)` This is an optional pre-compare operation.
    `List<Runnable>` | `sortFSArray(String typeName, String featureBaseName)`
    `Runnable` | `sortStringArray(StringArray stringArray)` This is an optional pre-compare operation.
    `List<Runnable>` | `sortStringArray(String typeName, String featureBaseName)`
    `List<Runnable>` | `type_feature_to_runnable(String typeName, String featureBaseName, BiFunction<TOP,Feature,Runnable> c)` Before comparing, you can create pending values for specific types / features, and return a list of runnables, which when run, plug in those pending values.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CasCompare

          public CasCompare(CASImpl c1,
                            CASImpl c2)

      Make an instance of this class to set up a compare operation, and optionally use to configure the compare.
      Parameters:
        `c1` - one CAS to compare
        `c2` - the other CAS to compare

  - ### Method Detail

    - #### compareCASes

          public static boolean compareCASes(CASImpl c1,
                                             CASImpl c2)

      Compare 2 CASes, with perhaps different type systems. - using default configuration.
      Parameters:
        `c1` - CAS to compare
        `c2` - CAS to compare
      Returns:
        true if equal (for types / features in both)

    - #### compareAll

          public void compareAll(boolean v)

      Continues the comparison after a miscompare (or not). This is useful when you want to see all of the miscompares.
      Parameters:
        `v` - defaults to false, set to true to continue the comparison after a miscompare

    - #### compareIds

          public void compareIds(boolean v)

      Normally, compares ignore the Feature Structure ID when comparing.
      Parameters:
        `v` - defaults to false, set to true to include the Feature Structure ID in the compare.

    - #### applyToBoth

          public void applyToBoth(Consumer<CASImpl> c)

      Many times some customation needs to be applied to both CASs being compared. This routine does that
      Parameters:
        `c` - the customization to be applied to both CASs

    - #### applyToTypeFeature

          public void applyToTypeFeature(String typeName,
                                         String featureBaseName,
                                         org.apache.uima.internal.util.function.Consumer2<TOP,Feature> c)

      Before comparing, you can adjust specific features of specific types, arbitrarily. This routine applies the adjustments to both CASs.
      Parameters:
        `typeName` - the fully qualified name of the type
        `featureBaseName` - the short feature name to adjust
        `c` - a function to do the adjustment

    - #### type_feature_to_runnable

          public List<Runnable> type_feature_to_runnable(String typeName,
                                                         String featureBaseName,
                                                         BiFunction<TOP,Feature,Runnable> c)

      Before comparing, you can create pending values for specific types / features, and return a list of runnables, which when run, plug in those pending values.
      Parameters:
        `typeName` - the type
        `featureBaseName` - the feature of the type
        `c` - the code to run for this type and feature
      Returns:
        a list of runnables, for both CASs

    - #### canonicalizeString

          public void canonicalizeString(String typeName,
                                         String featureBaseName,
                                         String[] items_to_change,
                                         String canonical_value)

      Before comparing, you can, for a selected type and feature which has a string value belonging to one of a set of strings, change the value to another (fixed) string which will of course compare equal. Use this to ignore selected string-valued features having particular values.
      Parameters:
        `typeName` - the fully qualified type name
        `featureBaseName` - the feature
        `items_to_change` - an array of strings to change if matched to one of these
        `canonical_value` - the new value

    - #### sortFSArray

          public List<Runnable> sortFSArray(String typeName,
                                            String featureBaseName)

    - #### sort_dedup_FSArray

          public List<Runnable> sort_dedup_FSArray(String typeName,
                                                   String featureBaseName)

    - #### sortStringArray

          public List<Runnable> sortStringArray(String typeName,
                                                String featureBaseName)

    - #### excludeRootTypesFromIndexes

          public void excludeRootTypesFromIndexes(Set<String> excluded_typeNames)

      The compare can find FeatureStructures to compare either from - being in some index in some view, or - being referenced through some chain which starts with the above. It sometimes helps to exclude miscompares of FeatureStructure like StringArrays which (for some reason) are indexed, in favor of finding these only via refs. You can exclude these from being found via indexes by setting types here. They could still be found via refs from other Feature Structures. Calling this disables any includeOnlyTheseTypesFromIndexes call;
      Parameters:
        `excluded_typeNames` - type names to exclude

    - #### excludeCollectionsTypesFromIndexes

          public void excludeCollectionsTypesFromIndexes()

      The compare can find FeatureStructures to compare either from - being in some index in some view, or - being referenced through some chain which starts with the above. It sometimes helps to exclude miscompares of FeatureStructure like StringArrays which (for some reason) are indexed, in favor of finding these only via refs. Call this to exclude the array types: boolean, byte, short, integer, long, float, double, string and fs arrays from being found via indexes. They could still be found via refs from other Feature Structures. Calling this disables any includeOnlyTheseTypesFromIndexes call;

    - #### excludeListTypesFromIndexes

          public void excludeListTypesFromIndexes()

      The compare can find FeatureStructures to compare either from - being in some index in some view, or - being referenced through some chain which starts with the above. It sometimes helps to exclude miscompares of List FeatureStructures like StringLists which (for some reason) are indexed, in favor of finding these only via refs. Call this to exclude the list types non-empty Float/Integer/String list elements from being found in the index. They could still be found via refs from other Feature Structures. Calling this disables any includeOnlyTheseTypesFromIndexes call;

    - #### includeOnlyTheseTypesFromIndexes

          public void includeOnlyTheseTypesFromIndexes(List<String> includedTypeNames)

      The compare can find FeatureStructures to compare either from - being in some index in some view, or - being referenced through some chain which starts with the above. It sometimes helps to exclude all types except for a few selected ones which are indexed, in favor of finding these only via refs. Calling this disables any excludeXXXTypesFromIndexes calls;
      Parameters:
        `includedTypeNames` - fully qualified type names to include when finding Feature Structures to compare via the indexes.

    - #### addStringCongruenceSet

          public void addStringCongruenceSet(String typeName,
                                             String featureBaseName,
                                             String[] set_of_strings_that_are_equivalent,
                                             int index)

      Add a set of strings that should be considered equal when doing string comparisons. This is conditioned on the typename and feature name
      Parameters:
        `typeName` - the fully qualified type name
        `featureBaseName` - the feature short name
        `set_of_strings_that_are_equivalent` - a set of strings that should compare equal, if testing the type / feature
        `index` - if the item being compared is a reference to a string array, which index should be compared. Use -1 if not applicable.

    - #### showProgress

          public static void showProgress()

      call this to show progress of the compare - useful for long compares

    - #### compareCASes

          public boolean compareCASes()

      This does the actual comparison operation of the previously specified CASes
      Returns:
        true if compare is OK

    - #### sortFSArray

          public Runnable sortFSArray(FSArray<?> fsArray)

      This is an optional pre-compare operation. Somtimes, when comparing FSArrays, the order of the elements is not significant, and the compare should be done ignoring order differences. This is accomplished by sorting the elements, before the compare is done, using this method. The sort order is not significant; it just needs to be the same order for otherwise equal FSArrays. Use this routine to accomplish the sort, on particular FSArrays you designate. Call it for each one you want to sort. During the sort, links are followed. The sorting is done in a clone of the array, and the original array is not updated. Instead, a Runnable is returned, which may be invoked later to update the original array with the sorted copy. This allows sorting to be done on the original item values (in case the links refer back to the originals)
      Parameters:
        `fsArray` - the array to be sorted
      Returns:
        a runnable, which (when invoked) updates the original array with the sorted result.

    - #### sort_dedup_FSArray

          public Runnable sort_dedup_FSArray(TOP fs,
                                             Feature feat)

      This is an optional pre-compare operation. It is identical to the method above, except that after sorting, it removes duplicates.
      Parameters:
        `fs` - the feature structure having the fsarray feature
        `feat` - the feature having the fsarray
      Returns:
        a runnable, which (when invoked) updates the original array with the sorted result.

    - #### sortStringArray

          public Runnable sortStringArray(StringArray stringArray)

      This is an optional pre-compare operation. Somtimes, when comparing StringArrays, the order of the elements is not significant, and the compare should be done ignoring order differences. This is accomplished by sorting the elements, before the compare is done, using this method. Use this routine to accomplish the sort, on particular StringArrays you designate. Call it for each one you want to sort. The sorting is done in a clone of the array, and the original array is not updated. Instead, a Runnable is returned, which may be invoked later to update the original array with the sorted copy. This allows sorting to be done while keeping the original values until a later time
      Parameters:
        `stringArray` - the array to be sorted
      Returns:
        null or a runnable, which (when invoked) updates the original array with the sorted result. callers should insure the runnable is garbage collected after use

    - #### compareNumberOfFSsByType

          public static StringBuilder compareNumberOfFSsByType(CAS cas1,
                                                               CAS cas2)

      Counts and compares the number of Feature Structures, by type, and generates a report
      Parameters:
        `cas1` - first CAS to compare
        `cas2` - second CAS to compare
      Returns:
        a StringBuilder with a report

Copyright © 2006–2022 The Apache Software Foundation. All rights reserved.