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 * (C) 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
014package com.ibm.rational.wvcm.stp.cq;
015
016import javax.wvcm.WvcmException;
017
018import 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 */
024public 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}