Package com.tibco.patterns.learn.api.feature

## Class FeatureQuery

- java.lang.Object
- - com.tibco.patterns.learn.api.feature.FeatureQuery

-     public final class FeatureQuery
      extends java.lang.Object

  Supports a feature query that can contain all types of features. Querylets are stored within objects of the Feature class and its descendants. When calculating feature scores, FeatureQuery constructs and returns a NetricsQuery object for each feature.

  An object of this class is typically creted by and returned from ModelSettings. It can also be created independently for testing purposes.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FeatureQuery​(java.util.List<java.lang.String> allFields, FeatureListener listener)` | Creates an empty feature query.
    `FeatureQuery​(java.util.List<java.lang.String> allFields, com.tibco.patterns.learn.jaxb.model.Model.Features xmlFeatureQuery, FeatureListener listener)` | Creates the feature query and all querylets read from the xmlFeatures.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addFeature​(Feature<?> newFeature)` | Adds the newFeature (of any type) to the feature query.
    `GenericFeature` | `addFeature​(java.lang.String name, AbstractQlt<?> qlt)` | Creates a new generic feature and adds it to the feature query.
    `void` | `clear()` | Deletes all features and the list of used thesauri.
    `void` | `generateXml​(com.tibco.patterns.learn.jaxb.model.Model.Features xmlFeatureQuery)` | Fills the given XML type with the user-defined features and thesauri that are stored in this FeatureQuery.
    `Feature<?>` | `getFeature​(int index)` |
    `Feature<?>` | `getFeature​(java.lang.String name)` | Gets the feature by name.
    `java.util.Set<java.lang.String>` | `getFieldNames()` |
    `com.netrics.likeit.NetricsQuery[]` | `getNetricsQlts​(java.lang.String[] values)` | Constructs NetricsQuery querylets from all querylets in feature query.
    `int` | `getNFeatures()` |
    `int` | `getNQlts()` | Returns the total number of querylets in all features
    `java.util.List<java.lang.String>` | `getQltNames()` |
    `java.util.List<AbstractQlt<?>>` | `getQlts()` |
    `java.util.Set<Thesaurus>` | `getThesauri()` |
    `Thesaurus` | `getThesaurus​(java.lang.String name)` |
    `java.util.Set<java.lang.String>` | `getThesaurusNames()` |
    `java.lang.String` | `getXmlString()` | Generates XML with all features (similar to the features element in model.xml) and returns it as string.
    `boolean` | `otherFeatureHasThesWithDifferentType​(Thesaurus thes, Feature<?> feature)` | Checks for thesaurus type conflicts.
    `void` | `removeFeature​(int index)` | Deletes the feature with the given index.
    `void` | `removeThesauri​(Feature<?> f)` | Removes all thesauri from the given feature and from the list of thesauri used by this feature query (if needed).
    `void` | `removeThesaurus​(TextQlt<?> qlt)` | Removes the thesaurus (if assigned) from the given querylet.
    `void` | `saveJavaCode​(java.nio.file.Path outputDir, java.lang.String javaClassName, java.lang.String methodName)` | Saves Java source code for the stored feature query.
    `void` | `saveXmlSearch​(java.nio.file.Path xmlFile)` | Exports all features to an XML file according to Patterns Search XML schema.
    `void` | `setFeature​(int index, Feature<?> newFeature)` | Replaces the existing feature with the new one.
    `void` | `setThesaurus​(Thesaurus thes, double weight, Feature<?> f)` | Sets (or replaces) thesaurus in the given feature and adds it to the list of thesauri used by this feature query (if not yet present).
    `void` | `setThesaurus​(Thesaurus thes, double weight, TextQlt<?> qlt)` | Sets (or replaces) thesaurus in the given querylet and adds it to the list of thesauri used by this feature query (if not yet present).
    `void` | `setThesPrefix​(java.lang.String uuid)` | Assigns the given identifier (UUID) that is used in all thesauri names on the server.
    `java.lang.String` | `toString()` |
    `void` | `upgradeXmlVersion​(int fromVersion)` | v.4: build list of thesauri with default thesaurus type using all thesauri in querylets.

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

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

- - ### Constructor Detail

    - #### FeatureQuery

          public FeatureQuery​(java.util.List<java.lang.String> allFields,
                              FeatureListener listener)

      Creates an empty feature query.
      Parameters:
        `allFields` - - the name of each field in the table
        `listener` - - object that gets notifications before any feature change. Use null when such notifications are not needed.

    - #### FeatureQuery

          public FeatureQuery​(java.util.List<java.lang.String> allFields,
                              com.tibco.patterns.learn.jaxb.model.Model.Features xmlFeatureQuery,
                              FeatureListener listener)
                       throws javax.xml.bind.JAXBException

      Creates the feature query and all querylets read from the xmlFeatures. To be used with Learn UI projects.
      Parameters:
        `allFields` - - the name of each field in the table
        `xmlFeatureQuery` - - features and thesauri read from model.xml file
        `listener` - - object that gets notifications before any feature change. Use null when such notifications are not needed.
      Throws:
        `javax.xml.bind.JAXBException` - if thesauri with the same name but different type are stored in XML or a stored feature is invalid.

  - ### Method Detail

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### generateXml

          public void generateXml​(com.tibco.patterns.learn.jaxb.model.Model.Features xmlFeatureQuery)

      Fills the given XML type with the user-defined features and thesauri that are stored in this FeatureQuery. To be used with Learn UI projects.
      Parameters:
        `xmlFeatureQuery` - - XML element for feature query. Part of model.xml file.

    - #### getXmlString

          public java.lang.String getXmlString()
                                        throws javax.xml.bind.JAXBException

      Generates XML with all features (similar to the features element in model.xml) and returns it as string. Used for saving model metadata.
      Returns:
        an XML string that contains all features.
      Throws:
        `javax.xml.bind.JAXBException` - on unexpected JAXB errors.

    - #### saveXmlSearch

          public void saveXmlSearch​(java.nio.file.Path xmlFile)
                             throws javax.xml.bind.JAXBException

      Exports all features to an XML file according to Patterns Search XML schema. The querylets in the XML file are combined with an AND score combiner.
      Throws:
        `javax.xml.bind.JAXBException`

    - #### addFeature

          public void addFeature​(Feature<?> newFeature)

      Adds the newFeature (of any type) to the feature query.
      Parameters:
        `newFeature` - - the new feature to be added. Not null.
      Throws:
        `java.lang.IllegalArgumentException` - if fields in any querylet are incorrect, or if feature query is already assigned to a querylet.

    - #### addFeature

          public GenericFeature addFeature​(java.lang.String name,
                                           AbstractQlt<?> qlt)

      Creates a new generic feature and adds it to the feature query.
      Parameters:
        `name` - - the name of the new feature.
        `qlt` - - querylet to be used in the new generic feature.
      Returns:
        the new feature that was added.
      Throws:
        `java.lang.IllegalArgumentException` - if fields in the querylet are incorrect, or if feature query is already assigned to the querylet.

    - #### setFeature

          public void setFeature​(int index,
                                 Feature<?> newFeature)

      Replaces the existing feature with the new one. The new feature can be of any type. Removes thesauri used by the old feature from the list of thesauri (if no longer used).
      Parameters:
        `index` - - the index if the existing feature in the list of features.
        `newFeature` - - the new feature. Not null. It must not be assigned to any feature query yet (unless it is already assigned to this index position, then the method does nothing).
      Throws:
        `java.lang.IllegalArgumentException` - if fields in any querylet are incorrect, or if feature query is already assigned to a querylet.

    - #### getNFeatures

          public int getNFeatures()

      Returns:
        the number of user-defined features in the feature query.

    - #### getFeature

          public Feature<?> getFeature​(int index)

      Parameters:
        `index` - - the index if the existing feature in the list of features.
      Returns:
        internal reference to the feature with the given index.

    - #### getFeature

          public Feature<?> getFeature​(java.lang.String name)

      Gets the feature by name. If several features have the same name, gets the first feature with that name.
      Returns:
        internal reference to the first feature with the given name.
      Throws:
        `java.lang.IllegalArgumentException` - if feature with the given name is not found.

    - #### removeFeature

          public void removeFeature​(int index)

      Deletes the feature with the given index. Removes thesauri used by the old feature from the list of thesauri (if no longer used).
      Parameters:
        `index` - - the index if the existing feature in the list of features.

    - #### clear

          public void clear()

      Deletes all features and the list of used thesauri.

    - #### getNQlts

          public int getNQlts()

      Returns the total number of querylets in all features

    - #### getQlts

          public java.util.List<AbstractQlt<?>> getQlts()

      Returns:
        all querylets in all features of this feature query.

    - #### getQltNames

          public java.util.List<java.lang.String> getQltNames()

      Returns:
        names of all querylets in all features of this feature query.

    - #### getFieldNames

          public java.util.Set<java.lang.String> getFieldNames()

      Returns:
        a set of field names (without repetitions) that are used in all querylets in this feature query.

    - #### upgradeXmlVersion

          public void upgradeXmlVersion​(int fromVersion)

      v.4: build list of thesauri with default thesaurus type using all thesauri in querylets.

    - #### otherFeatureHasThesWithDifferentType

          public boolean otherFeatureHasThesWithDifferentType​(Thesaurus thes,
                                                              Feature<?> feature)

      Checks for thesaurus type conflicts.
      Parameters:
        `feature` - - one of the features in this feature query that the thesaurus is being assigned to. If null, returns true if any feature has this thesaurus with a different type.
      Returns:
        true if a feature other than the given feature has thesaurus with the given name, but a different thesaurus type.

    - #### setThesaurus

          public void setThesaurus​(Thesaurus thes,
                                   double weight,
                                   TextQlt<?> qlt)

      Sets (or replaces) thesaurus in the given querylet and adds it to the list of thesauri used by this feature query (if not yet present).
      Parameters:
        `thes` - - thesaurus to be assigned. Not null.
        `qlt` - - the querylet. Not null, must be already assigned to this feature query.
      Throws:
        `java.lang.IllegalArgumentException` - if thesaurus with the same name but different type already exists, or if the given querylet is not assigned to this feature query.

    - #### setThesaurus

          public void setThesaurus​(Thesaurus thes,
                                   double weight,
                                   Feature<?> f)

      Sets (or replaces) thesaurus in the given feature and adds it to the list of thesauri used by this feature query (if not yet present).
      Parameters:
        `thes` - - thesaurus to be assigned. Not null.
        `f` - - a Simple, Cognate or Person Name feature. Not null. must be already assigned to this feature query.
      Throws:
        `java.lang.IllegalArgumentException` - if thesaurus with the same name but different type already exists, or if the given feature is not assigned to this feature query.

    - #### removeThesaurus

          public void removeThesaurus​(TextQlt<?> qlt)

      Removes the thesaurus (if assigned) from the given querylet. If no other querylets use the thesaurus, removes it from the list of thesauri used by this feature query.
      Parameters:
        `qlt` - - the querylet. Not null, must be already assigned to this feature query.
      Throws:
        `java.lang.IllegalArgumentException` - if the querylet is not assigned to this feature query.

    - #### removeThesauri

          public void removeThesauri​(Feature<?> f)

      Removes all thesauri from the given feature and from the list of thesauri used by this feature query (if needed).
      Throws:
        `java.lang.IllegalArgumentException` - if the feature is not assigned to this feature query.

    - #### getThesaurusNames

          public java.util.Set<java.lang.String> getThesaurusNames()

      Returns:
        a set of thesaurus names (without repetitions) that are used in this feature query. The thesaurus names do not include UUID.

    - #### getThesaurus

          public Thesaurus getThesaurus​(java.lang.String name)

      Returns:
        the thesaurus with the given name, or null if such thesaurus is not stored.

    - #### getThesauri

          public java.util.Set<Thesaurus> getThesauri()

      Returns:
        a set of thesauri that are used in this feature query. The thesaurus names do not include UUID.

    - #### setThesPrefix

          public void setThesPrefix​(java.lang.String uuid)

      Assigns the given identifier (UUID) that is used in all thesauri names on the server. It is set by each new RecPairScorer when all thesauri are uploaded to server.
      Parameters:
        `uuid` - - the unique identifier to be used for all thesauri names on server. Not null.
      Throws:
        `java.lang.IllegalArgumentException` - if thesPrefix is null.

    - #### getNetricsQlts

          public com.netrics.likeit.NetricsQuery[] getNetricsQlts​(java.lang.String[] values)

      Constructs NetricsQuery querylets from all querylets in feature query. Used when calculating feature scores for a specific record pair.
      Parameters:
        `values` - - the values of all non-key fields in the query record. Not null.
      Returns:
        a querylet for each feature. Each querylet uses symmetric scoring (if supported).
      Throws:
        `java.lang.IllegalArgumentException` - if number of values does not match number of all fields.

    - #### saveJavaCode

          public void saveJavaCode​(java.nio.file.Path outputDir,
                                   java.lang.String javaClassName,
                                   java.lang.String methodName)
                            throws java.io.IOException

      Saves Java source code for the stored feature query. If output Java file exists, this method overwrites it.
      Parameters:
        `outputDir` - - the directory where Java source file is saved. Not null.
        `javaClassName` - - name of the Java class in the exported source. May include package name. If package is not included, the default package is used. Not null.
        `methodName` - - the name of the method that returns NetricsQuery in the exported Java source. Not null.
      Throws:
        `java.io.IOException` - if writing to file fails.
        `java.lang.IllegalArgumentException` - if javaClassName starts or ends with a period.