Package com.netrics.likeit

Class ANetricsQueryBuilder

  • public abstract class ANetricsQueryBuilder
extends java.lang.Object
    Abstract class for building a NetricsQuery object.

    This provides a generic interface for classes that build a NetricsQuery object from a set of input field values. It allows for updating NetricsSearchOpts and NetricsSearchCfg objects, remapping field names used in input and output independently, and remapping names of subsidiary objects such as thesauri, Learn models, and querylet names. Implementations for most methods are provided, a derived class needs to implement only the basic query generation method and a method to return the default list of field names used (which defines the default ordering expected for field values). The abstract base class provides most of the boiler plate code needed to support a flexible query builder interface so the implementation can focus on just the query construction.

    The API also allows for configuring a query builder object for a particular activity once, then just updating the field values for each query to be generated. The API allows chaining of configuration and action methods so configuration and actions can be stated tersely.

    • Field Detail

      • KEY_FIELD_NAME

        public static final java.lang.String KEY_FIELD_NAME
        Special name for the record key value. This is used to designate an input field as the primary key of the record. It must always be the first field in the default input field names list.
        See Also:
        Constant Field Values

      • PARENT_KEY_FIELD_NAME

        public static final java.lang.String PARENT_KEY_FIELD_NAME
        Special name for the record parent key value. This is used to designate an input field as the parent key of the record. It must either directly follow the key field, or, if there is no key field, it must be the first field in the default input field names list.
        See Also:
        Constant Field Values

      • THESAURUS

        public static final java.lang.String THESAURUS
        standard object type name for thesaurus objects.
        See Also:
        Constant Field Values

      • LEARN_MODEL

        public static final java.lang.String LEARN_MODEL
        standard object type name for learn model objects.
        See Also:
        Constant Field Values

      • QUERYLET_NAME

        public static final java.lang.String QUERYLET_NAME
        standard object type name for querylet names.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ANetricsQueryBuilder

        public ANetricsQueryBuilder()

    • Method Detail

      • getDfltInputNames

        public java.util.List<java.lang.String> getDfltInputNames()
                                                   throws java.lang.IllegalStateException
        Return the default set of Input field names.
        Returns:
        the default set of Input field names.
        Throws:
        java.lang.IllegalStateException - if no default input field names is established.

      • getDfltOutputNames

        public java.util.List<java.lang.String> getDfltOutputNames()
                                                    throws java.lang.IllegalStateException
        Return the default set of Output field names.
        Returns:
        the default set of Output field names.
        Throws:
        java.lang.IllegalStateException - if no default output field names is established.

      • getCurOutputFieldNames

        public final java.util.List<java.lang.String> getCurOutputFieldNames()
                                                              throws java.lang.IllegalStateException
        Return the list of field names that is used in the generated query.
        Returns:
        the list of field names that is used in the generated query.
        Throws:
        java.lang.IllegalStateException

      • getCurOutputFieldName

        public final java.lang.String getCurOutputFieldName​(java.lang.String dflt_name)
                                             throws java.lang.IllegalStateException,
                                                    java.lang.IllegalArgumentException
        Return the current output field name for the given default name.
        Parameters:
        dflt_name - the default output field name.
        Returns:
        the current value for the output field name.
        Throws:
        java.lang.IllegalStateException - if the default output field names have not been established.
        java.lang.IllegalArgumentException - if dflt_name is null, empty, or not equal to one of the default output field names.

      • getCurJoinedFieldNames

        public final java.util.List<java.lang.String> getCurJoinedFieldNames()
                                                              throws java.lang.IllegalStateException
        Return the list of field names used in the generated query with join table prefix.
        Returns:
        the list of field names used in the generated query with join table prefix.
        Throws:
        java.lang.IllegalStateException

      • getCurJoinedFieldName

        public final java.lang.String getCurJoinedFieldName​(java.lang.String dflt_name)
                                             throws java.lang.IllegalStateException,
                                                    java.lang.IllegalArgumentException
        Return the current joined output field name for the given default name.
        Parameters:
        dflt_name - the default output field name.
        Returns:
        the current value for the output field name.
        Throws:
        java.lang.IllegalStateException - if the default output field names have not been established.
        java.lang.IllegalArgumentException - if dflt_name is null, empty, or not equal to one of the default output field names.

      • getCurInputFieldNames

        public final java.util.List<java.lang.String> getCurInputFieldNames()
                                                             throws java.lang.IllegalStateException
        Return the list of field names used to identify input fields.
        Returns:
        the list of field names used to identify input fields.
        Throws:
        java.lang.IllegalStateException

      • getDefaultItemNames

        public final java.util.List<java.lang.String> getDefaultItemNames​(java.lang.String item_type)
        Return the list of item names as used by the basic query builder.
        Parameters:
        item_type - the type of item to be listed. Standard types are: "thesaurus", "learn model", "querylet name"
        Returns:
        the list of item names, null if no items of the given type are used. The default implementation always returns null.

      • getUsedItemTypes

        public java.util.List<java.lang.String> getUsedItemTypes()
        Return a list of the item types used by this query builder.
        Returns:
        a list of all item types that are used by this query builder. An empty list is returned if this builder has no item names defined.

      • getCurItemNames

        public final java.util.List<java.lang.String> getCurItemNames​(java.lang.String item_type)
                                                       throws java.lang.IllegalArgumentException
        Return the list of item names as output in the generated query.
        Parameters:
        item_type - the type of item to be listed. Standard types are: ANetricsQueryBuilder.THESAURUS, ANetricsQueryBuilder.LEARN_MODEL, ANetricsQueryBuilder.QUERYLET_NAME
        Returns:
        the list of names for the given object type, null if none.
        Throws:
        java.lang.IllegalArgumentException - if item_type is null.

      • getCurItemName

        public final java.lang.String getCurItemName​(java.lang.String item_type,
                                             java.lang.String default_name)
                                      throws java.lang.IllegalArgumentException
        Get the current name of an item specified by type and default name.
        Parameters:
        item_type - the type of object. See getDefaultItemNames for a list of standard item type names.
        default_name - the default name for this item.
        Returns:
        the current name for this item. null if the given item_type or default name doesn't exist.
        Throws:
        java.lang.IllegalArgumentException - if item_type or default_name is null.

      • getCurItemName

        public final java.lang.String getCurItemName​(java.lang.String item_type,
                                             int pos)
                                      throws java.lang.IllegalArgumentException
        Get the current name of an item specified by type and position
        Parameters:
        item_type - the type of object. See getDefaultItemNames for a list of standard item type names.
        pos - the position in the default list of item names for this item type.
        Returns:
        the current name for this item. null if the given item_type doesn't exist or pos is out of range.
        Throws:
        java.lang.IllegalArgumentException - if item_type or pos is less than 0.

      • setOutputFieldNames

        public final ANetricsQueryBuilder setOutputFieldNames​(java.util.List<java.lang.String> new_names)
                                               throws java.lang.IllegalArgumentException,
                                                      java.lang.IllegalStateException
        Set the field names to be output in the generated query. This remaps the Default field names to the given values. These names will be inserted into the generated query instead of the original default names. The getCurOutputFieldNames() method returns this list.
        Parameters:
        new_names - The new list of names. This list must be the same length as the default field name list. Names must be presented in the same order as for the default field name list.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if the given list is null, not the right length, or contains null or empty entries.
        java.lang.IllegalStateException - if the default name list is not set.

      • setOutputFieldName

        public final ANetricsQueryBuilder setOutputFieldName​(java.lang.String default_name,
                                                     java.lang.String new_name)
                                              throws java.lang.IllegalArgumentException,
                                                     java.lang.IllegalStateException
        Change a single field name to be output in the generated query. This changes the field name for one field. The new name appears in the getCurOutputFieldNames() list.
        Parameters:
        default_name - the default name for the field.
        new_name - the new name for the field.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if default_name is not in the default name list, or new_name is null or empty.
        java.lang.IllegalStateException - if the default name list is not set.

      • setJoinTable

        public final ANetricsQueryBuilder setJoinTable​(java.lang.String tbl_name)
        Set the joined table name for joined queries. By default there is no join table prefix.
        Parameters:
        tbl_name - the name of the table (or alias) to be used for joined queries. A null or zero length name turns off adding of join table prefix to output names.
        Returns:
        this object.

      • setInputFieldNames

        public final ANetricsQueryBuilder setInputFieldNames​(java.util.List<java.lang.String> new_names)
                                              throws java.lang.IllegalArgumentException,
                                                     java.lang.IllegalStateException
        Set the field names to be used for input field values. This remaps the Default field names to the given values for use in identifying input fields. The getCurInputFieldNames() method returns this list.
        Parameters:
        new_names - The new list of names. This list must be the same length as the default field name list. Names must be presented in the same order as for the default field name list.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if the given list is null, not the right length, or contains null or empty entries.
        java.lang.IllegalStateException - if the default name list is not set.

      • setInputFieldName

        public final ANetricsQueryBuilder setInputFieldName​(java.lang.String default_name,
                                                    java.lang.String new_name)
                                             throws java.lang.IllegalArgumentException,
                                                    java.lang.IllegalStateException
        Set a field name to be used to identify an input field. This changes the input field name for one field. The new name appears in the getCurInputFieldNames() list.
        Parameters:
        default_name - the default name for the field.
        new_name - the new name for the field.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if default_name is not in the default name list, or new_name is null or empty.
        java.lang.IllegalStateException - if the default name list is not set.

      • changeItemNames

        public final ANetricsQueryBuilder changeItemNames​(java.lang.String item_type,
                                                  java.util.List<java.lang.String> new_names)
                                           throws java.lang.IllegalArgumentException
        Reset the item names to be output in the generated query. This remaps the Default item names to the given values. These names will be inserted into the generated query instead of the original default names. The getCurItemNames() method returns this list.
        Parameters:
        item_type - The type of item. Standard types are as listed in getDefaultItemNames().
        new_names - The new list of names. This list must be the same length as the default item name list. Names must be presented in the same order as for the default item name list.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if item_type is not used by this query, new_names is null, has the wrong length, or contains null or empty entries.

      • changeItemName

        public final ANetricsQueryBuilder changeItemName​(java.lang.String item_type,
                                                 java.lang.String default_name,
                                                 java.lang.String new_name)
                                          throws java.lang.IllegalArgumentException
        Change a single item name to be output in the generated query. This changes the item name for one item. The new name appears in the getCurItemNames() list.
        Parameters:
        item_type - The type of item. Standard types are as listed in getDefaultItemNames().
        default_name - the default name for the field.
        new_name - the new name for the field.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if item_type is not used by this query, default_name is not the default name for an item of the given type for this query, or if new_name is null or empty.

      • setInputFieldOrdering

        public final ANetricsQueryBuilder setInputFieldOrdering​(java.util.List<java.lang.String> input_fields)
                                                 throws java.lang.IllegalArgumentException,
                                                        java.lang.IllegalStateException
        Set input field ordering.

        This defines the fields that are given in the input field list, and the order in which they appear. This list consists of field names as returned by the getCurInputFieldNames method. The list may be shorter than that returned by getCurInputFieldNames, but each name given must be on the list, and a name must appear at most once.

        If this call is not made the ordering is assumed to be the same as returned by getCurInputFieldNames.

        Parameters:
        input_fields - A subset of the fields returned by getCurInputFieldNames.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if input_fields is null, or contains null or empty entries, repeated entries, or an entry that does not match a current input field name.
        java.lang.IllegalStateException - if the default name list is not set.

      • setDefaultValue

        public final ANetricsQueryBuilder setDefaultValue​(java.lang.String default_value)
        Set the default field value. This sets the value used for any field in the query that does not appear in the input field ordering list. It also sets the default value for null field values. By default the default value is null, which will generate an exception when the query is generated. So if the ordering list is shorter than the complete field list this must be set.
        Parameters:
        default_value - the value used as the default.
        Returns:
        this object.

      • setFieldValues

        public final ANetricsQueryBuilder setFieldValues​(java.util.List<java.lang.String> field_values)
                                          throws java.lang.IllegalArgumentException,
                                                 java.lang.IllegalStateException
        Set the current field values. This must be called before generating a query. It establishes the field values to be inserted into the query.
        Parameters:
        field_values - the list of field values. The length and order must match the current field ordering as defined by the setInputFieldOrdering method, or as defined by the getCurInputFieldNames method if setInputFieldOrdering was never called.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if field_values is the wrong length, or if some entries are left with a null value.
        java.lang.IllegalStateException - if the default name list is not set.

      • setFieldValues

        public final ANetricsQueryBuilder setFieldValues​(NetricsRecord record)
                                          throws java.lang.IllegalArgumentException,
                                                 java.lang.IllegalStateException
        Set the current field values from a NetricsRecord object. This is a convenience method that sets the field values directly from an input NetricsRecord object. If the first default input field name was the special KEY_FIELD_NAME, then the record key is inserted as the first data value. If the first default input field name (or second field if the first was the special KEY_FIELD_NAME value) is the special PARENT_KEY_FIELD_NAME value, then the parent key from the record is inserted before the record data fields.
        Parameters:
        record - the record containing the field values to use.
        Returns:
        this object for chaining.
        Throws:
        java.lang.IllegalArgumentException
        java.lang.IllegalStateException

      • setFieldValues

        public final ANetricsQueryBuilder setFieldValues​(java.util.Map<java.lang.String,​java.lang.String> field_map)
                                          throws java.lang.IllegalArgumentException,
                                                 java.lang.IllegalStateException
        Set the current field values. This must be called before generating a query. It establishes the field values to be inserted into the query.
        Parameters:
        field_map - This is a map where the index is a field name as found in getCurInputFieldNames() and the value is the value for the corresponding field. It is an error if an index value is not in the getCurInputFieldNames() list.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if field_map contains entries that do not match the current input field names.
        java.lang.IllegalStateException

      • setExtraData

        public final ANetricsQueryBuilder setExtraData​(java.lang.Object extra_data)
        Set any extra data for the query builder. This allows any arbitrary extra data to be passed in for special cases.
        Parameters:
        extra_data - an object containing the extra data needed.
        Returns:
        this object.

      • getQuery

        public abstract NetricsQuery getQuery()
                               throws java.lang.IllegalStateException,
                                      java.lang.Exception
        Generate and return a Query object for the current field set. It is an error if no field set is established.
        Returns:
        the generated NetricsQuery object.
        Throws:
        java.lang.IllegalStateException - if field values are not established.
        java.lang.Exception - on other errors.

      • setConfiguration

        public java.lang.Object setConfiguration​(java.io.File config_file)
                                  throws java.lang.UnsupportedOperationException,
                                         java.io.IOException,
                                         java.lang.IllegalArgumentException
        Initialize the builder from a configuration file.

        This configures the query builder from a configuration file. The configuration file may configure new input/output field names, object names, etc. It may set internal weights and parameters. It is completely up to the implementation what this configures.

        The configuration read in is returned as an object. New query builders from the same class can then be configured directly from the object, avoiding the overhead of reading in the file each time.

        Parameters:
        config_file - A file reference to the configuration file to be processed by this query builder.
        Returns:
        the configuration as a Java object. This can be passed to the setConfiguration(Object config_object) method of a different query builder object for the same class.
        Throws:
        java.lang.UnsupportedOperationException - if this class does not support setting of the configuration from a File.
        java.io.IOException - on errors opening or reading the given file.
        java.lang.IllegalArgumentException - if the file is not a valid configuration file for this class.

      • setConfiguration

        public java.lang.Object setConfiguration​(java.lang.String config_source)
                                  throws java.lang.UnsupportedOperationException,
                                         java.io.IOException,
                                         java.lang.IllegalArgumentException,
                                         java.lang.IllegalStateException
        Initialize the builder from a configuration source.

        This configures the query builder from a configuration source identified by a string. Typically this is a file name or file path. The configuration source may configure new input/output field names, object names, etc. It may set internal weights and parameters. It may define the feature querylets and tables for this builder. It is completely up to the implementation what this configures.

        The configuration read in is returned as an object. New query builders from the same class can then be configured directly from the object, avoiding the overhead of reading and parsing the configuration each time.

        Parameters:
        config_source - A string reference to the configuration source data to be processed by this query builder.
        Returns:
        the configuration as a Java object. This can be passed to the setConfiguration(Object config_object) method of a different query builder object for the same class.
        Throws:
        java.lang.UnsupportedOperationException - if this class does not support setting of the configuration from a source string.
        java.io.IOException - on errors opening or reading the given source.
        java.lang.IllegalArgumentException - if the source is not a valid configuration for this class.
        java.lang.IllegalStateException - if this object is already iniitalized.

      • setConfiguration

        public java.lang.Object setConfiguration​(java.io.InputStream config_stream)
                                  throws java.lang.UnsupportedOperationException,
                                         java.io.IOException,
                                         java.lang.IllegalArgumentException,
                                         java.lang.IllegalStateException
        Initialize the builder from an InputStream.

        This configures the query builder from an InputStream containing the configuration data. The configuration data may configure new input/output field names, object names, etc. It may set internal weights and parameters. It may define the feature querylets and tables for this builder. It is completely up to the implementation what this configures.

        The configuration read in is returned as an object. New query builders from the same class can then be configured directly from the object, avoiding the overhead of reading and parsing the configuration each time.

        Parameters:
        config_stream - An open input stream that returns the configuration data.
        Returns:
        the configuration as a Java object. This can be passed to the setConfiguration(Object config_object) method of a different query builder object for the same class.
        Throws:
        java.lang.UnsupportedOperationException - if this class does not support setting of the configuration from a source stream.
        java.io.IOException - on errors reading the given source.
        java.lang.IllegalArgumentException - if the stream data isn't a valid configuration for this class.
        java.lang.IllegalStateException - if this object is already iniitalized.

      • setConfiguration

        public void setConfiguration​(java.lang.Object config_object)
                      throws java.lang.UnsupportedOperationException,
                             java.lang.IllegalArgumentException
        Initialize the builder from a configuration object.

        This configures the query builder from a configuration object. The configuration object is normally obtained from a previous call to the setConfiguration(File config_file) method. The configuration object may configure new input/output field names, object names, etc. It may set internal weights and parameters. It is completely up to the implementation what this configures.

        Parameters:
        config_object - An object holding the configuration information for this query builder. Each class defines its own object type.
        Throws:
        java.lang.UnsupportedOperationException - if this class does not support setting of the configuration from an Object.
        java.lang.IllegalArgumentException - if the object is not a valid configuration object for this class.

      • setSearchOpts

        public ANetricsQueryBuilder setSearchOpts​(NetricsSearchOpts opts)
                                   throws java.lang.IllegalArgumentException,
                                          java.lang.IllegalStateException
        Add search options. This method adds any search options associated with the query that would be built by this object, to the given NetricsSeachOpts object. The default implementation does nothing.
        Parameters:
        opts - a search options object. This may throw an exception if opts is null.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - the method may throw this exception if opts is null.
        java.lang.IllegalStateException - the method may throw this exception if field values are required but not set.

      • setQueryConfiguration

        public ANetricsQueryBuilder setQueryConfiguration​(NetricsSearchCfg cfg)
                                           throws java.lang.IllegalArgumentException,
                                                  java.lang.IllegalStateException
        Add any query configuration options to the configuration. This method adds any search configuration options associated with the query that would be built by this object, to the given NetricsSearchCfg object. This is primarily intended to allow for filtering predicates. The default implementation does nothing.
        Parameters:
        cfg - a search configration object. This may throw an exception if cfg is null.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - this method may throw this exception if cfg is null.
        java.lang.IllegalStateException - the method may throw this exception if field values are required but not set.