Project: stp

com.ibm.rational.stp.client.samples
Class QueryCommand

Object
  extended by com.ibm.rational.stp.client.samples.QueryUtilities
      extended by com.ibm.rational.stp.client.samples.QueryCommand

public class QueryCommand
extends QueryUtilities

A sample CM API application for defining and executing ClearQuest queries using a command-line interface. Command line arguments are

-name existing-query-location
Specifies an existing query to execute and possibly modify and save.
-save [new-query-location]
Specifies that the query is to be saved after definition or modification and before attempting execution. If no location is specified here it must be specified by a -name clause
-select display-field-specification+
Specifies the (new) display fields for the query. Requires either -from or -name
-from primary-record-type-location
Specifies the primary record type for the query. Requires either -select or -name. The -save location, if specified with -name, must be different from the -name location for this to be valid, since the primary type of an existing query cannot be changed.
-where filtering-expression-term*
Specifies the (new) filtering expression for the query. A -where clause with no filtering-expression-terms forces the query to be run without a filtering expression.
-min first-row-to-show
The first row of the result set to be displayed; defaults to 1, the first row. Must be positive.
-max last-row-to-show
the last row of the result set to be displayed; defaults to the last row. If zero, the number of rows found by the query will be reported.
-with filter-leaf-expression+
Specifies a value (and, optionally an operation) to fill in the dynamic filters of the query.
-count
Request a count of the number of rows matched by the query, even if not all rows are returned (as specified by the -max parameter)
The implementation is divided into four methods: collectArgs, buildQuery, executeQuery, and printResults. As a sample CM API application, the buildQuery and executeQuery methods are the most instructive. To make the example realistic, a syntax for specifying display fields and filters on the command line was contrived. The parsing of this representation is implemented in the QueryUtilities class.


Field Summary
private static CqProvider g_provider
          The CqProvider instance used by the class and its instances
private static String g_repo
          The target ClearQuest user database, derived from command-line input
(package private)  CqQuery.ListOptions m_countRows
          Whether or not to count all rows: set by presence of -count
(package private)  long m_max
          -max operand: The last row of the result set to return
(package private)  long m_min
          -min operand: The first row of the result set to return
(package private)  com.ibm.rational.wvcm.stp.StpLocation m_oldName
          -name operand: The name of an existing query
(package private)  com.ibm.rational.wvcm.stp.StpLocation m_primaryType
          -from operand: the CqRecordType defining the type of records to query
(package private)  com.ibm.rational.wvcm.stp.StpLocation m_saveName
          -save operand: the name under which the query is to be saved
(package private)  List<String> m_select
          -select operand: Used to build the DisplayField[] for the query
(package private)  List<String> m_where
          -where operand: Used to build the filtering expression for the query
(package private)  List<String> m_with
          -with operand: Used to build the FilterLeaf[] for query parameters
private static javax.wvcm.PropertyRequestItem.PropertyRequest QUERY_PROPERTIES
           
 
Fields inherited from class com.ibm.rational.stp.client.samples.QueryUtilities
RECORD_TYPE_WITH_FIELDS
 
Constructor Summary
QueryCommand()
           
 
Method Summary
(package private)  CqQuery buildQuery()
          Constructs a CqQuery proxy in which the query specification data presented on the command line is stored.
(package private)  void collectArgs(String[] args)
          Collects the command-line arguments into object fields.
private  String describe(CqQuery query)
          Assembles a String containing information about the query executed.
(package private)  CqResultSet executeQuery(CqQuery input)
          Executes the constructed query.
private static List<String> getArgList(ListIterator<String> args)
          Collects the arguments in the command line upto, but not including, the first argument that begins with "-"
static void main(String[] args)
           
(package private)  void printResults(CqQuery query, CqResultSet results)
          Display the rows returned by the query on the console
(package private)  void run(String[] args)
           
private static com.ibm.rational.wvcm.stp.StpLocation toSelector(com.ibm.rational.wvcm.stp.StpLocation.Namespace namespace, String str)
          Converts command-line input specifying a resource into an StpLocation, adding domain and namespace if omitted by the user
 
Methods inherited from class com.ibm.rational.stp.client.samples.QueryUtilities
parseDisplayField, parseDynamicFilter, parseFilter, parseFilterLeaf
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

g_provider

private static CqProvider g_provider
The CqProvider instance used by the class and its instances


g_repo

private static String g_repo
The target ClearQuest user database, derived from command-line input


m_oldName

com.ibm.rational.wvcm.stp.StpLocation m_oldName
-name operand: The name of an existing query


m_saveName

com.ibm.rational.wvcm.stp.StpLocation m_saveName
-save operand: the name under which the query is to be saved


m_primaryType

com.ibm.rational.wvcm.stp.StpLocation m_primaryType
-from operand: the CqRecordType defining the type of records to query


m_select

List<String> m_select
-select operand: Used to build the DisplayField[] for the query


m_where

List<String> m_where
-where operand: Used to build the filtering expression for the query


m_with

List<String> m_with
-with operand: Used to build the FilterLeaf[] for query parameters


m_min

long m_min
-min operand: The first row of the result set to return


m_max

long m_max
-max operand: The last row of the result set to return


m_countRows

CqQuery.ListOptions m_countRows
Whether or not to count all rows: set by presence of -count


QUERY_PROPERTIES

private static final javax.wvcm.PropertyRequestItem.PropertyRequest QUERY_PROPERTIES
Constructor Detail

QueryCommand

public QueryCommand()
Method Detail

collectArgs

void collectArgs(String[] args)
           throws javax.wvcm.WvcmException
Collects the command-line arguments into object fields. Variables for unspecified arguments are left at their initial value. As the arguments are collected, the resource names are converted to a complete CM API StpLocation and from that the targeted ClearQuest database is determined.

Parameters:
args - A String array containing the command-line arguments
Throws:
javax.wvcm.WvcmException - if StpLocation objects cannot be constructed from the resource names on the command line.

buildQuery

CqQuery buildQuery()
             throws javax.wvcm.WvcmException
Constructs a CqQuery proxy in which the query specification data presented on the command line is stored. If -save was specified, the proxy will use that location since the query will be executed from that location. If -save was not specified but -name was, then that location is used since either the results will come directly from the named query or the query will be done anonymously; Otherwise, a dummy location is used.

Throws:
javax.wvcm.WvcmException

executeQuery

CqResultSet executeQuery(CqQuery input)
                   throws javax.wvcm.WvcmException
Executes the constructed query.

At this point, if the user followed the rules, we should be able to execute the query. If -save was specified, we need to define the query in the database and then use doExecute to get the results. If an existing query is being executed unmodified, then we use doExecute as well; Otherwise we use CqRecordType.doQuery() passing the data from the command line to ClearQuest.

Throws:
javax.wvcm.WvcmException

printResults

void printResults(CqQuery query,
                  CqResultSet results)
            throws javax.wvcm.WvcmException
Display the rows returned by the query on the console

Parameters:
query - The query that was executed.
results - The CqResultSet containing the rows of the result set.
Throws:
javax.wvcm.WvcmException - If interactions with the server fail or have failed to obtained the necessary information.

describe

private String describe(CqQuery query)
                 throws javax.wvcm.WvcmException
Assembles a String containing information about the query executed.

Parameters:
query - A CqQuery proxy for the query to be described. Must define the DISPLAY_FIELDS, PRIMARY_RECORD_TYPE, and FILTERING properties if the query has not been saved; USER_FRIENDLY_LOCATION, otherwise.
Returns:
A String containing the name of the query if saved or a stylized SQL select statement describing the query if not.
Throws:
javax.wvcm.WvcmException

run

void run(String[] args)
   throws javax.wvcm.WvcmException
Throws:
javax.wvcm.WvcmException

main

public static void main(String[] args)
                 throws Exception
Parameters:
args -
Throws:
Exception

getArgList

private static List<String> getArgList(ListIterator<String> args)
Collects the arguments in the command line upto, but not including, the first argument that begins with "-"

Parameters:
args - The command line argument iterator positioned on the argument that precedes the arguments to be collected. Must not be null.
Returns:
A List of the collected arguments. Will not be null, but may be empty.

toSelector

private static com.ibm.rational.wvcm.stp.StpLocation toSelector(com.ibm.rational.wvcm.stp.StpLocation.Namespace namespace,
                                                                String str)
                                                         throws javax.wvcm.WvcmException
Converts command-line input specifying a resource into an StpLocation, adding domain and namespace if omitted by the user

Parameters:
namespace - The expected namespace for the location. Must not be null.
str - The location as input by the user. Expect simple name and possibly repository information. Must not be null.
Returns:
An StpLocation specifying the same resource as the given string argument based on context.
Throws:
javax.wvcm.WvcmException

Generated Fri 16-Sep-2011 02:10 AM

Copyright © IBM 2011. All rights reserved.