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 }