001    /*
002     * file CqRowData.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cq.CqRowData
008     *
009     * © Copyright IBM Corporation 2004, 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 javax.wvcm.WvcmException;
017    
018    import com.ibm.rational.wvcm.stp.StpActivity;
019    
020    /**
021     * The interface for a row of a result set generated by the execution of a
022     * query.
023     */
024    public interface CqRowData
025    {
026        /**
027         * Returns the ordinal position of this row in the result set.
028         * 
029         * @return A positive integer specifying the row number of this row within
030         *         the result set generated by the query. (The first row is row
031         *         number 1.)
032         */
033        public long getRowNumber();
034    
035        /**
036         * The unique String instance used to represent the string image of a null
037         * field.
038         */
039        String NULL_IMAGE = "";
040    
041        /**
042         * Returns the raw data for the row in column order as string images. The
043         * data items correlate with the visible DisplayFields of the query that
044         * generated this row.
045         * <p>
046         * In this presentation all values are strings containing the image of the
047         * field.
048         * 
049         * @return A homogeneous array of String objects
050         */
051        public String[] getStrings();
052    
053        /**
054         * Returns the data for the row as native Java objects in column order. The
055         * data items correlate with the visible DisplayFields of the query that
056         * generated this row.
057         * <p>
058         * The extent to which the raw string values of the row are converted to
059         * Java objects depends on the DisplayField information made available to
060         * the query operation. For queries defined by a DisplayField[], the default
061         * is to use the defining DisplayField[] to convert all images to a native
062         * Java object appropriate to the type of data displayed in the column. For
063         * SQL-based queries, the default action is to use the types returned by
064         * {@link CqResultSet#getColumnTypes()}
065         * <p>
066         * Clients can alter the default conversion behavior by providing an
067         * alternative DisplayField[] to use for conversion as the value returned by
068         * the
069         * {@link com.ibm.rational.wvcm.stp.cq.CqQuery.ListOptions#getValueConversionData() ListOptions#getValueConversionData()}
070         * method.
071         * <p>
072         * In all cases, conversion of row data is not attempted until this method
073         * is invoked.
074         * 
075         * @return A heterogeneous array of Java object types, including proxy
076         *         objects, and nulls, representing the data in one row of a result
077         *         set.
078         * 
079         * @see com.ibm.rational.wvcm.stp.cq.CqQuery.ListOptions#getValueConversionData()
080         */
081        public Object[] getValues();
082    
083        /**
084         * Returns a proxy for the resource from which the fields of this row were
085         * generated.
086         * <p>
087         * NOTE This method will return a non-null value only if row data contains a
088         * field of the primary record of type CqFieldValue.ValueType.ID or
089         * CqFieldValue.ValueType.DBID. If both fields are defined, the ID field is
090         * chosen to create the record's user-friendly location. Also, the ID or
091         * DBID field must not have had an "aggregate" operation applied to it. For
092         * queries on a record-type family, a field of type RECORD_TYPE must also be
093         * present.
094         * <p>
095         * To obtain a proxy from row data generated by a SQL-based query, the
096         * required DisplayField information must have been be provided by the
097         * client to the query operation by overriding the default definition of
098         * ListOptions.getValueConversionData(). For queries defined by a
099         * DisplayField[], the value will be available regardless of the conversion
100         * level in effect, provided the row data contains the necessary fields for
101         * generation of the resource location.
102         * 
103         * @return A CqRecord proxy for the record from which the fields of this row
104         *         were computed; <b>null</b> if the record location cannot be
105         *         determined.
106         */
107        public StpActivity getRecord() throws WvcmException;
108    }