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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20  module com {  module sun {  module star {  module io {
  21  published interface XInputStream;
  22 };};};};
  23
  24  module com {  module sun {  module star {  module sdbc {
  25
  26  published interface XRef;
  27  published interface XArray;
  28  published interface XBlob;
  29  published interface XClob;
  30
  31
  32 /** represents an input stream that contains a stream of values representing an
  33     instance of a SQL structured or distinct type.
  34
  35
  36     <p>
  37     This interface, used only for custom mapping, is used by the driver
  38     behind the scenes, and a programmer never directly invokes
  39     <code>SQLInput</code>
  40     methods.
  41     </p>
  42     <p>
  43     When the method
  44     <code>getObject</code>
  45     is called with an object of a service implementing the interface
  46     <code>SQLData</code>
  47     , the SDBC driver calls the method
  48     com::sun::star::sdbc::XSQLData::getSQLType()
  49     to determine the SQL type of the user-defined type (UDT) being custom mapped.
  50     The driver creates an instance of
  51     com::sun::star::sdbc::XSQLInput
  52     ,
  53     populating it with the attributes of the UDT. The driver then passes the input
  54     stream to the method
  55     com::sun::star::sdbc::XSQLData::readSQL()
  56     , which in turn calls the
  57     <code>XSQLInput.readXXX</code>
  58     methods in its implementation for reading the attributes from the input stream.
  59     </p>
  60  */
  61 published interface XSQLInput: com::sun::star::uno::XInterface
  62 {
  63
  64     /** reads the next attribute in the stream as string.
  65         @returns
  66             the attribute; if the value is SQL NULL, return null.
  67         @throws SQLException
  68             if a database access error occurs.
  69      */
  70     string readString() raises (SQLException);
  71
  72     /** reads the next attribute in the stream as boolean.
  73         @returns
  74             the attribute; if the value is SQL NULL, return null.
  75         @throws SQLException
  76             if a database access error occurs.
  77      */
  78     boolean readBoolean() raises (SQLException);
  79
  80     /** reads the next attribute in the stream as byte.
  81         @returns
  82             the attribute; if the value is SQL NULL, return null.
  83         @throws SQLException
  84             if a database access error occurs.
  85      */
  86     byte readByte() raises (SQLException);
  87
  88     /** reads the next attribute in the stream as short.
  89         @returns
  90             the attribute; if the value is SQL NULL, return null.
  91         @throws SQLException
  92             if a database access error occurs.
  93      */
  94     short readShort() raises (SQLException);
  95
  96     /** reads the next attribute in the stream as long.
  97         @returns
  98             the attribute; if the value is SQL NULL, return null.
  99         @throws SQLException
 100             if a database access error occurs.
 101      */
 102     long readInt() raises (SQLException);
 103
 104     /** reads the next attribute in the stream as hyper.
 105         @returns
 106             the attribute; if the value is SQL NULL, return null.
 107         @throws SQLException
 108             if a database access error occurs.
 109      */
 110     hyper readLong() raises (SQLException);
 111
 112     /** reads the next attribute in the stream as float.
 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     float readFloat() raises (SQLException);
 119
 120     /** reads the next attribute in the stream as double.
 121         @returns
 122             the attribute; if the value is SQL NULL, return null.
 123         @throws SQLException
 124             if a database access error occurs.
 125      */
 126     double readDouble() raises (SQLException);
 127
 128     /** reads the next attribute in the stream as sequence of bytes.
 129                  @returns
 130             the attribute; if the value is SQL NULL, return null.
 131         @throws SQLException
 132             if a database access error occurs.
 133      */
 134     sequence<byte> readBytes() raises (SQLException);
 135
 136     /** reads the next attribute in the stream as date.
 137         @returns
 138             the attribute; if the value is SQL NULL, return null.
 139         @throws SQLException
 140             if a database access error occurs.
 141      */
 142     com::sun::star::util::Date readDate() raises (SQLException);
 143
 144     /** reads the next attribute in the stream as time.
 145         @returns
 146             the attribute; if the value is SQL NULL, return null.
 147         @throws SQLException
 148             if a database access error occurs.
 149      */
 150     com::sun::star::util::Time readTime() raises (SQLException);
 151
 152     /** reads the next attribute in the stream as datetime.
 153         @returns
 154             the attribute; if the value is SQL NULL, return null.
 155         @throws SQLException
 156             if a database access error occurs.
 157      */
 158     com::sun::star::util::DateTime readTimestamp() raises (SQLException);
 159
 160     /** reads the next attribute in the stream as sequence of bytes.
 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     com::sun::star::io::XInputStream readBinaryStream() raises (SQLException);
 167
 168     /** reads the next attribute in the stream as a Unicode string.
 169         @returns
 170             the attribute; if the value is SQL NULL, return null.
 171         @throws SQLException
 172             if a database access error occurs.
 173      */
 174     com::sun::star::io::XInputStream readCharacterStream() raises (SQLException);
 175
 176     /** returns the datum at the head of the stream as an any.
 177
 178
 179         <p>
 180         The actual type of the any returned is determined by the default
 181         type mapping, and any customizations present in this stream's type map.
 182
 183         <br/>
 184         A type map is registered with the stream by the SDBC driver before the
 185         stream is passed to the application.
 186
 187         <br/>
 188         When the datum at the head of the stream is a SQL NULL,
 189         the method returns `VOID`. If the datum is a SQL structured or distinct
 190         type, it determines the SQL type of the datum at the head of the stream,
 191         constructs an object of the appropriate service, and calls the method
 192         com::sun::star::sdbc::XSQLData::readSQL()
 193         on that object, which reads additional data
 194         from the stream using the protocol described for that method.
 195
 196         </p>
 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     any readObject() raises (SQLException);
 203
 204     /** reads a REF(&amp;lt;structured-type&amp;gt;) from the stream.
 205         @returns
 206             the attribute; if the value is SQL NULL, return null.
 207         @throws SQLException
 208             if a database access error occurs.
 209      */
 210     XRef readRef() raises (SQLException);
 211
 212     /** reads a BLOB from the stream.
 213         @returns
 214             the attribute; if the value is SQL NULL, return null.
 215         @throws SQLException
 216             if a database access error occurs.
 217      */
 218     XBlob readBlob() raises (SQLException);
 219
 220     /** reads a CLOB from the stream.
 221         @returns
 222             the attribute; if the value is SQL NULL, return null.
 223         @throws SQLException
 224             if a database access error occurs.
 225      */
 226     XClob readClob() raises (SQLException);
 227
 228     /** reads an array from the stream.
 229         @returns
 230             the attribute; if the value is SQL NULL, return null.
 231         @throws SQLException
 232             if a database access error occurs.
 233      */
 234     XArray readArray() raises (SQLException);
 235
 236     /** determines whether the last value read was null.
 237         @returns
 238             `TRUE` if the most recently gotten SQL value was null; otherwise, `FALSE`
 239         @throws SQLException
 240             if a database access error occurs.
 241      */
 242     boolean wasNull() raises (SQLException);
 243 };
 244
 245
 246 }; }; }; };
 247
 248 /*===========================================================================
 249 ===========================================================================*/
 250
 251 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */