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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20  module com {  module sun {  module star {  module sdbcx {
  21
  22
  23 /** is used to identify rows within a result set and to find rows by a bookmark.
  24
  25
  26     <p>
  27     Bookmarks are only valid in the scope of the current result set and
  28     are not interchangeable between result sets. A bookmark could be a complex data
  29     structure, so it could not be compared in a safe way. Because of that, a provider
  30     has to implement the compare method for bookmarks.
  31     </p>
  32  */
  33 published interface XRowLocate: com::sun::star::uno::XInterface
  34 {
  35
  36     /** returns the bookmark of the current row of a result set.
  37         @returns
  38             the current bookmark
  39         @throws com::sun::star::sdbc::SQLException
  40             if a database access error occurs.
  41      */
  42     any getBookmark() raises (com::sun::star::sdbc::SQLException);
  43
  44     /** moves the cursor to the row identified by a valid bookmark.
  45
  46         <p>
  47         If the bookmark could not be located, a result set will be positioned
  48         after the last record.
  49         <br/>
  50         If the bookmark is invalid, or not generated by the current result set, then
  51         the behavior is not defined, even an abnormal termination is possible.
  52         </p>
  53         @param bookmark
  54             the bookmark where to move
  55         @returns
  56             `TRUE` if successful
  57         @throws com::sun::star::sdbc::SQLException
  58             if a database access error occurs.
  59      */
  60     boolean moveToBookmark([in]any bookmark) raises (com::sun::star::sdbc::SQLException);
  61
  62     /** moves the cursor a relative number of rows, either positive or negative
  63         starting at a given bookmark position.
  64
  65
  66         <p>
  67         If the bookmark could not be located, a result set will be positioned
  68         after the last record.
  69         <br/>
  70         If the bookmark is invalid, or not generated by the current result set, then
  71         the behavior is not defined, even an abnormal termination is possible.
  72         </p>
  73         @param bookmark
  74             the bookmark where to move
  75         @param rows
  76             count of rows move relative to the bookmark
  77         @returns
  78             `TRUE` if successful
  79         @throws com::sun::star::sdbc::SQLException
  80             if a database access error occurs.
  81      */
  82     boolean moveRelativeToBookmark([in]any bookmark, [in]long rows)
  83         raises (com::sun::star::sdbc::SQLException);
  84
  85     /** compares two bookmarks and returns an indication of their relative values.
  86
  87         <p>
  88         The bookmarks must apply to the same ResultSet. You cannot reliably
  89         compare bookmarks from different ResultSets, even if they were created from
  90         the same source or statement.
  91         <br/>
  92         A bookmark that is not valid, or incorrectly formed, will cause an exception.
  93         </p>
  94         @param first
  95             the first bookmark
  96         @param second
  97             the second bookmark
  98         @returns
  99             a value of com::sun::star::sdbcx::CompareBookmark
 100         @throws com::sun::star::sdbc::SQLException
 101             if a database access error occurs.
 102
 103         @see com::sun::star::sdbcx::CompareBookmark
 104
 105      */
 106     long compareBookmarks([in]any first, [in]any second)
 107         raises (com::sun::star::sdbc::SQLException);
 108
 109     /** determines whether the bookmarks of a result set are ordered or not.
 110         @returns
 111             `TRUE` if so
 112         @throws com::sun::star::sdbc::SQLException
 113             if a database access error occurs.
 114         @see com::sun::star::sdbcx::CompareBookmark
 115      */
 116     boolean hasOrderedBookmarks() raises (com::sun::star::sdbc::SQLException);
 117
 118     /** returns the hash value for a specified bookmark.
 119         @param bookmark
 120             the bookmark to hash
 121         @returns
 122             the hashed value
 123         @throws com::sun::star::sdbc::SQLException
 124             if a database access error occurs.
 125      */
 126     long hashBookmark([in]any bookmark) raises (com::sun::star::sdbc::SQLException);
 127 };
 128
 129
 130 }; }; }; };
 131
 132 /*===========================================================================
 133 ===========================================================================*/
 134
 135 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */