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