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

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