org.apache.uima.cas.impl

## Class FeatureValuePathImpl

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

- All Implemented Interfaces:
    FeatureValuePath

      public class FeatureValuePathImpl
      extends Object
      implements FeatureValuePath

  Contains CAS Type and Feature objects to represent a feature path of the form feature1/.../featureN. Each part that is enclosed within / is referred to as "path snippet" below. Also contains the necessary evaluation logic to yield the value of the feature path. For leaf snippets, the following "special features" are defined:
  - `coveredText()` can be accessed using `evaluateAsString`
  - `typeName()` can be accessed using `evaluateAsString`
  - `fsId()` can be accessed using `evaluateAsInt`. Its result can be used to retrieve an FS from the current LowLevel-CAS.
  - `uniqueId()` can be accessed using `evaluateAsInt`. Its result can be used to uniquely identify an FS for a document (even if the document is split over several CAS chunks)
  Handling of Arrays
  - A feature path may contain 0 or more features of type `FSArray`, but not as the last path snippet. The next path snippet must contain the fully qualified type name, example: `family/members[0]/somepackage.Person:name`
  - A feature path may also contain 0 or 1 feature of type `IntArray, StringArray, FloatArray`, but only as the last path snippet.
  For array-valued features, the following access operators are defined:
  - `[index]` returns the array entry at `index`
  - `[last]` returns the last entry of the array
  - `[]` returns an array of values. `[]` is only allowed 0 or 1 time in a feature path. If it is used, `getValueType` will return one of the following: `CAS.TYPE_NAME_STRING_ARRAY ,CAS.TYPE_NAME_INTEGER_ARRAY,CAS.TYPE_NAME_FLOAT_ARRAY`.
  If the feature path is defined directly for an `FSArray`, an actual feature name can be omitted, and only the array access operator can be used. Examples:

                                                                                  []/somepackage.Person:coveredText()
                                                                                   [last]/somepackage.Person:fsId()

  Usage
  - To create the feature path, use `FeaturePath.getFeaturePath`. Note that the client code needs to keep track of the "start type" of the feature path, that is, the type that contains the attribute used in the first snippet of the path.
  - At `typeSystemInit` of your component (CAS consumer or TAE), call `typeSystemInit` of the feature path.
  - Call `getValueType` to find out whether the feature path evaluates to a String, and int, a float, or their array counterparts.
  - Depending on the leaf type, call the appropriate `evaluateAs` methods

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `evaluate(int currentFS, LowLevelCAS cas)`
    `Float` | `evaluateAsFloat(int currentFS, LowLevelCAS cas)`
    `Float[]` | `evaluateAsFloatArray(int currentFS, LowLevelCAS cas)`
    `Integer` | `evaluateAsInt(int currentFS, LowLevelCAS cas)`
    `Integer[]` | `evaluateAsIntArray(int currentFS, LowLevelCAS cas)`
    `String` | `evaluateAsString(int currentFS, LowLevelCAS cas)` Evaluates each snippet of the feature path.
    `String[]` | `evaluateAsStringArray(int currentFS, LowLevelCAS cas)`
    `static FeatureValuePathImpl` | `getFeaturePath(String featurePath)`
    `int` | `getFSType()` Returns the type for which the last feature in the feature path is defined.
    `String` | `getValueType()` Returns the type that this feature path will evaluate to.
    `String` | `toString()`
    `void` | `typeSystemInit(int fsType, LowLevelTypeSystem ts)`

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

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

- - ### Method Detail

    - #### getFeaturePath

          public static FeatureValuePathImpl getFeaturePath(String featurePath)
                                                     throws CASRuntimeException

      Throws:
        `CASRuntimeException`

    - #### evaluate

          public Object evaluate(int currentFS,
                                 LowLevelCAS cas)

      Specified by:
        `evaluate` in interface `FeatureValuePath`

    - #### evaluateAsFloat

          public Float evaluateAsFloat(int currentFS,
                                       LowLevelCAS cas)

      Specified by:
        `evaluateAsFloat` in interface `FeatureValuePath`

    - #### evaluateAsFloatArray

          public Float[] evaluateAsFloatArray(int currentFS,
                                              LowLevelCAS cas)

      Specified by:
        `evaluateAsFloatArray` in interface `FeatureValuePath`

    - #### evaluateAsInt

          public Integer evaluateAsInt(int currentFS,
                                       LowLevelCAS cas)

      Specified by:
        `evaluateAsInt` in interface `FeatureValuePath`

    - #### evaluateAsIntArray

          public Integer[] evaluateAsIntArray(int currentFS,
                                              LowLevelCAS cas)

      Specified by:
        `evaluateAsIntArray` in interface `FeatureValuePath`

    - #### evaluateAsString

          public String evaluateAsString(int currentFS,
                                         LowLevelCAS cas)

      Evaluates each snippet of the feature path. Returns a String representation of the leaf value of the path. Returns `null` if some feature within the path is not set. If the leaf snippet is `COVERED_TEXT`, returns the covered text of `currentFS`.
      Specified by:
        `evaluateAsString` in interface `FeatureValuePath`
      Parameters:
        `currentFS` - the current Feature Structure
        `cas` - CAS
      Returns:
        A string representation of the leaf value.

    - #### evaluateAsStringArray

          public String[] evaluateAsStringArray(int currentFS,
                                                LowLevelCAS cas)

      Specified by:
        `evaluateAsStringArray` in interface `FeatureValuePath`

    - #### getFSType

          public int getFSType()

      Returns the type for which the last feature in the feature path is defined. Assumes that `typeSystemInit` has been called prior to this method.
      - For a feature path `feature1/.../featureN-1/featureN`, returns the type of featureN.
      - For a feature path `feature1/.../featureN-1/typeN:featureN`, returns the type code for typeN. (For example, if the range type of featureN-1 is FSList or FSArray)
      - For a feature path `feature1`, where feature1 is simple-valued, returns the type that was used in `typeSystemInit`
      Specified by:
        `getFSType` in interface `FeatureValuePath`
      Returns:
        the type for which the last feature in the feature path is defined.

    - #### getValueType

          public String getValueType()

      Returns the type that this feature path will evaluate to. Can be used to select the correct "evaluateAs" method.
      Specified by:
        `getValueType` in interface `FeatureValuePath`
      Returns:
        String the type that this feature path will evaluate to. Will be one of the following:
        - CAS.TYPE_NAME_STRING
        - CAS.TYPE_NAME_STRING_ARRAY
        - CAS.TYPE_NAME_INTEGER
        - CAS.TYPE_NAME_INTEGER_ARRAY
        - CAS.TYPE_NAME_FLOAT
        - CAS.TYPE_NAME_FLOAT_ARRAY

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### typeSystemInit

          public void typeSystemInit(int fsType,
                                     LowLevelTypeSystem ts)
                              throws CASRuntimeException

      Specified by:
        `typeSystemInit` in interface `FeatureValuePath`
      Throws:
        `CASRuntimeException`

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