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

Class 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.