offapi/com/sun/star/sdbc/XSQLData.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 #ifndef __com_sun_star_sdbc_XSQLData_idl__
  20 #define __com_sun_star_sdbc_XSQLData_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23
  24 #include <com/sun/star/sdbc/SQLException.idl>
  25
  26  module com {  module sun {  module star {  module sdbc {
  27
  28  published interface XSQLInput;
  29  published interface XSQLOutput;
  30
  31
  32 /** is used for the custom mapping of SQL user-defined types.
  33
  34
  35     <p>
  36     This interface must be implemented by a service that is
  37     registered in a type mapping.  It is expected that this interface
  38     will normally be implemented by a tool. The methods in this interface
  39     are called by the driver and are never called by a programmer
  40     directly.
  41     </p>
  42  */
  43 published interface XSQLData: com::sun::star::uno::XInterface
  44 {
  45
  46     /** returns the fully-qualified name of the SQL user-defined type
  47         that this object represents.
  48
  49
  50         <p>
  51         This method is called by the SDBC driver to get the name of the
  52         UDT instance that is being mapped to this instance of SQLData.
  53         </p>
  54         @returns
  55             the name of the SQL type.
  56         @throws SQLException
  57             if a database access error occurs.
  58      */
  59     string getSQLTypeName() raises (SQLException);
  60
  61
  62     /** populates this object with data read from the database.
  63
  64
  65         <p>
  66         The implementation of the method must follow this protocol:
  67         <br/>
  68         It must read each of the attributes or elements of the SQL
  69         type from the given input stream. This is done
  70         by calling a method of the input stream to read each
  71         item, in the order that they appear in the SQL definition
  72         of the type. The method
  73         <code>readSQL</code>
  74         then assigns the data to appropriate fields or elements (of this
  75         or other objects).
  76         <br/>
  77         Specifically, it must call the appropriate
  78         <code>XSQLInput.readXXX</code>
  79         method(s) to do the following:
  80         for a Distinct Type, read its single data element;
  81         for a Structured Type, read a value for each attribute of the SQL type.
  82         </p>
  83         <p>
  84         The SDBC driver initializes the input stream with a type map
  85         before calling this method, which is used by the appropriate
  86         <code>SQLInput.readXXX</code>
  87         method on the stream.
  88         </p>
  89
  90         @param stream
  91             the input SQL data stream
  92         @param typeName
  93             the SQL type of the value on the data stream
  94         @throws SQLException
  95             if a database access error occurs.
  96
  97         @see com::sun::star::sdbc::XSQLInput
  98      */
  99     void readSQL([in]XSQLInput stream, [in]string typeName)
 100         raises (SQLException);
 101
 102     /** writes this object to the given SQL data stream.
 103
 104
 105         <p>
 106         The implementation of the method must follow this protocol:
 107         <br/>
 108         It must write each of the attributes of the SQL type to the given output
 109         stream. This is done by calling a method of the output stream to write
 110         each item, in the order that they appear in the SQL definition of the type.
 111         Specifically, it must call the appropriate
 112         <code>XSQLOutput.writeXXX</code>
 113         method(s) to do the following:<br>
 114         for a Distinct Type, write its single data element;
 115         for a Structured Type, write a value for each attribute of the SQL type.
 116         </p>
 117         @param stream
 118             the output SQL data stream
 119         @throws SQLException
 120             if a database access error occurs.
 121         @see com::sun::star::sdbc::XSQLOutput
 122      */
 123     void writeSQL([in]XSQLOutput stream) raises (SQLException);
 124 };
 125
 126
 127 }; }; }; };
 128
 129 /*===========================================================================
 130 ===========================================================================*/
 131 #endif
 132
 133 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */