offapi/com/sun/star/sdbcx/XRowLocate.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XRowLocate.idl,v $
  10  * $Revision: 1.12 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_sdbcx_XRowLocate_idl__
  31 #define __com_sun_star_sdbcx_XRowLocate_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_sdbc_SQLException_idl__
  38 #include <com/sun/star/sdbc/SQLException.idl>
  39 #endif
  40
  41  module com {  module sun {  module star {  module sdbcx {
  42
  43
  44 /** is used to identify rows within a result set and to find rows by a bookmark.
  45
  46
  47     <p>
  48     Bookmarks are only valid in the scope of the current result set and
  49     are not interchangeable between result sets. A bookmark could be a complex data
  50     structure, so it could not be compared in a safe way. Because of that, a provider
  51     has to implement the compare method for bookmarks.
  52     </p>
  53  */
  54 published interface XRowLocate: com::sun::star::uno::XInterface
  55 {
  56
  57     /** returns the bookmark of the current row of a result set.
  58         @returns
  59             the current bookmark
  60         @throws com::sun::star::sdbc::SQLException
  61             if a database access error occurs.
  62      */
  63     any getBookmark() raises (com::sun::star::sdbc::SQLException);
  64     //-------------------------------------------------------------------------
  65
  66     /** moves the cursor to the row identified by an valid bookmark.
  67
  68         <p>
  69         If the bookmark could not be located, a result set will be positioned
  70         after the last record.
  71         <br/>
  72         If the bookmark is invalid, or not generated by the current result set, then
  73         the behaviour is not defined, even an abnormal termination is possible.
  74         </p>
  75         @param bookmark
  76             the bookmark where to move
  77         @returns
  78             <TRUE/> if successful
  79         @throws com::sun::star::sdbc::SQLException
  80             if a database access error occurs.
  81      */
  82     boolean moveToBookmark([in]any bookmark) raises (com::sun::star::sdbc::SQLException);
  83     //-------------------------------------------------------------------------
  84
  85     /** moves the cursor a relative number of rows, either positive or negative
  86         starting at a given bookmark position.
  87
  88
  89         <p>
  90         If the bookmark could not be located, a result set will be positioned
  91         after the last record.
  92         <br/>
  93         If the bookmark is invalid, or not generated by the current result set, then
  94         the behaviour is not defined, even an abnormal termination is possible.
  95         </p>
  96         @param bookmark
  97             the bookmark where to move
  98         @param rows
  99             count of rows move relative to the bookmark
 100         @returns
 101             <TRUE/> if successful
 102         @throws com::sun::star::sdbc::SQLException
 103             if a database access error occurs.
 104      */
 105     boolean moveRelativeToBookmark([in]any bookmark, [in]long rows)
 106         raises (com::sun::star::sdbc::SQLException);
 107     //-------------------------------------------------------------------------
 108
 109     /** compares two bookmarks and returns an indication of their relative values.
 110
 111         <p>
 112         The bookmarks must apply to the same ResultSet. You cannot reliably
 113         compare bookmarks from different ResultSets, even if they were created from
 114         the same source or statement.
 115         <br/>
 116         A bookmark that is not valid, or incorrectly formed, will cause an exception.
 117         </p>
 118         @param first
 119             the first bookmark
 120         @param second
 121             the second bookmark
 122         @returns
 123             a value of <type scope="com::sun::star::sdbcx">CompareBookmark</type>
 124         @throws com::sun::star::sdbc::SQLException
 125             if a database access error occurs.
 126
 127         @see com::sun::star::sdbcx::CompareBookmark
 128
 129      */
 130     long compareBookmarks([in]any first, [in]any second)
 131         raises (com::sun::star::sdbc::SQLException);
 132     //-------------------------------------------------------------------------
 133
 134     /** determines whether the bookmarks of a result set are ordered or not.
 135         @returns
 136             <TRUE/> if so
 137         @throws com::sun::star::sdbc::SQLException
 138             if a database access error occurs.
 139         @see com::sun::star::sdbcx::CompareBookmark
 140      */
 141     boolean hasOrderedBookmarks() raises (com::sun::star::sdbc::SQLException);
 142     //-------------------------------------------------------------------------
 143
 144     /** returns the hash value for a specified bookmark.
 145         @param bookmark
 146             the bookmark to hash
 147         @returns
 148             the hashed value
 149         @throws com::sun::star::sdbc::SQLException
 150             if a database access error occurs.
 151      */
 152     long hashBookmark([in]any bookmark) raises (com::sun::star::sdbc::SQLException);
 153 };
 154
 155 //=============================================================================
 156
 157 }; }; }; };
 158
 159 /*===========================================================================
 160 ===========================================================================*/
 161 #endif