001/*
002 * file CqResultSet.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM 
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqResultSet
008 *
009 * (C) Copyright IBM Corporation 2007, 2013.  All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
011 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
012 */
013
014package com.ibm.rational.wvcm.stp.cq;
015
016import java.util.Iterator;
017
018import com.ibm.rational.wvcm.stp.StpReleasable;
019import com.ibm.rational.wvcm.stp.cq.CqQuery.DisplayField;
020import com.ibm.rational.wvcm.stp.cq.CqQuery.DisplayField.FieldType;
021import com.ibm.rational.wvcm.stp.cq.CqQuery.DisplayField.SortType;
022
023
024/**
025 * An interface specifying the structure returned by CqQuery.doExecute and
026 * CqRecordType.doQuery to represent the results of executing a ClearQuest
027 * query.
028 * <p>
029 * A CqResultSet is an Iterable as well as an Iterator. Each invocation of its
030 * iterator() method <i>does not</i> restart the iteration. It just continues
031 * from the last read row. That is CqResultSet.iterator() simply returns the
032 * CqResultSet object. It is provided to allow the use of CqResultSet objects in
033 * the Java 5 for-each construct.
034 * 
035 * @see CqQuery#doExecute(long, long,
036 *      com.ibm.rational.wvcm.stp.cq.CqQuery.ListOptions,
037 *      com.ibm.rational.wvcm.stp.cq.CqQuery.FilterLeaf[])
038 * @see CqRecordType#doQuery(String, long, long,
039 *      com.ibm.rational.wvcm.stp.cq.CqQuery.ListOptions)
040 * @see CqRecordType#doQuery(com.ibm.rational.wvcm.stp.cq.CqQuery.DisplayField[],
041 *      com.ibm.rational.wvcm.stp.cq.CqQuery.Filter, long, long,
042 *      com.ibm.rational.wvcm.stp.cq.CqQuery.ListOptions)
043 */
044public interface CqResultSet extends StpReleasable, Iterator<CqRowData>,
045                Iterable<CqRowData>
046{
047    /**
048     * @return A String[] containing the label defined for each column of the
049     * result set.
050     */
051    String[] getColumnLabels();
052
053    /**
054     * @return A FieldType[] containing FieldType enumerators that specify the
055     *         type of data returned in each column of the result set. In the
056     *         result set generated by a raw SQL query the column type is
057     *         inferred from the database data type and not a field definition.
058     *         Thus, in this case, only the following generic FieldType
059     *         enumerators are used in this array: BINARY, SHORT_STRING,
060     *         MULTILINE_STRING, INTEGER, FLOAT, and DATE_TIME.
061     */
062    FieldType[] getColumnTypes();
063
064    /**
065     * @return A SortType array containing SortType enumerators that specify
066     *         the sort type for each column of the result set.
067     */
068    SortType[] getColumnSortTypes();
069    
070    /**
071     * @return A Long array containing the sort order for each column of the
072     *         the result set.
073     */
074    Long[] getColumnSortOrders();
075    
076    /**
077     * @return A String containing the query expressed as a vendor-specific SQL
078     *         select statement.
079     */
080    String getSql();
081
082    /**
083     * The total number of rows found by the query in the database. This value
084     * is available only if requested when the query was executed and this
085     * result set was generated. If computed, this number would be the upper
086     * bound on the number of CqRowData elements to expect in this result set.
087     * The actual content of the iterator may be less or even empty depending
088     * on the options specified for the execution of the query.
089     * 
090     * @return If a row count was requested, the total number of rows found by
091     * the query in the database; if a row count was not requested, -1.
092     * 
093     * @see CqQuery.ListOptions#getEnableRowCount()
094     */
095    long getRowCount();
096
097    /**
098     * @return The absolute upper bound on the maximum row number that can be
099     * returned by a query. This value is established by the ClearQuest database
100     * administrator and cannot be changed via this API.
101     */
102    long getRowNumberHardLimit();
103
104    /**
105     * @return The default upper bound on the maximum row number that can be
106     *         returned by a query. This value is established by the ClearQuest
107     *         database administrator. It can be overridden by defining
108     *         {@link CqQuery.CommonOptions#getRowNumberLimit()} to return the
109     *         overriding value.
110     */
111    long getRowNumberSoftLimit();
112
113    /**
114     * @return Answers whether or not a row number generated by the query
115     *         exceeded the smaller of
116     *         <ul>
117     *         <li><code>ListOption.getRowNumberLimit()</code> (which
118     *         defaults to <code>getRowNumberSoftLimit()</code>)
119     *         <li><code>getRowNumberHardLimit()</code>
120     *         </ul>. Note that the value returned by this method does not
121     *         indicate whether or not the <code>maxRows</code> limit was
122     *         exceeded.
123     * 
124     * @see CqQuery.ListOptions#getRowNumberLimit()
125     */
126    boolean isRowNumberLimitExceeded();
127
128    /**
129     * @return whether primary record type is stateless.
130     */
131    boolean getIsStateless();
132    
133    /**
134     * @return whether query is SQL generated.
135     */
136    boolean getIsSQLGenerated();
137    
138    /**
139     * Returns a CqQuery proxy for the query that was executed to generate this
140     * result set. It is available only from CqQuery.doExecute and only if the
141     * ListOptions passed to that method defined
142     * ListOptions.getQueryPropertyRequest() to return a non-null
143     * PropertyRequest.
144     * 
145     * @return If CqQuery.ListOptions.getQueryPropertyRequest() was not 
146     *         <b>null</b>, a proxy for the executed query populated with the 
147     *         requested properties; otherwise <b>null</b>.
148     * 
149     * @see CqQuery.ListOptions#getQueryPropertyRequest()
150     */
151    CqQuery getQuery();
152}