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, 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 }