offapi/com/sun/star/sdbc/XSQLInput.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: XSQLInput.idl,v $
  10  * $Revision: 1.12 $
  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_XSQLInput_idl__
  31 #define __com_sun_star_sdbc_XSQLInput_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_util_Date_idl__
  38 #include <com/sun/star/util/Date.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_util_DateTime_idl__
  42 #include <com/sun/star/util/DateTime.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_util_Time_idl__
  46 #include <com/sun/star/util/Time.idl>
  47 #endif
  48
  49  module com {  module sun {  module star {  module io {
  50  published interface XInputStream;
  51 };};};};
  52
  53 #ifndef __com_sun_star_sdbc_SQLException_idl__
  54 #include <com/sun/star/sdbc/SQLException.idl>
  55 #endif
  56
  57  module com {  module sun {  module star {  module sdbc {
  58
  59  published interface XRef;
  60  published interface XArray;
  61  published interface XBlob;
  62  published interface XClob;
  63
  64
  65 /** represents an input stream that contains a stream of values representing an
  66     instance of a SQL structured or distinct type.
  67
  68
  69     <p>
  70     This interface, used only for custom mapping, is used by the driver
  71     behind the scenes, and a programmer never directly invokes
  72     <code>SQLInput</code>
  73     methods.
  74     </p>
  75     <p>
  76     When the method
  77     <code>getObject</code>
  78     is called with an object of a service implementing the interface
  79     <code>SQLData</code>
  80     , the SDBC driver calls the method
  81     <member scope="com::sun::star::sdbc">XSQLData::getSQLType()</member>
  82     to determine the SQL type of the user-defined type (UDT) being custom mapped.
  83     The driver creates an instance of
  84     <type scope="com::sun::star::sdbc">XSQLInput</type>
  85     ,
  86     populating it with the attributes of the UDT. The driver then passes the input
  87     stream to the method
  88     <member scope="com::sun::star::sdbc">XSQLData::readSQL()</member>
  89     , which in turn calls the
  90     <code>XSQLInput.readXXX</code>
  91     methods in its implementation for reading the attributes from the input stream.
  92     </p>
  93  */
  94 published interface XSQLInput: com::sun::star::uno::XInterface
  95 {
  96
  97     /** reads the next attribute in the stream as string.
  98         @returns
  99             the attribute; if the value is SQL NULL, return null.
 100         @throws SQLException
 101             if a database access error occurs.
 102      */
 103     string readString() raises (SQLException);
 104     //-------------------------------------------------------------------------
 105
 106     /** reads the next attribute in the stream as boolean.
 107         @returns
 108             the attribute; if the value is SQL NULL, return null.
 109         @throws SQLException
 110             if a database access error occurs.
 111      */
 112     boolean readBoolean() raises (SQLException);
 113     //-------------------------------------------------------------------------
 114
 115     /** reads the next attribute in the stream as byte.
 116         @returns
 117             the attribute; if the value is SQL NULL, return null.
 118         @throws SQLException
 119             if a database access error occurs.
 120      */
 121     byte readByte() raises (SQLException);
 122     //-------------------------------------------------------------------------
 123
 124     /** reads the next attribute in the stream as short.
 125         @returns
 126             the attribute; if the value is SQL NULL, return null.
 127         @throws SQLException
 128             if a database access error occurs.
 129      */
 130     short readShort() raises (SQLException);
 131     //-------------------------------------------------------------------------
 132
 133     /** reads the next attribute in the stream as long.
 134         @returns
 135             the attribute; if the value is SQL NULL, return null.
 136         @throws SQLException
 137             if a database access error occurs.
 138      */
 139     long readInt() raises (SQLException);
 140     //-------------------------------------------------------------------------
 141
 142     /** reads the next attribute in the stream as hyper.
 143         @returns
 144             the attribute; if the value is SQL NULL, return null.
 145         @throws SQLException
 146             if a database access error occurs.
 147      */
 148     hyper readLong() raises (SQLException);
 149     //-------------------------------------------------------------------------
 150
 151     /** reads the next attribute in the stream as float.
 152         @returns
 153             the attribute; if the value is SQL NULL, return null.
 154         @throws SQLException
 155             if a database access error occurs.
 156      */
 157     float readFloat() raises (SQLException);
 158     //-------------------------------------------------------------------------
 159
 160     /** reads the next attribute in the stream as double.
 161         @returns
 162             the attribute; if the value is SQL NULL, return null.
 163         @throws SQLException
 164             if a database access error occurs.
 165      */
 166     double readDouble() raises (SQLException);
 167     //-------------------------------------------------------------------------
 168
 169     /** reads the next attribute in the stream as sequence of bytes.
 170                  @returns
 171             the attribute; if the value is SQL NULL, return null.
 172         @throws SQLException
 173             if a database access error occurs.
 174      */
 175     sequence<byte> readBytes() raises (SQLException);
 176     //-------------------------------------------------------------------------
 177
 178     /** reads the next attribute in the stream as date.
 179         @returns
 180             the attribute; if the value is SQL NULL, return null.
 181         @throws SQLException
 182             if a database access error occurs.
 183      */
 184     com::sun::star::util::Date readDate() raises (SQLException);
 185     //-------------------------------------------------------------------------
 186
 187     /** reads the next attribute in the stream as time.
 188         @returns
 189             the attribute; if the value is SQL NULL, return null.
 190         @throws SQLException
 191             if a database access error occurs.
 192      */
 193     com::sun::star::util::Time readTime() raises (SQLException);
 194     //-------------------------------------------------------------------------
 195
 196     /** reads the next attribute in the stream as datetime.
 197         @returns
 198             the attribute; if the value is SQL NULL, return null.
 199         @throws SQLException
 200             if a database access error occurs.
 201      */
 202     com::sun::star::util::DateTime readTimestamp() raises (SQLException);
 203     //-------------------------------------------------------------------------
 204
 205     /** reads the next attribute in the stream as sequence of bytes.
 206         @returns
 207             the attribute; if the value is SQL NULL, return null.
 208         @throws SQLException
 209             if a database access error occurs.
 210      */
 211     com::sun::star::io::XInputStream readBinaryStream() raises (SQLException);
 212     //-------------------------------------------------------------------------
 213
 214     /** reads the next attribute in the stream as a unicode string.
 215         @returns
 216             the attribute; if the value is SQL NULL, return null.
 217         @throws SQLException
 218             if a database access error occurs.
 219      */
 220     com::sun::star::io::XInputStream readCharacterStream() raises (SQLException);
 221        //-------------------------------------------------------------------------
 222
 223     /** returns the datum at the head of the stream as an any.
 224
 225
 226         <p>
 227         The actual type of the any returned is determined by the default
 228         type mapping, and any customizations present in this stream's type map.
 229
 230         <br/>
 231         A type map is registered with the stream by the SDBC driver before the
 232         stream is passed to the application.
 233
 234         <br/>
 235         When the datum at the head of the stream is a SQL NULL,
 236         the method returns <void/>. If the datum is a SQL structured or distinct
 237         type, it determines the SQL type of the datum at the head of the stream,
 238         constructs an object of the appropriate service, and calls the method
 239         <member scope="com::sun::star::sdbc">XSQLData::readSQL()</member>
 240         on that object, which reads additional data
 241         from the stream using the protocol described for that method.
 242
 243         </p>
 244         @returns
 245             the attribute; if the value is SQL NULL, return null.
 246         @throws SQLException
 247             if a database access error occurs.
 248      */
 249     any readObject() raises (SQLException);
 250       //-------------------------------------------------------------------------
 251
 252     /** reads a REF(&amp;lt;structured-type&amp;gt;) from the stream.
 253         @returns
 254             the attribute; if the value is SQL NULL, return null.
 255         @throws SQLException
 256             if a database access error occurs.
 257      */
 258     XRef readRef() raises (SQLException);
 259       //-------------------------------------------------------------------------
 260
 261     /** reads a BLOB from the stream.
 262         @returns
 263             the attribute; if the value is SQL NULL, return null.
 264         @throws SQLException
 265             if a database access error occurs.
 266      */
 267     XBlob readBlob() raises (SQLException);
 268       //-------------------------------------------------------------------------
 269
 270     /** reads a CLOB from the stream.
 271         @returns
 272             the attribute; if the value is SQL NULL, return null.
 273         @throws SQLException
 274             if a database access error occurs.
 275      */
 276     XClob readClob() raises (SQLException);
 277       //-------------------------------------------------------------------------
 278
 279     /** reads an array from the stream.
 280         @returns
 281             the attribute; if the value is SQL NULL, return null.
 282         @throws SQLException
 283             if a database access error occurs.
 284      */
 285     XArray readArray() raises (SQLException);
 286       //-------------------------------------------------------------------------
 287
 288     /** determines whether the last value read was null.
 289         @returns
 290             <TRUE/> if the most recently gotten SQL value was null; otherwise, <FALSE/>
 291         @throws SQLException
 292             if a database access error occurs.
 293      */
 294     boolean wasNull() raises (SQLException);
 295 };
 296
 297 //=============================================================================
 298
 299 }; }; }; };
 300
 301 /*===========================================================================
 302 ===========================================================================*/
 303 #endif