Package com.netrics.likeit

Class ANetricsCompoundQueryBuilder

  • public abstract class ANetricsCompoundQueryBuilder
extends java.lang.Object
    A query builder class for building compound queries.

    This class is analogous to the ANetricsQueryBuilder abstract class. It provides the ability to build matching queries for compound records, whereas the ANetricsQueryBuilder class builds queries for matching a single table. A compound record is a parent record with zero or more child records. There may be child records for multiple child tables, and there may be multiple child records for a single on of the child tables. A compound record matching query finds the best matching combination of parent record and child records.

    A compound query consists of one or more feature querylets. Each feature querylet is a query against a single table. There can be at most one feature querylet for each child table. To build the complete compound query an ANetricsCompoundQueryBuilder object must have an ANetricsQueryBuilder object for each feature querylet. The parent table may have multiple feature querylets. However all parent table querylets must have the exact same set of default input and output field names.

    The setting of input and output field names and item names is by table. Essentially the setting of input and output field names, and item names, is passed on to the ANetricsQueryBuilder objects associated with the table.

    • Constructor Detail

      • ANetricsCompoundQueryBuilder

        public ANetricsCompoundQueryBuilder()

    • Method Detail

      • getDfltInputNames

        public java.util.List<java.lang.String> getDfltInputNames​(java.lang.String table_name)
                                                   throws java.lang.IllegalStateException,
                                                          java.lang.IllegalArgumentException
        Return the default set of Input field names for the given table.
        Parameters:
        table_name - the original default table name.
        Returns:
        the default set of Input field names, null if no feature is defined for the given table.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if table_name is null, empty or not a valid default table name.

      • getCurInputFieldNames

        public java.util.List<java.lang.String> getCurInputFieldNames​(java.lang.String table_name)
                                                       throws java.lang.IllegalArgumentException,
                                                              java.lang.IllegalStateException
        Return the list of field names for the specified table used to identify input fields.
        Parameters:
        table_name - the original default table name.
        Returns:
        the list of field names used to identify input fields, null if there is no feature for this table.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if table_name is null, empty or not a valid default table name.

      • getDfltOutputNames

        public java.util.List<java.lang.String> getDfltOutputNames​(java.lang.String table_name)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException
        Return the default set of Output field names for the given table.
        Parameters:
        table_name - the original default table name.
        Returns:
        the default set of Output field names, null if no feature is defined for this table.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if table_name is null, empty or not a valid default table name.

      • getCurOutputFieldNames

        public java.util.List<java.lang.String> getCurOutputFieldNames​(java.lang.String table_name)
        Return the list of field names that is used in the generated query for the given table. The list has the same length and ordering as the default field name list.
        Parameters:
        table_name - the original default table name.
        Returns:
        the list of field names that is used in the generated query, null if there is no feature for this table.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if table_name is null, empty or not a valid default table name.

      • getCurJoinedFieldNames

        public java.util.List<java.lang.String> getCurJoinedFieldNames()
                                                        throws java.lang.IllegalStateException,
                                                               java.lang.IllegalArgumentException
        Return the list of field names used in the generated query with join table prefix. This returns a combined list for all tables. The tables are returned in the same order as returned by getDefaultTableNames(). Fields are returned in the same order as the default field ordering for the table.
        Returns:
        the list of field names used in the generated query with join table prefix.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if table_name is null, empty or not a valid default table name.

      • getCurJoinedFieldNames

        public java.util.List<java.lang.String> getCurJoinedFieldNames​(java.lang.String table_name)
                                                        throws java.lang.IllegalArgumentException,
                                                               java.lang.IllegalStateException
        Return the list of field names with join table prefix, for the given table. This is a list only for the given table. The names appear in the same order as the default output name field list.
        Parameters:
        table_name - the original default table name.
        Returns:
        the list of field names with join table prefix, for the given table, null if there is no feature to the table.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if table_name is null, empty or not a valid default table name.

      • setOutputFieldNames

        public ANetricsCompoundQueryBuilder setOutputFieldNames​(java.lang.String table_name,
                                                        java.util.List<java.lang.String> new_names)
                                                 throws java.lang.IllegalArgumentException,
                                                        java.lang.IllegalStateException
        Set the field names for the given table 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(table_name) method returns this list.
        Parameters:
        table_name - the original default table name.
        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 there is no such table as table_name, if the given list is null, not the right length, or contains null or empty entries.
        java.lang.IllegalStateException - if features have not been established.

      • setOutputFieldName

        public ANetricsCompoundQueryBuilder setOutputFieldName​(java.lang.String table_name,
                                                       java.lang.String default_name,
                                                       java.lang.String new_name)
                                                throws java.lang.IllegalArgumentException,
                                                       java.lang.IllegalStateException
        For the specified table change a single field name to be output in the generated query. This changes the field name for one field in the given table. The new name appears in the getCurOutputFieldNames(table_name) list.
        Parameters:
        table_name - the original default table name.
        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 features have not been established.

      • setInputFieldNames

        public ANetricsCompoundQueryBuilder setInputFieldNames​(java.lang.String table_name,
                                                       java.util.List<java.lang.String> new_names)
                                                throws java.lang.IllegalArgumentException,
                                                       java.lang.IllegalStateException
        Set the field names for a table to be used for input field values. This remaps the Default field names for the given table to the given values for use in identifying input fields. The getCurInputFieldNames(table_name) method returns this list.
        Parameters:
        table_name - the original default table name.
        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 features have not been established.

      • setInputFieldName

        public ANetricsCompoundQueryBuilder setInputFieldName​(java.lang.String table_name,
                                                      java.lang.String default_name,
                                                      java.lang.String new_name)
                                               throws java.lang.IllegalArgumentException,
                                                      java.lang.IllegalStateException
        Set a field name for the given table to be used to identify an input field. This changes the input field name for one field for the given table. The new name appears in the getCurInputFieldNames() list.
        Parameters:
        table_name - the original default table name.
        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 features have not been established.

      • setInputFieldOrdering

        public ANetricsCompoundQueryBuilder setInputFieldOrdering​(java.lang.String table_name,
                                                          java.util.List<java.lang.String> input_fields)
        Set the input field ordering for the specified table.

        This defines the fields that are given in the input field list for the specified table, and the order in which they appear. This list consists of field names as returned by the getCurInputFieldNames(table_name) 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:
        table_name - the original default table name.
        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 features have not been established.

      • setDefaultValue

        public ANetricsCompoundQueryBuilder setDefaultValue​(java.lang.String default_field_value)
                                             throws java.lang.IllegalStateException
        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.

        The default value is the same for all tables.

        Parameters:
        default_field_value - the value used as the default.
        Returns:
        this object.
        Throws:
        java.lang.IllegalStateException - if features have not been established.

      • getDefaultTableNames

        public java.util.List<java.lang.String> getDefaultTableNames()
                                                      throws java.lang.IllegalStateException
        Return a list of all tables used by this compound query builder. The list must list the parent table first. These are the names as known to the query builder. All method calls that have a table_name parameter reference a name in this list.
        Returns:
        list of all tables referenced by this query builder.
        Throws:
        java.lang.IllegalStateException - if features have not been established.

      • getCurrentOutputTableNames

        public java.util.List<java.lang.String> getCurrentOutputTableNames()
                                                            throws java.lang.IllegalStateException
        Return a list of table names as output in the generate queries. These are the table names as they will appear in the generated query, search options and search configuration. The list is in the same order as returned by the getDefaultTableNames() list.
        Returns:
        list of all output table names.
        Throws:
        java.lang.IllegalStateException - if features have not been established.

      • getCurrentInputTableNames

        public java.util.List<java.lang.String> getCurrentInputTableNames()
                                                           throws java.lang.IllegalStateException
        Return a list of table names as recognized in the input record data. These are the table names expected in the input compound record data. This list is in the same order as returned by the getDefaultTableNames() list.
        Returns:
        list of all input table names.
        Throws:
        java.lang.IllegalStateException - if features have not been established.

      • setOutputTableName

        public ANetricsCompoundQueryBuilder setOutputTableName​(java.lang.String table_name,
                                                       java.lang.String output_alias)
                                                throws java.lang.IllegalArgumentException,
                                                       java.lang.IllegalStateException
        Set the table name to be used in the generated queries. This sets a single table name. The output_alias value is output in the generated query, search options and search configuration.
        Parameters:
        table_name - the original default table name.
        output_alias - the name as it should appear in the generated query.
        Returns:
        this object for chaining of calls.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if either name is null or empty, or if table_name is not a defined default table name.

      • setInputTableNames

        public ANetricsCompoundQueryBuilder setInputTableNames​(java.util.List<java.lang.String> new_names)
                                                throws java.lang.IllegalStateException,
                                                       java.lang.IllegalArgumentException
        Set the table names as recognized in the input record data. This sets the table names as they will appear in the input record data. If this method is not called the input table names will be the same as the default table names returned by getDefaultTableNames().
        Parameters:
        new_names - a list of the table names as used in the input record data. The list must be the same length and same order as that returned by getDefaultTableNames(). Null or empty names are not allowed.
        Returns:
        this object for chaining of calls.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if new_names is null, not the same length as the default list, or contains empty elements.

      • setInputTableName

        public ANetricsCompoundQueryBuilder setInputTableName​(java.lang.String table_name,
                                                      java.lang.String input_alias)
                                               throws java.lang.IllegalArgumentException,
                                                      java.lang.IllegalStateException
        Set the table name as recognized in the input record data. This sets a single table name. The input_alias value is recognized in the input record table.
        Parameters:
        table_name - the original default table name.
        input_alias - the name as it will appear in the input record data.
        Returns:
        this object for chaining of calls.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if either name is null or empty, or if table_name is not a defined default table name.

      • getDefaultItemNames

        public java.util.List<java.lang.String> getDefaultItemNames​(java.lang.String item_type)
                                                     throws java.lang.IllegalArgumentException,
                                                            java.lang.IllegalStateException
        Return the list of default item names for the specified item type. These are the names as recognized by the underlying query builders. This list is a consolidated list from all builders.
        Parameters:
        item_type - the type of item to be listed.
        Returns:
        the list of default item names, an empty list if no builder uses this item type.
        Throws:
        java.lang.IllegalStateException - if features have not been established.
        java.lang.IllegalArgumentException - if the item_type is null or empty.

      • getUsedItemTypes

        public java.util.List<java.lang.String> getUsedItemTypes()
                                                  throws java.lang.IllegalStateException
        Return the list of used item types. The list returned is a consolidated list of all types used in any of the builders, including our own.
        Returns:
        the list of all unique item types.
        Throws:
        java.lang.IllegalStateException - if features have not been established.

      • getCurItemName

        public java.lang.String getCurItemName​(java.lang.String item_type,
                                       java.lang.String default_name)
                                throws java.lang.IllegalArgumentException,
                                       java.lang.IllegalStateException
        Get the current name of an item for the given item type and default name.
        Parameters:
        item_type - the type of object.
        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 in any builder.
        Throws:
        java.lang.IllegalArgumentException - if item_type or default_name is null or empty.
        java.lang.IllegalStateException - if features have not been established.

      • changeItemName

        public boolean changeItemName​(java.lang.String item_type,
                              java.lang.String default_name,
                              java.lang.String new_name)
                       throws java.lang.IllegalArgumentException,
                              java.lang.IllegalStateException
        Change a single item name to be output in the generated query. This changes the item name for one item in all builders, including this compound builder.
        Parameters:
        item_type - The type of item.
        default_name - the default name for the item.
        new_name - the new name for the item.
        Returns:
        true if at least one builder contained the indicated item name and was successfully updated. False otherwise.
        Throws:
        java.lang.IllegalArgumentException - if any argument is null or empty.
        java.lang.IllegalStateException - if features have not been established.

      • setFieldValuesFromRecord

        public ANetricsCompoundQueryBuilder setFieldValuesFromRecord​(NetricsCompoundRecord record)
                                                      throws java.lang.IllegalArgumentException,
                                                             java.lang.IllegalStateException,
                                                             java.lang.Exception
        Set the current field values. One of the setFieldValues* methods must be called before generating a query. It establishes the field values to be inserted into the query. The field values are taken from a compound record. A compound record has a single parent record with zero or more child records. The child records may be for any of the defined child tables. There may be multiple child records for a single child table.

        This method takes the field data from a NetricsCompoundRecord object. The table names for the child records in the compound record must match those as returned by the getCurrentInputTableNames method. The number of fields and ordering of the fields for a record must match those as established by the setFieldOrdering call for the associated table. If no setFieldOrdering call was made they must match the ordering as returned by the getCurInputFieldNames method.

        Parameters:
        record - the compound record containing the field data.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if the compound record doesn't contain data for any of the currently defined tables, or if record is null or contains null field data and no default value is established.
        java.lang.IllegalStateException - if features have not been established, or if one of the builders is not properly initialized.
        java.lang.Exception - as thrown by ANetricsQueryBuilder.getQuery.

      • setFieldValuesFromList

        public ANetricsCompoundQueryBuilder setFieldValuesFromList​(java.util.Map<java.lang.String,​java.util.List<java.util.List<java.lang.String>>> record_data)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException,
                                                           java.lang.Exception
        Set the current field values. One of the setFieldValues* methods must be called before generating a query. It establishes the field values to be inserted into the query. The field values are taken from a mapping of table names to record data.

        This method takes the field data from a Map. The index of the map is a table name as returned by the getCurrentInputTableNames method. The value is a list of record values. The record values are passed as a list of String values. The length of the list and the ordering of the values must match those as established by the setFieldOrdering call for the associated table. If no setFieldOrdering call was made they must match the ordering as returned by the getCurInputFieldNames method.

        An entry for the parent table is required. Entries for child tables are optional. It is an error if there is more than one record in the parent table list.

        Parameters:
        record_data - the mapping as described above.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if the record data doesn't contain data for any of the currently defined tables, or if record_data is null or contains null field data and no default value is established.
        java.lang.IllegalStateException - if features have not been established, or if one of the builders is not properly initialized.
        java.lang.Exception - as thrown by ANetricsQueryBuilder.getQuery.

      • setFieldValuesFromMap

        public ANetricsCompoundQueryBuilder setFieldValuesFromMap​(java.util.Map<java.lang.String,​java.util.List<java.util.Map<java.lang.String,​java.lang.String>>> record_data)
                                                   throws java.lang.IllegalArgumentException,
                                                          java.lang.IllegalStateException,
                                                          java.lang.Exception
        Set the current field values. One of the setFieldValues* methods must be called before generating a query. It establishes the field values to be inserted into the query. The field values are taken from a mapping of table names to record data.

        This method takes the field data from a Map. The index of the map is a table name as returned by the getCurrentInputTableNames method. The value is a list of record values. The record values are passed as a Mapping of String keys, to String values. The key must be an input field name as returned by getCurInputFieldNames for the associated table. The value is the field value.

        There must be at least one entry for one table. It is an error if there is more than one record in the parent table list.

        Parameters:
        record_data - the mapping as described above.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - if record_data is null, if any key value does not correspond to a table name as returned by getCurrentInputTableNames, if there is no entry for the parent table, or if its list does not contain exactly one entry, if the record data mapping contains a key that is not a current input field name for the associated table, or if any field value is null, or not given in the mapping and there is no default value established.
        java.lang.IllegalStateException - if features have not been established.
        java.lang.Exception - as thrown by ANetricsQueryBuilder.getQuery.

      • setConfiguration

        public java.lang.Object setConfiguration​(java.io.File config_file)
                                  throws java.lang.UnsupportedOperationException,
                                         java.io.IOException,
                                         java.lang.IllegalArgumentException,
                                         java.lang.IllegalStateException
        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 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 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.
        java.lang.IllegalStateException - if this object is already iniitalized.

      • 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,
                             java.lang.IllegalStateException
        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.
        java.lang.IllegalStateException - if this object is already iniitalized.

      • 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 by a call to one of the setFieldValues* methods.
        Returns:
        the generated NetricsQuery object.
        Throws:
        java.lang.IllegalStateException - if field values are not established.
        java.lang.Exception - on other errors.

      • setSearchOpts

        public static NetricsSearchOpts setSearchOpts​(NetricsSearchOpts opts)
        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. If opts is null and search options must be added a new NetricsSearchOpts object is created, initialized and returned.
        Parameters:
        opts - a search options object.
        Returns:
        the updated search options object.
        Throws:
        java.lang.IllegalStateException - the method may throw this exception if field values are required but not set.

      • setQueryConfiguration

        public NetricsSearchCfg setQueryConfiguration​(NetricsSearchCfg cfg)
                                       throws java.lang.IllegalStateException,
                                              java.lang.Exception
        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. If cfg is null a new configuration is created with the appropriate join definition, any configuration options are then added. If cfg is not null it is assumed the appropriate join definition is already established and only additional options are added.

        The default implementation creates a JOIN_FULL_AND_PARTIALS mode join using single parent mode. It uses all defined tables.

        Parameters:
        cfg - a search configration object.
        Returns:
        the updated or newly created configuration.
        Throws:
        java.lang.IllegalStateException - the method may throw this exception if field values are required but not set.
        java.lang.Exception - other exceptions may be thrown by custom implementations.