offapi/com/sun/star/chart2/data/XDatabaseDataProvider.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: XDatabaseDataProvider.idl,v $
  10  * $Revision: 1.4 $
  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_report_XDatabaseDataProvider_idl__
  31 #define __com_sun_star_report_XDatabaseDataProvider_idl__
  32
  33 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  34 #include <com/sun/star/container/NoSuchElementException.idl>
  35 #endif
  36 #include <com/sun/star/beans/XPropertySet.idl>
  37 #include <com/sun/star/beans/UnknownPropertyException.idl>
  38 #include <com/sun/star/lang/XInitialization.idl>
  39 #include <com/sun/star/lang/XComponent.idl>
  40 #include <com/sun/star/sdbc/XConnection.idl>
  41 #include <com/sun/star/sdbc/XParameters.idl>
  42 #include <com/sun/star/sdbc/XRowSet.idl>
  43 #include <com/sun/star/chart2/data/XDataProvider.idl>
  44 #include <com/sun/star/chart2/data/XRangeXMLConversion.idl>
  45
  46 //=============================================================================
  47
  48  module com {  module sun {  module star {  module chart2 { module data {
  49
  50 //=============================================================================
  51
  52 /** identifies a <type>XDataProvider</type> for result sets.
  53
  54     @see XDataProvider
  55     @see DataProvider
  56  */
  57 interface XDatabaseDataProvider
  58 {
  59     /** For accessing data a component provides for being used by
  60         charts.
  61      */
  62     interface XDataProvider;
  63
  64     /** allows you to convert the ranges a data provider deals with
  65         internally into valid XML.
  66      */
  67     interface XRangeXMLConversion;
  68
  69     /** allows access to the properties of the instance.
  70     */
  71     interface com::sun::star::lang::XInitialization;
  72
  73     /** allows life-time control of the database data provider.
  74      */
  75     interface com::sun::star::lang::XComponent;
  76
  77     /** allows access to the properties of the instance.
  78     */
  79     interface com::sun::star::beans::XPropertySet;
  80
  81     interface com::sun::star::sdbc::XParameters;
  82     interface com::sun::star::sdbc::XRowSet;
  83
  84     /** is used for subreports and contains the names of columns of the parent report.
  85     <p> These columns are typically the foreign key fields of the parent report.
  86     The values of theses columns are used to identify the data for the subreport.
  87     Each time the parent report changes it's current row, the subreport requeries
  88     it's data based on the values of the master fields.</p>
  89     <p>If the report is no sub report (e.g. it's parent is not a report itself), this
  90     property is not evaluated.</p>
  91
  92     */
  93     [attribute,bound] sequence<string> MasterFields;
  94
  95     /**is used for subreports and contains the names of the columns of the subreport
  96     which are related to the master fields of the parent report.
  97     <p>Entries in this sequence can either denote column names in the sub report,
  98     or paramater names.<br/>
  99     For instance, you could base the report on the SQL statement
 100     <code>SELECT * FROM invoices WHERE cust_ref = :cid</code>, and add <code>cid</code>
 101     to the DetailFields property. In this case, the parameter will be filled from
 102     the corresponding master field.<br/>
 103     Alternatively, you could simply base your report on the table <code>invoices</code>,
 104     and add the column name <code>cust_ref</code> to the DetailFields. In this case,
 105     and implicit filter clause <code>WHERE cust_ref = :&lt;new_param_name&gt;</code> will
 106     be created, and the artificial parameter will be filled from the corresponding
 107     master field.<br/>
 108     If a string in this property denotes both a column name and a parameter name, it
 109     is undefined which way it is interpreted, but implementations of the service are required
 110     to either decide for the paramter or the column, and proceed as usual.
 111     </p>
 112     <p>The columns specified herein typically represent a part of the primary key
 113     fields or their aliases of the detail report.</p>
 114     <p>If the report is no sub report (e.g. it's parent is not a report itself), this
 115     property is not evaluated.</p>
 116     *
 117     */
 118     [attribute,bound] sequence<string> DetailFields;
 119
 120     /** is the command which should be executed, the type of command depends
 121     on the CommandType.
 122     <p>In case of a <member>CommandType</member> of <member>CommandType::COMMAND</member>,
 123     means in case the <member>Command</member> specifies an SQL statement, the inherited
 124     <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member>
 125     becomes relevant:<br/>
 126     It then can be to used to specify whether the SQL statement should be analyzed on the
 127     client side before sending it to the database server.<br/>
 128     The default value for <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member>
 129     is <TRUE/>. By switching it to <FALSE/>, you can pass backend-specific SQL statements,
 130     which are not standard SQL, to your database.</p>
 131
 132
 133     @see com::sun::star::sdb::CommandType
 134     */
 135     [attribute,bound] string Command;
 136
 137     /** specifies the type of the command to be executed to retrieve a result set.
 138
 139         <p><member>Command</member> needs to be interpreted depending on the value of this property.</p>
 140
 141         <p>This property is only meaningfull together with the <member>Command</member>
 142         property, thus either <em>both</em> or <em>none</em> of them are present.</p>
 143
 144         @see com::sun::star::sdb::CommandType
 145      */
 146     [attribute,bound] long CommandType;
 147
 148     /** specifies an addtional filter to optinally use.
 149
 150         <p>The Filter string has to form a SQL WHERE-clause, <em>without</em> the WHERE-string itself.</p>
 151
 152         <p>If a <member>DataSourceName</member>, <member>Command</member> and <member>CommandType</member>
 153         are specified, a <type>RowSet</type> can be created with this information. If the results provided by the
 154         row set are to be additionally filtered, the Filter property can be used.</p>
 155
 156         <p>Note that the Filter property does not make sense if a <member>ResultSet</member> has been specified
 157         in the DataAccessDescriptor.</p>
 158
 159         @see com::sun::star::sdb::RowSet
 160         @see ResultSet
 161     */
 162     [attribute,bound] string Filter;
 163
 164     /** indicates whether the filter should be applied or not,
 165         default is <FALSE/>.
 166      */
 167     [attribute,bound] boolean ApplyFilter;
 168
 169     /** additional having clause for the row set
 170      */
 171     [attribute,bound] string HavingClause
 172     {
 173         set raises (com::sun::star::beans::UnknownPropertyException);
 174     };
 175
 176     /** additional group by for the row set
 177      */
 178     [attribute,bound] string GroupBy
 179     {
 180         set raises (com::sun::star::beans::UnknownPropertyException);
 181     };
 182
 183     /** is a additional sort order definition for a rowset.
 184      */
 185     [attribute,bound] string Order;
 186
 187     /** specifies if the <member>Command</member> should be analyzed on the client side before sending it
 188         to the database server.
 189
 190         <p>The default value of this property is <TRUE/>. By switching it to <FALSE/>, you can pass
 191         backend-specific SQL statements, which are not standard SQL, to your database.</p>
 192
 193         <p>This property is usually present together with the <member>Command</member> and
 194         <member>CommandType</member> properties, and is evaluated if and only if <member>CommandType</member>
 195         equals <member>CommandType::COMMAND</member>.</p>
 196     */
 197     [attribute,bound] boolean EscapeProcessing;
 198
 199     /** specifies the maximal count of rows which should be fetched.
 200         <p>A value of zero implies that no limit exists.</p>
 201     */
 202     [attribute,bound] long RowLimit;
 203
 204     /** specifies the active connection which is used to create the resulting report.
 205     */
 206     [attribute,bound] com::sun::star::sdbc::XConnection ActiveConnection
 207     {
 208         set raises (com::sun::star::lang::IllegalArgumentException);
 209     };
 210     /** is the name of the datasource to use, this could be a named datasource
 211         or the URL of a data access component.
 212      */
 213     [attribute,bound] string DataSourceName;
 214 };
 215
 216 service DatabaseDataProvider : XDatabaseDataProvider
 217 {
 218     createWithConnection([in] com::sun::star::sdbc::XConnection connection);
 219 };
 220 //=============================================================================
 221
 222  }; }; }; };  };
 223
 224 /*=============================================================================
 225
 226 =============================================================================*/
 227 #endif