offapi/com/sun/star/sdbc/XArray.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XArray.idl,v $
  10  * $Revision: 1.11 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_sdbc_XArray_idl__
  31 #define __com_sun_star_sdbc_XArray_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37  module com {  module sun {  module star {  module container {
  38  published interface XNameAccess;
  39 };};};};
  40
  41 #ifndef __com_sun_star_sdbc_SQLException_idl__
  42 #include <com/sun/star/sdbc/SQLException.idl>
  43 #endif
  44
  45  module com {  module sun {  module star {  module sdbc {
  46
  47  published interface XResultSet;
  48
  49
  50 /** is used for mapping the SQL type
  51     <member scope= "com::sun::star::sdbc">DataType::ARRAY</member>
  52     .
  53     By default, an
  54     <code>Array</code>
  55     is a transaction duration
  56     reference to an SQL array. By default, an
  57
  58     <code>Array</code>
  59
  60     is implemented using a SQL LOCATOR(array) internally.
  61  */
  62 published interface XArray: com::sun::star::uno::XInterface
  63 {
  64
  65     /** returns the SQL type name of the elements in
  66         the array designated by this
  67         <code>Array</code>
  68         object.
  69         <p>
  70         If the elements are a built-in type, it returns
  71         the database-specific type name of the elements.
  72         If the elements are a user-defined type (UDT),
  73         this method returns the fully-qualified SQL type name.
  74         </p>
  75         @returns
  76             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
  77
  78         @throws SQLException
  79             if a database access error occurs.
  80      */
  81     string getBaseTypeName() raises (SQLException);
  82
  83       //-------------------------------------------------------------------------
  84
  85     /** returns the SDBC type of the elements in the array designated
  86         by this
  87         <code>Array</code>
  88         object.
  89         @returns
  90             a constant from the SDBC types that is the type code for the elements in the array designated by this Array object.
  91         @throws SQLException
  92             if a database access error occurs.
  93      */
  94     long getBaseType() raises (SQLException);
  95
  96     //-------------------------------------------------------------------------
  97
  98     /** retrieves the contents of the SQL array designated by this
  99                 <code>Array</code>
 100              object, using the specified
 101              <code>typeMap</code>
 102              for type map customizations.
 103              <p>
 104              If the base type of the array does not match a user-defined type
 105              in
 106              <code>typeMap</code>
 107              , the standard mapping is used instead.
 108
 109              @param typeMap
 110                 is a map object that contains mappings of SQL type names to
 111                 services. If the
 112                 <code>typeMap</code>
 113                 is
 114                 <NULL/>
 115                 , the type-map
 116                     associated with the connection for customizations of the type-mappings
 117                  is used.
 118
 119              @returns
 120                 an sequence that contains the ordered elements
 121                 of the SQL array designated by this object.
 122
 123              @throws SQLException
 124                 if an error occurs while attempting to access the array.
 125      */
 126     sequence<any> getArray([in]com::sun::star::container::XNameAccess typeMap)
 127         raises (SQLException);
 128
 129       //-------------------------------------------------------------------------
 130
 131     /** returns an array containing a slice of the SQL array, beginning with the
 132                 specified
 133              <code>index</code>
 134              and containing up to
 135              <code>count</code>
 136                 successive elements of the SQL array.
 137
 138              @param index
 139                 is the array index of the first element to retrieve;
 140                 the first element is at index 1.
 141                 @param count
 142                 is the number of successive SQL array elements to retrieve.
 143              @param typeMap
 144                 is a map object that contains mappings of SQL type names to
 145                 services. If the
 146                 <code>typeMap</code>
 147                 is
 148                 <NULL/>
 149                 , the type-map
 150                    associated with the connection for customizations of the type-mappings
 151                 is used.
 152              @returns
 153                 an array containing up to
 154                 <code>count</code>
 155                 consecutive elements
 156                    of the SQL array, beginning with element
 157                 <code>index</code>
 158                 .
 159                 @throws SQLException
 160                 if an error occurs while attempting to access the array.
 161      */
 162     sequence<any> getArrayAtIndex([in]long index,
 163                                   [in]long count,
 164                                   [in]com::sun::star::container::XNameAccess
 165                                                                       typeMap)
 166             raises (SQLException);
 167
 168       //-------------------------------------------------------------------------
 169
 170     /** returns a result set that contains the elements of the array
 171         designated by this
 172         <code>Array</code>
 173         object and uses the given
 174         <code>typeMap</code>
 175         to map the array elements.  If the base
 176         type of the array does not match a user-defined type in
 177         <code>typeMap</code>
 178         or the
 179         <code>typeMap</code>
 180         is
 181         <NULL/>
 182         ,
 183         the connection type mapping is used instead.
 184
 185
 186         <p>
 187         The result set contains one row for each array element, with
 188         two columns in each row.  The second column stores the element
 189         value; the first column stores the index into the array for
 190         that element (with the first array element being at index 1).
 191         The rows are in ascending order corresponding to
 192         the order of the indices.
 193         </p>
 194
 195         @param  typeMap
 196             contains mapping of SQL user-defined types to classes in the UNO programming language
 197         @returns
 198             a ResultSet object containing one row for each of the elements in the array designated by this Array object,
 199             with the rows in ascending order based on the indices.
 200         @throws SQLException
 201             if a database access error occurs.
 202      */
 203     XResultSet getResultSet([in]com::sun::star::container::XNameAccess typeMap)
 204         raises (SQLException);
 205
 206       //-------------------------------------------------------------------------
 207
 208     /** returns a result set holding the elements of the subarray that
 209         starts at index
 210         <code>index</code>
 211         and contains up to
 212         <code>count</code>
 213         successive elements. This method uses the given
 214         <code>typeMap</code>
 215         to map the array elements. If the base
 216         type of the array does not match a user-defined type in
 217         <code>typeMap</code>
 218         or the
 219         <code>typeMap</code>
 220         is
 221         <NULL/>
 222         ,
 223         the connection type mapping is used instead.
 224
 225
 226         <p>
 227         The result set contains one row for each array element, with
 228         two columns in each row.  The second column stores the element
 229         value; the first column stores the index into the array for
 230         that element (with the first array element being at index 1).
 231         The rows are in ascending order corresponding to
 232         the order of the indices.
 233         </p>
 234         @param index
 235             the array index of the first element to retrieve; the first element is at index 1.
 236         @param count
 237             the number of successive SQL array elements to retrieve,
 238         @param typeMap
 239             the Map object that contains the mapping of SQL type names to classes in the UNO programming language.
 240         @returns
 241             a ResultSet object containing up to count consecutive elements of the SQL array
 242             designated by this Array object, starting at index index.
 243         @throws SQLException
 244             if a database access error occurs.
 245      */
 246     XResultSet getResultSetAtIndex([in]long index,
 247                                    [in]long count,
 248                                    [in]com::sun::star::container::XNameAccess typeMap)
 249         raises (SQLException);
 250 };
 251
 252 //=============================================================================
 253
 254 }; }; }; };
 255
 256 /*===========================================================================
 257 ===========================================================================*/
 258 #endif