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