Project: stp

com.ibm.rational.wvcm.stp.cq
Interface CqQuery

All Superinterfaces:
CqContextResource, CqQueryFolderItem, CqResource, CqUserDbMember, Resource, StpResource

public interface CqQuery
extends CqQueryFolderItem

A proxy interface for ClearQuest query and chart resources.

The user-friendly specification for the location of a query or chart has the form

  cq.query:<parent-folder-path>/<query-name>@<db-set>/<user-db>
 
where <parent-folder-path> is a sequence of one or more path segments separated by the slash character, wherein each segment denotes a query folder immediately contained by its predecessor in the sequence. The first segment is either "Public Queries" or "Personal Queries" (or the localization of one of these).


Nested Class Summary
static interface CqQuery.ChartOptions
          An extension of the CommonOptions interface specifying an additional set of parameters applying only to the generation of charts.
static class CqQuery.ChartOptionsClass
          Instances of this class provide the default values for each attribute specified by the ChartOptions interface, which is the same behavior exhibited when using null for a ChartOptions object.
static interface CqQuery.CommonOptions
          An interface specifying a set of optional parameters that may be passed to CqQuery.doExecute, CqQuery.doMakeChart, CqRecordType.doQuery, or CqReport.doMakeReport to control the execution of queries and the generation of charts and reports.
static interface CqQuery.DisplayField
          The description of a column of the result set generated by a query.
static interface CqQuery.FileOptions
          An interface through which a client may, optionally, specify values for various attributes that control the behavior of executing a query to a stream.
static class CqQuery.FileOptionsClass
          Instances of this class provide the default values for each attribute specified by the FileOptions interface, which is the same behavior exhibited when using null for a FileOptions parameter.
static interface CqQuery.Filter
          A query filter expression or a subexpression thereof.
static interface CqQuery.FilterLeaf
          A field/value comparison within a query filter expression; the leaf of a query filter expression.
static interface CqQuery.FilterNode
          The conjunction or disjunction of subexpressions within a query filter expression.
static interface CqQuery.ListOptions
          An extension of the CommonOptions interface specifying an additional set of parameters applying only to the generation of query result sets.
static class CqQuery.ListOptionsClass
          Instances of this class provide the default values for each attribute specified by the ListOptions interface, which is the same behavior exhibited when using null for a ListOptions object.
static class CqQuery.QueryType
          An enumeration of the possible types of queries.
 
Nested classes/interfaces inherited from interface CqQueryFolderItem
CqQueryFolderItem.OverwriteMode
 
Nested classes/interfaces inherited from interface com.ibm.rational.wvcm.stp.StpResource
StpResource.UnsupportedProperty
 
Nested classes/interfaces inherited from interface javax.wvcm.Resource
Resource.CopyFlag
 
Field Summary
static CqQuery.ListOptions COUNT_ROWS
          An instance of ListOptions that enables the row count option for a query execution.
static PropertyNameList.PropertyName<CqQuery.DisplayField[]> DISPLAY_FIELDS
          An array containing a DisplayField structure for each column of the result set generated by this query.
static PropertyNameList.PropertyName<CqQuery.FilterLeaf[]> DYNAMIC_FILTERS
          An array containing a FilterLeaf structure for each of the query's dynamic filters.
static PropertyNameList.PropertyName<CqQuery.Filter> FILTERING
          A Filter node representing the logical expression that is used to filter records to form each row of the result set.
static PropertyNameList.PropertyName<Boolean> IS_AGGREGATED
          Whether or not any fields of the query are aggregated.
static PropertyNameList.PropertyName<Boolean> IS_MULTITYPE
          Whether or not the query is defined on a family of record types as opposed to being defined on a single record type.
static PropertyNameList.PropertyName<Boolean> IS_SQL_GENERATED
          Whether or not SQL has been generated for the query
static CqQuery.ChartOptions PNG_CHART
          An instance of ChartOptions that requests the chart in PNG format.
static PropertyNameList.PropertyName<CqRecordType> PRIMARY_RECORD_TYPE
          The record type of the records that are targeted by the query.
static PropertyNameList.PropertyName<CqQuery.QueryType> QUERY_TYPE
          Whether this query generates a list, report, or chart
static PropertyNameList.PropertyName<String> SQL
          The SQL associated with the query.
static CqFieldDefinition[] UNIQUE_KEY_FIELD_PATH
          A special field path token designating the aggregated key fields of a ClearQuest record, for use in specifying query filters and display fields.
 
Fields inherited from interface CqQueryFolderItem
CAN_UPDATE_OR_DELETE, CQ_MASTER_REPLICA, IS_SITE_EXTENDED_NAME_REQUIRED, QUERY_FOLDER, SITE_EXTENDED_NAME, SITE_EXTENDED_NAMES
 
Fields inherited from interface CqContextResource
IS_MODIFIED
 
Fields inherited from interface CqUserDbMember
DB_SET, USER_DB
 
Fields inherited from interface com.ibm.rational.wvcm.stp.StpResource
ALL_PROPERTIES, AUTHENTICATION_REALM, CREATOR_GROUP_NAME, CREATOR_LOGIN_NAME, EFFICIENT_LOCATION, INVALID_PROPERTIES, REPOSITORY, STABLE_LOCATION, USER_FRIENDLY_LOCATION
 
Fields inherited from interface javax.wvcm.Resource
ALL_CUSTOM_PROPERTIES, COMMENT, CONTENT_CHARACTER_SET, CONTENT_IDENTIFIER, CONTENT_LANGUAGE, CONTENT_LENGTH, CONTENT_TYPE, CREATION_DATE, CREATOR_DISPLAY_NAME, DISPLAY_NAME, IS_EXECUTABLE, LAST_MODIFIED, PARENT_LIST, PATHNAME_LOCATION, PROVIDER_LIST, RESOURCE_IDENTIFIER, WORKSPACE_FOLDER_LIST
 
Method Summary
 long columnNumber(String label)
          Returns the position/column number of the display field having the given label.
 CqQuery doCreateQuery(Feedback feedback)
          Creates a new query at the location specified by this proxy and delivers it to the database.
 CqQuery doCreateQuery(Feedback feedback, List<CqContextResource> deliveryOrder)
          Creates a new query at the location specified by this proxy and delivers it to the database.
 CqQuery doExecute(File results, Feedback feedback, CqQuery.FileOptions options, CqQuery.FilterLeaf... dynamicFilters)
          Executes this query and writes the result set to a text file
 CqResultSet doExecute(long targetRow, long maxRows, CqQuery.ListOptions options, CqQuery.FilterLeaf... dynamicFilters)
          Executes this query on the server and returns rows of the result set as requested.
 CqQuery doMakeChart(OutputStream chartImage, Feedback feedback, CqQuery.ChartOptions options, CqQuery.FilterLeaf... dynamicFilters)
          Executes this query and formats the results into a chart.
 CqQuery.DisplayField[] getDisplayFields()
          Returns the value of the DISPLAY_FIELDS property as defined by this proxy.
 CqQuery.FilterLeaf[] getDynamicFilters()
          Returns the value of the DYNAMIC_FILTERS property as defined by this proxy.
 CqQuery.Filter getFiltering()
          Returns the value of the FILTERING property as defined by this proxy.
 boolean getIsAggregated()
          Returns the value of the IS_AGGREGATED property as defined by this proxy.
 boolean getIsMultitype()
          Returns the value of the IS_MULTITYPE property as defined by this proxy.
 boolean getIsSqlGenerated()
          Returns the value of the IS_SQL_GENERATED property as defined by this proxy.
 CqRecordType getPrimaryRecordType()
          Returns the value of the PRIMARY_RECORD_TYPE property as defined by this proxy.
 CqQuery.QueryType getQueryType()
          Returns the value of the QUERY_TYPE property as defined by this proxy.
 String getSql()
          Returns the value of the SQL property as defined by this proxy.
 void setDisplayFields(CqQuery.DisplayField... displayFields)
          Defines a new value for the DISPLAY_FIELDS property of this proxy.
 void setFiltering(CqQuery.Filter filter)
          Defines a new value for the FILTERING property of this proxy.
 void setPrimaryRecordType(CqRecordType primaryRecordType)
          Defines a new value for the PRIMARY_RECORD_TYPE property of this proxy.
 void setSql(String sql)
          Defines a new value for the SQL property of this proxy.
 
Methods inherited from interface CqQueryFolderItem
doCopy, doCopy, doMove, doMove, getCanUpdateOrDelete, getCqMasterReplica, getIsSiteExtendedNameRequired, getQueryFolder, getSiteExtendedName, getSiteExtendedNames, setCqMasterReplica
 
Methods inherited from interface CqContextResource
doDeliver, doRevert, doUnbindAll, doUnbindAll, doWriteProperties, doWriteProperties, getIsModified
 
Methods inherited from interface CqUserDbMember
getDbSet, getUserDb
 
Methods inherited from interface CqResource
cqProvider, getComment, getContentCharacterSet, getContentIdentifier, getContentLanguage, getContentLength, getContentType, getCreationDate, getCreatorDisplayName, getCreatorGroupName, getCreatorLoginName, getIsExecutable, getLastModified, getProviderList, getWorkspaceFolderList, setComment, setContentCharacterSet, setContentLanguage, setContentType, setCreatorDisplayName, setIsExecutable
 
Methods inherited from interface com.ibm.rational.wvcm.stp.StpResource
doReadProperties, equals, getAllProperties, getAuthenticationRealm, getCustomProperties, getEfficientLocation, getInvalidProperties, getMetaProperties, getPropertyException, getRepository, getResourceError, getResourceIdentifier, getStableLocation, getUserFriendlyLocation, hashCode, hasProperties, initMetaProperty, proxyType, stpLocation, stpProvider
 
Methods inherited from interface javax.wvcm.Resource
doCopy, doFind, doFindAll, doGetPropertyNameList, doGetPropertyNameList, doReadContent, doReadProperties, doWriteContent, forgetProperty, getDisplayName, getParentList, getPathnameLocation, getProperty, initProperty, location, lookupProperty, modifyLocation, propertyNameList, provider, removeProperty, setDisplayName, setProperty, setProperty, updatedPropertyNameList
 

Field Detail

COUNT_ROWS

static final CqQuery.ListOptions COUNT_ROWS
An instance of ListOptions that enables the row count option for a query execution. Provided as a convenience for specifying this commonly used option.


DISPLAY_FIELDS

static final PropertyNameList.PropertyName<CqQuery.DisplayField[]> DISPLAY_FIELDS
An array containing a DisplayField structure for each column of the result set generated by this query.


DYNAMIC_FILTERS

static final PropertyNameList.PropertyName<CqQuery.FilterLeaf[]> DYNAMIC_FILTERS
An array containing a FilterLeaf structure for each of the query's dynamic filters. This property is computed from the PROMPTED leaves of the filter defined by the FILTERING property.


FILTERING

static final PropertyNameList.PropertyName<CqQuery.Filter> FILTERING
A Filter node representing the logical expression that is used to filter records to form each row of the result set.


IS_AGGREGATED

static final PropertyNameList.PropertyName<Boolean> IS_AGGREGATED
Whether or not any fields of the query are aggregated.


IS_MULTITYPE

static final PropertyNameList.PropertyName<Boolean> IS_MULTITYPE
Whether or not the query is defined on a family of record types as opposed to being defined on a single record type.


IS_SQL_GENERATED

static final PropertyNameList.PropertyName<Boolean> IS_SQL_GENERATED
Whether or not SQL has been generated for the query


PNG_CHART

static final CqQuery.ChartOptions PNG_CHART
An instance of ChartOptions that requests the chart in PNG format. Provided as a convenience for specifying this commonly used option.


PRIMARY_RECORD_TYPE

static final PropertyNameList.PropertyName<CqRecordType> PRIMARY_RECORD_TYPE
The record type of the records that are targeted by the query.


QUERY_TYPE

static final PropertyNameList.PropertyName<CqQuery.QueryType> QUERY_TYPE
Whether this query generates a list, report, or chart


SQL

static final PropertyNameList.PropertyName<String> SQL
The SQL associated with the query.


UNIQUE_KEY_FIELD_PATH

static final CqFieldDefinition[] UNIQUE_KEY_FIELD_PATH
A special field path token designating the aggregated key fields of a ClearQuest record, for use in specifying query filters and display fields.

Method Detail

columnNumber

long columnNumber(String label)
                  throws WvcmException
Returns the position/column number of the display field having the given label. Requires that the DISPLAY_FIELDS property is defined for this proxy.

Parameters:
label - A String containing the column label for the desired display field.
Returns:
0 if the label cannot be found amongst the visible display fields of the query; otherwise the ordinal position of the display field among the columns of the result set.
Throws:
WvcmException - If the DISPLAY_FIELDS property is not defined for this proxy.

doCreateQuery

CqQuery doCreateQuery(Feedback feedback)
                      throws WvcmException
Creates a new query at the location specified by this proxy and delivers it to the database. This proxy must define the PRIMARY_RECORD_TYPE property and one of the properties DISPLAY_FIELDS or SQL.

Parameters:
feedback - Requests the properties desired in the proxy returned by this operation.
Returns:
A proxy for the newly created query populated with the properties requested by the feedback argument.
Throws:
WvcmException - If a resource already exists at the location defined by this proxy or if the new query cannot be delivered to the database for any number of reasons.

doCreateQuery

CqQuery doCreateQuery(Feedback feedback,
                      List<CqContextResource> deliveryOrder)
                      throws WvcmException
Creates a new query at the location specified by this proxy and delivers it to the database. This proxy must always define the PRIMARY_RECORD_TYPE property. At least one of the properties DISPLAY_FIELDS or SQL must be defined if the new query is to be delivered to the database.

Parameters:
feedback - Requests the properties desired in the proxy returned by this operation.
deliveryOrder - A deliver order list specifying the resources to be delivered to the database after this resource is successfully created.
Returns:
A proxy for the newly created query populated with the properties requested by the feedback argument.
Throws:
WvcmException - If a resource already exists at the location defined by this proxy or if the resources specified by the deliveryOrder argument cannot be delivered to the database.

doExecute

CqQuery doExecute(File results,
                  Feedback feedback,
                  CqQuery.FileOptions options,
                  CqQuery.FilterLeaf... dynamicFilters)
                  throws WvcmException
Executes this query and writes the result set to a text file

Parameters:
results - The File into which the result set is to be written. Must not be null.
feedback - A Feedback instance specifying properties to be returned from the operation in the CqQuery proxy. May be null.
options - A StreamOptions instance specifying various options to control the format of the generated output.
dynamicFilters - Some queries require selected portions of the filter to be specified dynamically at the time the query is executed. These filter values must be specified in the dynamicFilters vector in the order defined by the query. See Query#DYNAMIC_FILTERS. May be null if the query has no parameters.
Returns:
A CqQuery proxy for the query that was executed, populated with the property values requested by the feedback parameter.
Throws:
WvcmException

doExecute

CqResultSet doExecute(long targetRow,
                      long maxRows,
                      CqQuery.ListOptions options,
                      CqQuery.FilterLeaf... dynamicFilters)
                      throws WvcmException
Executes this query on the server and returns rows of the result set as requested.

Parameters:
targetRow - The 1-based index of a row of the result set that must be included in the response to this request. The target row values will be the values returned in the first RowData object of the iterator.
maxRows - The maximum number of rows of the result set that should be included in the response to this request. A value of Long.MAX_VALUE will request all rows in the result set; If this parameter is 0, no rows are requested. If the query does not generate all of the rows requested, it is not an error.
options - An instance of ListOptions that specifies optional attributes for controlling the performance of the query or its response. May be null, in which case server-specified values will be used for each attribute.
dynamicFilters - Some queries require selected portions of the filter to be specified dynamically at the time the query is executed. These filter values must be specified in the dynamicFilters vector in the order defined by the query. See Query#DYNAMIC_FILTERS. May be null if the query has no parameters.
Returns:
A CqResultSet presenting the rows of the result set in the order returned by the query.
Throws:
WvcmException - if any errors occur during the execution of the query or the formation of the response.

doMakeChart

CqQuery doMakeChart(OutputStream chartImage,
                    Feedback feedback,
                    CqQuery.ChartOptions options,
                    CqQuery.FilterLeaf... dynamicFilters)
                    throws WvcmException
Executes this query and formats the results into a chart.

Parameters:
chartImage - An OutputStream to which the generated chart image will be written.
feedback - A Feedback instance specifying properties to be returned from the operation in the CqQuery proxy. May be null.
options - A ChartOptions object specifying the attributes of the generated chart.
dynamicFilters - Any dynamic filters needed to execute the query.
Returns:
A proxy for this query populated with the properties specified by the Feedback argument.
Throws:
WvcmException - Thrown if the chart cannot be generated as requested.

getDisplayFields

CqQuery.DisplayField[] getDisplayFields()
                                        throws WvcmException
Returns the value of the DISPLAY_FIELDS property as defined by this proxy.

Returns:
An array of DisplayField structures describing the columns of the result set generated by the query.
Throws:
WvcmException - if this proxy does not define a value for the DISPLAY_FIELDS property.

getDynamicFilters

CqQuery.FilterLeaf[] getDynamicFilters()
                                       throws WvcmException
Returns the value of the DYNAMIC_FILTERS property as defined by this proxy.

Returns:
An array of FilterLeaf objects, each representing one of the dynamic filters defined for this query. An empty array if the query's filtering expression has no PROMPTED FieldLeaf instances.
Throws:
WvcmException - if this proxy does not define a value for the DYNAMIC_FILTERS property.

getFiltering

CqQuery.Filter getFiltering()
                            throws WvcmException
Returns the value of the FILTERING property as defined by this proxy.

Returns:
A Filter object representing the filter expression defined by this query definition. Will never be null.
Throws:
WvcmException - if this proxy does not define a value for the FILTERING property.

getIsAggregated

boolean getIsAggregated()
                        throws WvcmException
Returns the value of the IS_AGGREGATED property as defined by this proxy.

Returns:
true if this query contains any aggregated display fields; false otherwise.
Throws:
WvcmException - if this proxy does not define a value for the IS_AGGREGATED property.

getIsMultitype

boolean getIsMultitype()
                       throws WvcmException
Returns the value of the IS_MULTITYPE property as defined by this proxy.

Returns:
true if this query is defined on a family of record types; false if it is defined on a single record type.
Throws:
WvcmException - if this proxy does not define a value for the IS_MULTITYPE property.

getIsSqlGenerated

boolean getIsSqlGenerated()
                          throws WvcmException
Returns the value of the IS_SQL_GENERATED property as defined by this proxy.

Returns:
true if SQL has been generated for this query; false if the SQL has been provided by the user.
Throws:
WvcmException - if this proxy does not define a value for the IS_SQL_GENERATED property.

getPrimaryRecordType

CqRecordType getPrimaryRecordType()
                                  throws WvcmException
Returns the value of the PRIMARY_RECORD_TYPE property as defined by this proxy.

Returns:
A CqRecordType proxy for the primary resource type of this query. Will never be null.
Throws:
WvcmException - if this proxy does not define a value for the PRIMARY_RECORD_TYPE property.

getQueryType

CqQuery.QueryType getQueryType()
                               throws WvcmException
Returns the value of the QUERY_TYPE property as defined by this proxy.

Returns:
A QueryType enumerator identifying the type of this query.
Throws:
WvcmException - if this proxy does not define a value for the QUERY_TYPE property.

getSql

String getSql()
              throws WvcmException
Returns the value of the SQL property as defined by this proxy.

Returns:
A String containing the SQL statement for this query.
Throws:
WvcmException - if this proxy does not define a value for the SQL property.

setDisplayFields

void setDisplayFields(CqQuery.DisplayField... displayFields)
Defines a new value for the DISPLAY_FIELDS property of this proxy.

Parameters:
displayFields - An array of DisplayField objects representing the new display fields of the query.

setFiltering

void setFiltering(CqQuery.Filter filter)
Defines a new value for the FILTERING property of this proxy.

Parameters:
filter - A Filter object representing the new filtering to be used in this query definition.

setPrimaryRecordType

void setPrimaryRecordType(CqRecordType primaryRecordType)
Defines a new value for the PRIMARY_RECORD_TYPE property of this proxy.

Parameters:
primaryRecordType - A CqRecordType object representing the new primary record type for this query definition.

setSql

void setSql(String sql)
Defines a new value for the SQL property of this proxy.

Parameters:
sql - A String object containing the SQL statement for the query.

Generated Fri 14-Jan-2011 09:44 PM

Copyright © IBM 2011. All rights reserved.