com.tibco.patterns.qbp

Class GeneralCompoundQueryBuilder

java.lang.Object

com.netrics.likeit.ANetricsCompoundQueryBuilder

com.tibco.patterns.qbp.GeneralCompoundQueryBuilder

public class GeneralCompoundQueryBuilder
extends com.netrics.likeit.ANetricsCompoundQueryBuilder

Generalized compound query builder class. This class acts as a compound query builder. The query it builds is defined by an XML configuration file. The XML supports building almost any query structure.

In addition to the standard query builder operations this class supports generating java classes that build the queries defined by the XML file.

Although this class is a compound query builder it also supports building queries for a single table. This is viewed as a compound query builder that has only one feature. As a feature is tied to one table, a compound query builder with only one feature is a builder of a single table query.

Nested Class Summary

Nested classes/interfaces inherited from class com.netrics.likeit.ANetricsCompoundQueryBuilder

com.netrics.likeit.ANetricsCompoundQueryBuilder.FeatureDef

Field Summary

Fields inherited from class com.netrics.likeit.ANetricsCompoundQueryBuilder

features

Constructor Summary

Constructors

Constructor and Description
GeneralCompoundQueryBuilder() Default constructor.
GeneralCompoundQueryBuilder(IQBPFileMgr file_mgr, IQBPLoaderMgr loader_mgr, com.tibco.patterns.qbp.jaxb.RecordMatchingQueryDef input_config, AQBPLogger logger) Create a new general compound query builder from a configuration object.

Method Summary

Modifier and Type	Method and Description
boolean	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.
boolean	generateSource(java.io.File generated_source_directory, AQBPLogger logger) Generate code for this query builder.
protected com.netrics.likeit.ANetricsQueryBuilder	getBuilder(java.lang.String class_name, java.lang.String class_file, AQBPLogger logger) Retrieve a class as an ANetricsQueryBuilder object.
java.lang.String	getCurItemName(java.lang.String item_type, java.lang.String default_name) Get the current name of an item for the given item type and default name.
java.util.List<java.lang.String>	getDefaultItemNames(java.lang.String item_type) Return the list of default item names for the specified item type.
com.netrics.likeit.NetricsQuery	getQuery() Implement the qetQuery method for running in interpretive mode.
java.util.List<java.lang.String>	getUsedItemTypes() Return the list of used item types.
boolean	installCustomClasses(java.io.File generated_class_directory, AQBPLogger logger) Install the custom classes for this compound query builder.
static void	main(java.lang.String[] args) Provide command line interface for generating query builders.
static void	outputAnnotatedConfiguration(com.tibco.patterns.qbp.jaxb.RecordMatchingQueryDef config_object, java.io.File annotated_config_file, AQBPLogger logger) Output an annotated input configuration file.
boolean	outputRunTimeConfiguration(java.io.File run_time_config_directory, java.io.File output_config_directory, AQBPLogger logger) Output the run time configuration files.
java.lang.Object	setConfiguration(java.io.File config_file) Initialize this general compound query builder from a RecordMatchingQueryDef file.
java.lang.Object	setConfiguration(java.io.InputStream config_stream) Initialize this general compound query builder from a RecordMatchingQueryDef stream.
void	setConfiguration(java.lang.Object config_object) Initialize this general compound query builder from a RecordMatchingQueryDef object.
java.lang.Object	setConfiguration(java.lang.String config_src) Initialize this general compound query builder from a RecordMatchingQueryDef source.
void	setFileMgr(IQBPFileMgr file_manager) Set the file manager used by this query builder.

Methods inherited from class com.netrics.likeit.ANetricsCompoundQueryBuilder

addDefaultItem, getCurInputFieldNames, getCurJoinedFieldNames, getCurJoinedFieldNames, getCurOutputFieldNames, getCurrentInputTableNames, getCurrentOutputTableNames, getDefaultTableNames, getDfltInputNames, getDfltOutputNames, getFeatureQueryletLists, getFeatureQuerylets, getJoinConfig, setDefaultValue, setFeatures, setFieldValuesFromList, setFieldValuesFromMap, setFieldValuesFromRecord, setInputFieldName, setInputFieldNames, setInputFieldOrdering, setInputTableName, setInputTableNames, setOutputFieldName, setOutputFieldNames, setOutputTableName, setQueryConfiguration, setSearchOpts, setTables

Methods inherited from class java.lang.Object

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

Constructor Detail

GeneralCompoundQueryBuilder

public GeneralCompoundQueryBuilder()

Default constructor. This creates an uninitialized general compound builder. It must be initialized by calling one of the setConfiguration methods before it can be used.

GeneralCompoundQueryBuilder

public GeneralCompoundQueryBuilder(IQBPFileMgr file_mgr,
                                   IQBPLoaderMgr loader_mgr,
                                   com.tibco.patterns.qbp.jaxb.RecordMatchingQueryDef input_config,
                                   AQBPLogger logger)
                            throws java.lang.IllegalArgumentException,
                                   AQBPLogger.QBPException,
                                   AQBPLogger.QBPConfigException

Create a new general compound query builder from a configuration object.

Parameters:

file_mgr - the file manager to use when loading configuration files. If null the default file manager is used.

loader_mgr - the class loader manager to use when loading classes. If null the default loader manager is used.

input_config - the definition of the compound query to be built.

logger - a logger used to log all messages and errors.

Throws:

java.lang.IllegalArgumentException - if any argument is null.

AQBPLogger.QBPException - if exception mode is on and an error is encountered or if a fatal error is encountered.

AQBPLogger.QBPConfigException - if config exception mode is on and a configuration error is encountered or if a fatal configuration error is encountered.

Method Detail

getBuilder

protected com.netrics.likeit.ANetricsQueryBuilder getBuilder(java.lang.String class_name,
                                                             java.lang.String class_file,
                                                             AQBPLogger logger)
                                                      throws AQBPLogger.QBPException,
                                                             java.lang.IllegalArgumentException

Retrieve a class as an ANetricsQueryBuilder object. This dynamically loads a class and creates an instance of it using the default constructor. It then casts the instance to ANetricsQueryBuilder and returns it. This is used to load custom classes.

Parameters:

class_name - the full name of the class to be instantiated.

class_file - the file containing the builder class. This first attempts to load the class from this file, if that fails it attempts to load it from the standard class path.

logger - a logger for logging errors.

Returns:

an instance of the class created with the default constructor, null if the class could not be loaded and instantiated.

Throws:

java.lang.IllegalArgumentException - if logger is null.

AQBPLogger.QBPException - if logger is in exception mode and an error is encountered.

setConfiguration

public java.lang.Object setConfiguration(java.io.File config_file)
                                  throws java.lang.UnsupportedOperationException,
                                         java.lang.IllegalArgumentException,
                                         java.lang.IllegalStateException

Initialize this general compound query builder from a RecordMatchingQueryDef file.

Overrides:

setConfiguration in class com.netrics.likeit.ANetricsCompoundQueryBuilder

Parameters:

config_file - this must be an existing file containing a RecordMatchingQueryDef XML element as the top element.

Throws:

java.lang.IllegalArgumentException - if config_file is null, not an existing file, does not contain a RecordMatchingQueryDef XML element as the top level element, or if there are any errors processing its contents.

java.lang.IllegalStateException - if this object is already initialized.

java.lang.UnsupportedOperationException

setConfiguration

public java.lang.Object setConfiguration(java.io.InputStream config_stream)
                                  throws java.lang.UnsupportedOperationException,
                                         java.lang.IllegalArgumentException,
                                         java.lang.IllegalStateException

Initialize this general compound query builder from a RecordMatchingQueryDef stream.

Overrides:

setConfiguration in class com.netrics.likeit.ANetricsCompoundQueryBuilder

Parameters:

config_stream - this must be an open stream containing a RecordMatchingQueryDef XML element as the top element.

Throws:

java.lang.IllegalArgumentException - if config_stream is null, does not contain a RecordMatchingQueryDef XML element as the top level element, or if there are any errors processing its contents.

java.lang.IllegalStateException - if this object is already initialized.

java.lang.UnsupportedOperationException

setConfiguration

public java.lang.Object setConfiguration(java.lang.String config_src)
                                  throws java.lang.UnsupportedOperationException,
                                         java.lang.IllegalArgumentException,
                                         java.lang.IllegalStateException

Initialize this general compound query builder from a RecordMatchingQueryDef source.

Overrides:

setConfiguration in class com.netrics.likeit.ANetricsCompoundQueryBuilder

Parameters:

config_src - this must be an existing file source containing a RecordMatchingQueryDef XML element as the top element.

Throws:

java.lang.IllegalArgumentException - if config_src is null, not an existing source, does not contain a RecordMatchingQueryDef XML element as the top level element, or if there are any errors processing its contents.

java.lang.IllegalStateException - if this object is already initialized.

java.lang.UnsupportedOperationException

setConfiguration

public void setConfiguration(java.lang.Object config_object)
                      throws java.lang.UnsupportedOperationException,
                             java.lang.IllegalArgumentException,
                             java.lang.IllegalStateException

Initialize this general compound query builder from a RecordMatchingQueryDef object.

Overrides:

setConfiguration in class com.netrics.likeit.ANetricsCompoundQueryBuilder

Parameters:

config_object - this must be a valid RecordMatchingQueryDef object.

Throws:

java.lang.IllegalArgumentException - if config_object is null, not a RecordMatchingQueryDef object, or if there are any errors processing its contents.

java.lang.IllegalStateException - if this object is already initialized.

java.lang.UnsupportedOperationException

getQuery

public com.netrics.likeit.NetricsQuery getQuery()
                                         throws java.lang.IllegalStateException,
                                                java.lang.Exception

Implement the qetQuery method for running in interpretive mode.

Specified by:

getQuery in class com.netrics.likeit.ANetricsCompoundQueryBuilder

Returns:

a query for the current field value settings.

Throws:

java.lang.IllegalStateException - if this object is not initialized, if this object uses any custom query classes, or if the field data is not set.

java.lang.Exception - on other errors.

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. This adds onto the standard functionality checking the underlying compound builder.

Overrides:

getCurItemName in class com.netrics.likeit.ANetricsCompoundQueryBuilder

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. This adds in applying the change to the underlying compound builder.

Overrides:

changeItemName in class com.netrics.likeit.ANetricsCompoundQueryBuilder

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.

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. This adds in getting types from the underlying compound query builder.

Overrides:

getUsedItemTypes in class com.netrics.likeit.ANetricsCompoundQueryBuilder

Returns:

the list of all unique item types used.

Throws:

java.lang.IllegalStateException - if features have not been established.

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. This adds getting item names from the underlying compound query builder.

Overrides:

getDefaultItemNames in class com.netrics.likeit.ANetricsCompoundQueryBuilder

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.

setFileMgr

public void setFileMgr(IQBPFileMgr file_manager)

Set the file manager used by this query builder. A file manager is used to enforce access restrictions on configuration files. It can also be used to enable reading of configuration data from non standard sources, such as a DBMS or a web-service.

Parameters:

file_manager - the file manager to use.

Throws:

java.lang.IllegalArgumentException - if file_manager is null.

generateSource

public boolean generateSource(java.io.File generated_source_directory,
                              AQBPLogger logger)
                       throws java.lang.IllegalArgumentException,
                              AQBPLogger.QBPException

Generate code for this query builder.

Parameters:

generated_source_directory - this is the root directory where the generated source is placed. This directory must exist. Source files are generated into sub-directories under this directory following standard java package directory conventions. The sub-directories are created as needed.

logger - a logger used to log all messages and errors.

Returns:

true if successful, false otherwise.

Throws:

java.lang.IllegalArgumentException - if any argument is null.

java.lang.IllegalStateException - if this object is not initialized.

AQBPLogger.QBPException - if exception mode is on and an error is encountered. Otherwise all errors are logged without throwing an exception.

installCustomClasses

public boolean installCustomClasses(java.io.File generated_class_directory,
                                    AQBPLogger logger)
                             throws java.lang.IllegalArgumentException,
                                    AQBPLogger.QBPException

Install the custom classes for this compound query builder. This copies all custom query classes into the class directory.

Parameters:

generated_class_directory - this is the root directory where the custom class files are placed. This directory must exist. Class files are copied into sub-directories under this directory following standard java package directory conventions. The sub-directories are created as needed.

logger - a logger used to log all messages and errors.

Returns:

true if successful, false otherwise.

Throws:

java.lang.IllegalArgumentException - if any argument is null.

AQBPLogger.QBPException - if exception mode is on and an error is encountered. Otherwise all errors are logged without throwing an exception.

outputRunTimeConfiguration

public boolean outputRunTimeConfiguration(java.io.File run_time_config_directory,
                                          java.io.File output_config_directory,
                                          AQBPLogger logger)
                                   throws java.lang.IllegalArgumentException,
                                          AQBPLogger.QBPException,
                                          AQBPLogger.QBPConfigException

Output the run time configuration files. This outputs all of the configuration files that are used by the generated query builders.

Parameters:

run_time_config_directory - the configurations output are set to reference other configuration files from this directory.

output_config_directory - configuration files that are needed at run time by the query builder classes generated are placed in this directory. The directory must exist.

logger - a logger used to log all messages and errors.

Returns:

true if successful, false otherwise.

Throws:

java.lang.IllegalArgumentException - if any argument is null.

AQBPLogger.QBPConfigException - if exception mode is on and the run time configuration object is invalid and can't be written out.

AQBPLogger.QBPException - if exception mode is on and an error is encountered. Otherwise all errors are logged without throwing an exception.

outputAnnotatedConfiguration

public static void outputAnnotatedConfiguration(com.tibco.patterns.qbp.jaxb.RecordMatchingQueryDef config_object,
                                                java.io.File annotated_config_file,
                                                AQBPLogger logger)
                                         throws java.lang.IllegalArgumentException,
                                                AQBPLogger.QBPException

Output an annotated input configuration file. The input configuration file may be annotated with messages. These are generally warning and error messages. This method outputs the annotated configuration file if there were notations. The notation count is kept in the logger passed in. It is assumed this is the same logger that was used when processing the configuration.

If the logger indicates notations were added an information message is output to the log noting the number of notations added. This is output regardless of whether the annotated file is output.

If an annotated configuration file is given, the configuration file is output to that file.

Info messages are logged to the given logger.

Parameters:

config_object - the annotated configuration object to be output.

annotated_config_file - if non-null and notes (normally errors) were added to the input configuration, the annotated configuration file is written to this file.

logger - a logger used to log all messages and errors.

Throws:

java.lang.IllegalArgumentException - if logger is null.

AQBPLogger.QBPException - if exception mode is on and an error is encountered. Otherwise all errors are logged without throwing an exception.

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Provide command line interface for generating query builders. The arguments expected are:

 java -jar TIB_tps_qbpcmd.jar <options>
 java -jar TIB_tps_qbpcmd.jar -help
 Options:
 -config-home config-home-dir
      All configuration files must reside under this directory.
      Optional.  Default is no restrictions on the location of
      configuration files.
 -class-home class-home-dir
      The class files for all dynamically loaded query builder
      classes must reside under this directory.
      Optional.  Default is to load classes only from the
      JVM class path.
 -def query-config-file
      Full path to the configuration file defining the query.
      Required.
 -adef annotated-config-file
      If there are errors in the query definition configuration,
      configuration with error annotations is output to here.
      Optional.  Default is to not output the annotated configuration.
 -parse-log log-file
      All log entries involved in parsing the configuration file
      and generating the source and run time files are sent to
      this file.
      Optional.  Default is to send log entries to the standard out.
 -run-log run-log-file
      All output associated with running queries is sent to
      this file.
      Optional.  Default is to send log entries to the standard out.
 -src root-directory-for-source
      If given, the Java source for the query builders defined in
      the configuration is output to this directory. The directory
      must exist.  The source is put in sub-directories as defined
      by the class package names.  The sub-directories are created
      as needed.
      Optional.  Default is to not generate source.
 -class root-directory-for-classes
      If given, the referenced user defined custom query classes
      are collected and placed under this directory.  The directory
      must exist.  The classes are put in sub-directories as
      defined by the class package names.  The sub-directories are
      created as needed.
      Optional.  Default is to not collect the classes.
 -output-config-dir output-configuration-directory
      If given, all configuration files used by the query builders
      are copied or generated into this directory.  The directory
      must exist.
      Optional.  Default is to not copy/generation the files.
 -run-config-dir run-time-configuration-directory
      The directory where configuration files are expected to reside
      in the run time environment for the query builders.  Output
      configuration files the reference other configuration files
      reference this directory.
      Optional.  Default is the output-configuration-directory.
 -run-queries query-run-configuration-file
      Run a set queries as defined by the query run configuration
      read from this file.
      Optional.  Default is to not run queries.
 -help
      If this flag is given the command outputs this usage
      message and terminates.
 

Parameters:

args - the command line arguments as described above.

Throws:

java.lang.Exception - on unrecoverable errors. Generally all errors are reported in the log file or standard out.