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