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    }