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

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