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 }