Package 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 | 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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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.