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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28 #ifndef __com_sun_star_sdbc_XSQLInput_idl__
  29 #define __com_sun_star_sdbc_XSQLInput_idl__
  30
  31 #include <com/sun/star/uno/XInterface.idl>
  32
  33 #include <com/sun/star/util/Date.idl>
  34
  35 #include <com/sun/star/util/DateTime.idl>
  36
  37 #include <com/sun/star/util/Time.idl>
  38
  39  module com {  module sun {  module star {  module io {
  40  published interface XInputStream;
  41 };};};};
  42
  43 #include <com/sun/star/sdbc/SQLException.idl>
  44
  45  module com {  module sun {  module star {  module sdbc {
  46
  47  published interface XRef;
  48  published interface XArray;
  49  published interface XBlob;
  50  published interface XClob;
  51
  52
  53 /** represents an input stream that contains a stream of values representing an
  54     instance of a SQL structured or distinct type.
  55
  56
  57     <p>
  58     This interface, used only for custom mapping, is used by the driver
  59     behind the scenes, and a programmer never directly invokes
  60     <code>SQLInput</code>
  61     methods.
  62     </p>
  63     <p>
  64     When the method
  65     <code>getObject</code>
  66     is called with an object of a service implementing the interface
  67     <code>SQLData</code>
  68     , the SDBC driver calls the method
  69     <member scope="com::sun::star::sdbc">XSQLData::getSQLType()</member>
  70     to determine the SQL type of the user-defined type (UDT) being custom mapped.
  71     The driver creates an instance of
  72     <type scope="com::sun::star::sdbc">XSQLInput</type>
  73     ,
  74     populating it with the attributes of the UDT. The driver then passes the input
  75     stream to the method
  76     <member scope="com::sun::star::sdbc">XSQLData::readSQL()</member>
  77     , which in turn calls the
  78     <code>XSQLInput.readXXX</code>
  79     methods in its implementation for reading the attributes from the input stream.
  80     </p>
  81  */
  82 published interface XSQLInput: com::sun::star::uno::XInterface
  83 {
  84
  85     /** reads the next attribute in the stream as string.
  86         @returns
  87             the attribute; if the value is SQL NULL, return null.
  88         @throws SQLException
  89             if a database access error occurs.
  90      */
  91     string readString() raises (SQLException);
  92     //-------------------------------------------------------------------------
  93
  94     /** reads the next attribute in the stream as boolean.
  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     boolean readBoolean() raises (SQLException);
 101     //-------------------------------------------------------------------------
 102
 103     /** reads the next attribute in the stream as byte.
 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     byte readByte() raises (SQLException);
 110     //-------------------------------------------------------------------------
 111
 112     /** reads the next attribute in the stream as short.
 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     short readShort() raises (SQLException);
 119     //-------------------------------------------------------------------------
 120
 121     /** reads the next attribute in the stream as long.
 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     long readInt() raises (SQLException);
 128     //-------------------------------------------------------------------------
 129
 130     /** reads the next attribute in the stream as hyper.
 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     hyper readLong() raises (SQLException);
 137     //-------------------------------------------------------------------------
 138
 139     /** reads the next attribute in the stream as float.
 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     float readFloat() raises (SQLException);
 146     //-------------------------------------------------------------------------
 147
 148     /** reads the next attribute in the stream as double.
 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     double readDouble() raises (SQLException);
 155     //-------------------------------------------------------------------------
 156
 157     /** reads the next attribute in the stream as sequence of bytes.
 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     sequence<byte> readBytes() raises (SQLException);
 164     //-------------------------------------------------------------------------
 165
 166     /** reads the next attribute in the stream as date.
 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     com::sun::star::util::Date readDate() raises (SQLException);
 173     //-------------------------------------------------------------------------
 174
 175     /** reads the next attribute in the stream as time.
 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::Time readTime() raises (SQLException);
 182     //-------------------------------------------------------------------------
 183
 184     /** reads the next attribute in the stream as datetime.
 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::DateTime readTimestamp() raises (SQLException);
 191     //-------------------------------------------------------------------------
 192
 193     /** reads the next attribute in the stream as sequence of bytes.
 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::io::XInputStream readBinaryStream() raises (SQLException);
 200     //-------------------------------------------------------------------------
 201
 202     /** reads the next attribute in the stream as a Unicode string.
 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 readCharacterStream() raises (SQLException);
 209        //-------------------------------------------------------------------------
 210
 211     /** returns the datum at the head of the stream as an any.
 212
 213
 214         <p>
 215         The actual type of the any returned is determined by the default
 216         type mapping, and any customizations present in this stream's type map.
 217
 218         <br/>
 219         A type map is registered with the stream by the SDBC driver before the
 220         stream is passed to the application.
 221
 222         <br/>
 223         When the datum at the head of the stream is a SQL NULL,
 224         the method returns <void/>. If the datum is a SQL structured or distinct
 225         type, it determines the SQL type of the datum at the head of the stream,
 226         constructs an object of the appropriate service, and calls the method
 227         <member scope="com::sun::star::sdbc">XSQLData::readSQL()</member>
 228         on that object, which reads additional data
 229         from the stream using the protocol described for that method.
 230
 231         </p>
 232         @returns
 233             the attribute; if the value is SQL NULL, return null.
 234         @throws SQLException
 235             if a database access error occurs.
 236      */
 237     any readObject() raises (SQLException);
 238       //-------------------------------------------------------------------------
 239
 240     /** reads a REF(&amp;lt;structured-type&amp;gt;) from the stream.
 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     XRef readRef() raises (SQLException);
 247       //-------------------------------------------------------------------------
 248
 249     /** reads a BLOB 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     XBlob readBlob() raises (SQLException);
 256       //-------------------------------------------------------------------------
 257
 258     /** reads a CLOB 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     XClob readClob() raises (SQLException);
 265       //-------------------------------------------------------------------------
 266
 267     /** reads an array 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     XArray readArray() raises (SQLException);
 274       //-------------------------------------------------------------------------
 275
 276     /** determines whether the last value read was null.
 277         @returns
 278             <TRUE/> if the most recently gotten SQL value was null; otherwise, <FALSE/>
 279         @throws SQLException
 280             if a database access error occurs.
 281      */
 282     boolean wasNull() raises (SQLException);
 283 };
 284
 285 //=============================================================================
 286
 287 }; }; }; };
 288
 289 /*===========================================================================
 290 ===========================================================================*/
 291 #endif
 292
 293 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */