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
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 import 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 */
044 public 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 }