offapi/com/sun/star/sdbc/XArray.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 container {
  21  published interface XNameAccess;
  22 };};};};
  23
  24  module com {  module sun {  module star {  module sdbc {
  25
  26  published interface XResultSet;
  27
  28
  29 /** is used for mapping the SQL type com::sun::star::sdbc::DataType::ARRAY.
  30
  31     By default, an <code>Array</code> is a transaction duration
  32     reference to an SQL array. By default, an <code>Array</code>
  33     is implemented using a SQL LOCATOR(array) internally.
  34  */
  35 published interface XArray: com::sun::star::uno::XInterface
  36 {
  37
  38     /** returns the SQL type name of the elements in
  39         the array designated by this
  40         <code>Array</code>
  41         object.
  42         <p>
  43         If the elements are a built-in type, it returns
  44         the database-specific type name of the elements.
  45         If the elements are a user-defined type (UDT),
  46         this method returns the fully-qualified SQL type name.
  47         </p>
  48         @returns
  49             a String that is the database-specific name for a built-in base type or the fully-qualified SQL type name for a base type that is a UDT
  50
  51         @throws SQLException
  52             if a database access error occurs.
  53      */
  54     string getBaseTypeName() raises (SQLException);
  55
  56
  57     /** returns the SDBC type of the elements in the array designated
  58         by this
  59         <code>Array</code>
  60         object.
  61         @returns
  62             a constant from the SDBC types that is the type code for the elements in the array designated by this Array object.
  63         @throws SQLException
  64             if a database access error occurs.
  65      */
  66     long getBaseType() raises (SQLException);
  67
  68
  69     /** retrieves the contents of the SQL array designated by this
  70                 <code>Array</code>
  71              object, using the specified
  72              <code>typeMap</code>
  73              for type map customizations.
  74              <p>
  75              If the base type of the array does not match a user-defined type
  76              in
  77              <code>typeMap</code>
  78              , the standard mapping is used instead.
  79
  80              @param typeMap
  81                 is a map object that contains mappings of SQL type names to
  82                 services. If the
  83                 <code>typeMap</code>
  84                 is
  85                 `NULL`
  86                 , the type-map
  87                     associated with the connection for customizations of the type-mappings
  88                  is used.
  89
  90              @returns
  91                 a sequence that contains the ordered elements
  92                 of the SQL array designated by this object.
  93
  94              @throws SQLException
  95                 if an error occurs while attempting to access the array.
  96      */
  97     sequence<any> getArray([in]com::sun::star::container::XNameAccess typeMap)
  98         raises (SQLException);
  99
 100
 101     /** returns an array containing a slice of the SQL array, beginning with the
 102                 specified
 103              <code>index</code>
 104              and containing up to
 105              <code>count</code>
 106                 successive elements of the SQL array.
 107
 108              @param index
 109                 is the array index of the first element to retrieve;
 110                 the first element is at index 1.
 111                 @param count
 112                 is the number of successive SQL array elements to retrieve.
 113              @param typeMap
 114                 is a map object that contains mappings of SQL type names to
 115                 services. If the
 116                 <code>typeMap</code>
 117                 is
 118                 `NULL`
 119                 , the type-map
 120                    associated with the connection for customizations of the type-mappings
 121                 is used.
 122              @returns
 123                 an array containing up to
 124                 <code>count</code>
 125                 consecutive elements of the SQL array, beginning with element
 126                 <code>index</code>.
 127                 @throws SQLException
 128                 if an error occurs while attempting to access the array.
 129      */
 130     sequence<any> getArrayAtIndex([in]long index,
 131                                   [in]long count,
 132                                   [in]com::sun::star::container::XNameAccess
 133                                                                       typeMap)
 134             raises (SQLException);
 135
 136
 137     /** returns a result set that contains the elements of the array
 138         designated by this
 139         <code>Array</code>
 140         object and uses the given
 141         <code>typeMap</code>
 142         to map the array elements.  If the base
 143         type of the array does not match a user-defined type in
 144         <code>typeMap</code>
 145         or the
 146         <code>typeMap</code>
 147         is
 148         `NULL`
 149         ,
 150         the connection type mapping is used instead.
 151
 152
 153         <p>
 154         The result set contains one row for each array element, with
 155         two columns in each row.  The second column stores the element
 156         value; the first column stores the index into the array for
 157         that element (with the first array element being at index 1).
 158         The rows are in ascending order corresponding to
 159         the order of the indices.
 160         </p>
 161
 162         @param  typeMap
 163             contains mapping of SQL user-defined types to classes in the UNO programming language
 164         @returns
 165             a ResultSet object containing one row for each of the elements in the array designated by this Array object,
 166             with the rows in ascending order based on the indices.
 167         @throws SQLException
 168             if a database access error occurs.
 169      */
 170     XResultSet getResultSet([in]com::sun::star::container::XNameAccess typeMap)
 171         raises (SQLException);
 172
 173
 174     /** returns a result set holding the elements of the subarray that
 175         starts at index
 176         <code>index</code>
 177         and contains up to
 178         <code>count</code>
 179         successive elements. This method uses the given
 180         <code>typeMap</code>
 181         to map the array elements. If the base
 182         type of the array does not match a user-defined type in
 183         <code>typeMap</code>
 184         or the
 185         <code>typeMap</code>
 186         is
 187         `NULL`
 188         ,
 189         the connection type mapping is used instead.
 190
 191
 192         <p>
 193         The result set contains one row for each array element, with
 194         two columns in each row.  The second column stores the element
 195         value; the first column stores the index into the array for
 196         that element (with the first array element being at index 1).
 197         The rows are in ascending order corresponding to
 198         the order of the indices.
 199         </p>
 200         @param index
 201             the array index of the first element to retrieve; the first element is at index 1.
 202         @param count
 203             the number of successive SQL array elements to retrieve,
 204         @param typeMap
 205             the Map object that contains the mapping of SQL type names to classes in the UNO programming language.
 206         @returns
 207             a ResultSet object containing up to count consecutive elements of the SQL array
 208             designated by this Array object, starting at index index.
 209         @throws SQLException
 210             if a database access error occurs.
 211      */
 212     XResultSet getResultSetAtIndex([in]long index,
 213                                    [in]long count,
 214                                    [in]com::sun::star::container::XNameAccess typeMap)
 215         raises (SQLException);
 216 };
 217
 218
 219 }; }; }; };
 220
 221 /*===========================================================================
 222 ===========================================================================*/
 223
 224 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */