com.netrics.likeit

Class ANetricsQueryBuilder

java.lang.Object

com.netrics.likeit.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 Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	KEY_FIELD_NAME Special name for the record key value.
static java.lang.String	LEARN_MODEL standard object type name for learn model objects.
static java.lang.String	PARENT_KEY_FIELD_NAME Special name for the record parent key value.
static java.lang.String	QUERYLET_NAME standard object type name for querylet names.
static java.lang.String	THESAURUS standard object type name for thesaurus objects.

Constructor Summary

Constructors

Constructor and Description
ANetricsQueryBuilder()

Method Summary

Modifier and Type	Method and Description
ANetricsQueryBuilder	changeItemName(java.lang.String item_type, java.lang.String default_name, java.lang.String new_name) Change a single item name to be output in the generated query.
ANetricsQueryBuilder	changeItemNames(java.lang.String item_type, java.util.List<java.lang.String> new_names) Reset the item names to be output in the generated query.
java.util.List<java.lang.String>	getCurInputFieldNames() Return the list of field names used to identify input fields.
java.lang.String	getCurItemName(java.lang.String item_type, int pos) Get the current name of an item specified by type and position
java.lang.String	getCurItemName(java.lang.String item_type, java.lang.String default_name) Get the current name of an item specified by type and default name.
java.util.List<java.lang.String>	getCurItemNames(java.lang.String item_type) Return the list of item names as output in the generated query.
java.lang.String	getCurJoinedFieldName(java.lang.String dflt_name) Return the current joined output field name for the given default name.
java.util.List<java.lang.String>	getCurJoinedFieldNames() Return the list of field names used in the generated query with join table prefix.
java.lang.String	getCurOutputFieldName(java.lang.String dflt_name) Return the current output field name for the given default name.
java.util.List<java.lang.String>	getCurOutputFieldNames() Return the list of field names that is used in the generated query.
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.
java.util.List<java.lang.String>	getDfltInputNames() Return the default set of Input field names.
java.util.List<java.lang.String>	getDfltOutputNames() Return the default set of Output field names.
abstract NetricsQuery	getQuery() Generate and return a Query object for the current field set.
java.util.List<java.lang.String>	getUsedItemTypes() Return a list of the item types used by this query builder.
java.lang.Object	setConfiguration(java.io.File config_file) Initialize the builder from a configuration file.
java.lang.Object	setConfiguration(java.io.InputStream config_stream) Initialize the builder from an InputStream.
void	setConfiguration(java.lang.Object config_object) Initialize the builder from a configuration object.
java.lang.Object	setConfiguration(java.lang.String config_source) Initialize the builder from a configuration source.
ANetricsQueryBuilder	setDefaultValue(java.lang.String default_value) Set the default field value.
ANetricsQueryBuilder	setExtraData(java.lang.Object extra_data) Set any extra data for the query builder.
ANetricsQueryBuilder	setFieldValues(java.util.List<java.lang.String> field_values) Set the current field values.
ANetricsQueryBuilder	setFieldValues(java.util.Map<java.lang.String,java.lang.String> field_map) Set the current field values.
ANetricsQueryBuilder	setFieldValues(NetricsRecord record) Set the current field values from a NetricsRecord object.
ANetricsQueryBuilder	setInputFieldName(java.lang.String default_name, java.lang.String new_name) Set a field name to be used to identify an input field.
ANetricsQueryBuilder	setInputFieldNames(java.util.List<java.lang.String> new_names) Set the field names to be used for input field values.
ANetricsQueryBuilder	setInputFieldOrdering(java.util.List<java.lang.String> input_fields) Set input field ordering.
ANetricsQueryBuilder	setJoinTable(java.lang.String tbl_name) Set the joined table name for joined queries.
ANetricsQueryBuilder	setOutputFieldName(java.lang.String default_name, java.lang.String new_name) Change a single field name to be output in the generated query.
ANetricsQueryBuilder	setOutputFieldNames(java.util.List<java.lang.String> new_names) Set the field names to be output in the generated query.
ANetricsQueryBuilder	setQueryConfiguration(NetricsSearchCfg cfg) Add any query configuration options to the configuration.
ANetricsQueryBuilder	setSearchOpts(NetricsSearchOpts opts) Add search options.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.