xref: /trunk/main/offapi/com/sun/star/sdbc/XResultSet.idl (revision ffd38472365e95f6a578737bc9a5eb0fac624a86)

/**************************************************************
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/


#ifndef __com_sun_star_sdbc_XResultSet_idl__
#define __com_sun_star_sdbc_XResultSet_idl__

#ifndef __com_sun_star_uno_XInterface_idl__
#include <com/sun/star/uno/XInterface.idl>
#endif

#ifndef __com_sun_star_sdbc_SQLException_idl__
#include <com/sun/star/sdbc/SQLException.idl>
#endif

 module com {  module sun {  module star {  module sdbc {

 published interface XStatement;


/** provides the navigation on a table of data.  A
    <type scope="com::sun::star::sdbc">ResultSet</type>
    object is usually generated by executing a
    <type scope="com::sun::star::sdbc">Statement</type>
    .


    <p>
    A ResultSet maintains a cursor pointing to its current row of
    data. Initially the cursor is positioned before the first row.
    The 'next' method moves the cursor to the next row.
    </p>
 */
published interface XResultSet: com::sun::star::uno::XInterface
{
    //-------------------------------------------------------------------------

    /** moves the cursor down one row from its current position.


        <p>
        A ResultSet cursor is initially positioned before the first row; the
        first call to next makes the first row the current row; the
        second call makes the second row the current row, and so on.
        </p>
        <p>If an input stream is open for the current row, a call
        to the method
        <code>next</code>
        will implicitly close it.
        The ResultSet's warning chain is cleared when a new row is read.
        </p>
        @returns
         <TRUE/> if successful
        @throws SQLException
            if a database access error occurs.
     */
    boolean next() raises (SQLException);
    //-------------------------------------------------------------------------

    /** indicates whether the cursor is before the first row in the result
        set.
        @returns
         <TRUE/> if so
        @throws SQLException
            if a database access error occurs.
     */
    boolean isBeforeFirst() raises (SQLException);
    //-------------------------------------------------------------------------

    /** indicates whether the cursor is after the last row in the result
        set.
        @returns
         <TRUE/> if so
        @throws SQLException
            if a database access error occurs.
     */
    boolean isAfterLast() raises (SQLException);
    //-------------------------------------------------------------------------

    /** indicates whether the cursor is on the first row of the result set.
        @returns
         <TRUE/> if so
        @throws SQLException
            if a database access error occurs.
     */
    boolean isFirst() raises (SQLException);
    //-------------------------------------------------------------------------

    /** indicates whether the cursor is on the last row of the result set.


        <p>
        <B>
        Note:
        </B>
        Calling the method
        <code>isAtLast</code>
        may be expensive because the SDBC driver might need to fetch ahead one row in order
        to determine whether the current row is the last row in the result set.
        </p>
        @returns
         <TRUE/> if so
        @throws SQLException
            if a database access error occurs.
     */
    boolean isLast() raises (SQLException);
    //-------------------------------------------------------------------------

    /** moves the cursor to the front of the result set, just before the
        first row. Has no effect if the result set contains no rows.
        @throws SQLException
            if a database access error occurs.
     */
    void beforeFirst() raises (SQLException);
    //-------------------------------------------------------------------------

    /** moves the cursor to the end of the result set, just after the last
        row. Has no effect if the result set contains no rows.
        @throws SQLException
            if a database access error occurs.
     */
    void afterLast() raises (SQLException);
    //-------------------------------------------------------------------------

    /** moves the cursor to the first row in the result set.
        @returns
         <TRUE/> if successful
        @throws SQLException
            if a database access error occurs.
     */
    boolean first() raises (SQLException);
    //-------------------------------------------------------------------------

    /** moves the cursor to the last row in the result set.
        @returns
         <TRUE/> if successful
        @throws SQLException
            if a database access error occurs.
     */
    boolean last() raises (SQLException);
    //-------------------------------------------------------------------------

    /** retrieves the current row number. The first row is number 1, the
        second number 2, and so on.
        @returns
         the current position
        @throws SQLException
            if a database access error occurs.
     */
    long getRow() raises (SQLException);
    //-------------------------------------------------------------------------

    /** moves the cursor to the given row number in the result set.


        <p>
        If the row number is positive, the cursor moves to
        the given row number with respect to the
        beginning of the result set. The first row is row 1, the second
        is row 2, and so on.
        </p>
        <p>
        If the given row number is negative, the cursor moves to
        an absolute row position with respect to
        the end of the result set. For example, calling
        <code>absolute(-1)</code>
        positions the
        cursor on the last row,
        <code>absolute(-2)</code>
        indicates the next-to-last row, and so on.
        </p>
        <p>
        An attempt to position the cursor beyond the first/last row in
        the result set leaves the cursor before/after the first/last
        row, respectively.
        </p>
        <p>
        Note: Calling
        <code>absolute(1)</code>
        is the same
        as calling
        <member scope="com::sun::star::sdbc">XResultSet::first()</member>
        .
        Calling <code>moveToPosition(-1)</code> is the same as calling
        <code>moveToLast()</code>.
        </p>
     */
    boolean absolute([in] long row ) raises (SQLException);
    //-------------------------------------------------------------------------

    /** moves the cursor a relative number of rows, either positive or negative.


        <p>
        Attempting to move beyond the first/last row in the result set
        positions the cursor before/after
        the first/last row. Calling
        <code>relative(0)</code>
        is valid, but does not change the cursor position.
        </p>
        <p>
        Note: Calling
        <code>relative(1)</code>
        is different from calling
        <member scope="com::sun::star::sdbc">XResultSet::next()</member>
        because is makes sense to call
        <code>next()</code>
        when there is no current row, for example, when the cursor is positioned before
        the first row or after the last row of the result set.
        </p>
        @param rows
            how many rows should be moved relative to the current row
        @returns
         <TRUE/> if successful
        @throws SQLException
            if a database access error occurs.
     */
    boolean relative([in]long rows) raises (SQLException);
    //-------------------------------------------------------------------------

    /** moves the cursor to the previous row in the result set.


        <p>
        Note:
        <code>previous()</code>
        is not the same as
        <code>relative(-1)</code>
        because it makes sense to call
        <code>previous()</code>
        when there is no current row.
        </p>
        @returns
            <TRUE/> if successful
        @throws SQLException
            if a database access error occurs.
     */
    boolean previous() raises (SQLException);
    //-------------------------------------------------------------------------

    /** refreshes the current row with its most recent value in
        the database. Cannot be called when on the insert row.
        The
        <code>refreshRow</code>
        method provides a way for an application to
        explicitly tell the SDBC driver to refetch a row(s) from the
        database. An application may want to call
        <code>refreshRow</code>
        when caching or prefetching is being done by the SDBC driver to
        fetch the latest value of a row from the database. The SDBC driver
        may actually refresh multiple rows at once if the fetch size is
        greater than one.
        All values are refetched subject to the transaction isolation
        level and cursor sensitivity. If
        <code>refreshRow</code>
        is called after calling
        <code>updateXXX</code>
        , but before calling
        <member scope="com::sun::star::sdbc">XResultSet::updateRow()</member>
        , then the updates made to the row are lost.
        Calling the method
        <code>refreshRow</code>
        frequently will likely slow performance.
        @throws SQLException
            if a database access error occurs.
     */
    void refreshRow() raises (SQLException);
    //-------------------------------------------------------------------------

    /** indicates whether the current row has been updated. The value returned
        depends on whether or not the result set can detect updates.
        @returns
            <TRUE/> if successful
        @throws SQLException
            if a database access error occurs.
     */
    boolean rowUpdated() raises (SQLException);
    //-------------------------------------------------------------------------

    /** indicates whether the current row has had an insertion.  The value returned
        depends on whether or not the result set can detect visible inserts.
        @returns
            <TRUE/> if successful
        @throws SQLException
            if a database access error occurs.
     */
    boolean rowInserted() raises (SQLException);
    //-------------------------------------------------------------------------

    /** indicates whether a row has been deleted.  A deleted row may leave
        a visible "hole" in a result set.  This method can be used to
        detect holes in a result set.  The value returned depends on whether
        or not the result set can detect deletions.
        @returns
            <TRUE/> if successful
        @throws SQLException
            if a database access error occurs.
     */
    boolean rowDeleted() raises (SQLException);
    //-------------------------------------------------------------------------

    /** returns the Statement that produced this
        <type scope="com::sun::star::sdbc">ResultSet</type>
        object. If the result set was generated some other way, such as by an
        <type scope="com::sun::star::sdbc">XDatabaseMetaData</type>
        method, this method returns
        <NULL/>
        .
        @returns
            the statement object
        @throws SQLException
            if a database access error occurs.
     */
    com::sun::star::uno::XInterface getStatement() raises (SQLException);
};

//=============================================================================

}; }; }; };

/*===========================================================================
===========================================================================*/
#endif