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    }