offapi/com/sun/star/sdb/DataAccessDescriptor.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 sdb {
  21
  22 /** descriptor for accessing basic data access objects.
  23
  24     <p>Various components interacting with the database access world require to specify (or provide themselves) an object
  25     such as a query, a table, a result set, a connection to a data source, a column within a table, and so on.<br/>
  26     All of these objects are usually not specified with a single property, but with a set of properties, and for
  27     various objects, various (but not always different) properties are needed.<br/>
  28     The <code>DataAccessDescriptor</code> describes the super set of the properties for the most common
  29     data access objects.</p>
  30
  31     <p>Every component providing or requiring a DataAccessDescriptor for some functionality
  32     is urged to specify which properties are mandatory, and which ones optional. Additionally,
  33     it's free to specify any additional requirements about the relations of properties.</p>
  34
  35     @since OOo 1.1.2
  36 */
  37 published service DataAccessDescriptor
  38 {
  39     /** specifies the name of the datasource to access.
  40
  41         <p>This data source is usually used to create a Connection. If no DataSourceName is given
  42         and the #DatabaseLocation and the #ConnectionResource are empty, then an #ActiveConnection
  43         is required.</p>
  44
  45         @see com::sun::star::sdb::DatabaseContext
  46         @see ActiveConnection
  47      */
  48     [optional, property] string DataSourceName;
  49
  50     /** specifies the URL of the database file.
  51
  52         <p>This database location is usually used to create a Connection. If no DatabaseLocation is given
  53         and the #ConnectionResource is empty, then an #ActiveConnection is required.</p>
  54
  55         @see com::sun::star::sdb::DatabaseContext
  56         @see ActiveConnection
  57      */
  58     [optional, property] string DatabaseLocation;
  59
  60     /** specifies the database URL which locates a database driver.
  61
  62         <p>This database URL is usually used to create a Connection. If no ConnectionResource is given,
  63         then an #ActiveConnection is required.</p>
  64
  65         @see com::sun::star::sdb::DatabaseContext
  66         @see ActiveConnection
  67      */
  68     [optional, property] string ConnectionResource;
  69
  70     /** specifies additional info to use when creating a connection from a <code>ConnectionResource</code>
  71
  72         <p>This member is evaluated only when <code>ConnectionResource</code> is used: In this case,
  73         com::sun::star::sdbc::XDriverManager::getConnectionWithInfo() is used
  74         to create a connection for the given connection resource, instead of
  75         com::sun::star::sdbc::XDriverManager::getConnection().</p>
  76
  77         <p>If the sequence is empty, it is ignored.</p>
  78     */
  79     [optional, property] sequence< ::com::sun::star::beans::PropertyValue > ConnectionInfo;
  80
  81     /** is a connection to use.
  82
  83         <p>This object is guaranteed to be a com::sun::star::sdbc::Connection, but usually
  84         it will be a Connection from the module com::sun::star::sdb.<br/>
  85         Especially in the case where no #DataSourceName is given, but
  86         #CommandType is CommandType::QUERY, the ActiveConnection needs
  87         to fully support the Connection service, to actually retrieve the query specified by
  88         #Command</p>
  89
  90         <p>If no ActiveConnection is given, then a #DataSourceName is required.</p>
  91
  92         @see DataSourceName
  93      */
  94     [optional, property] com::sun::star::sdbc::XConnection ActiveConnection;
  95
  96     /** specifies the command to execute to retrieve a result set.
  97
  98         <p>This property is only meaningful together with the #CommandType
  99         property, thus either <em>both</em> or <em>none</em> of them are present.</p>
 100
 101         @see CommandType
 102      */
 103     [optional, property] string Command;
 104
 105
 106     /** specifies the type of the command to be executed to retrieve a result set.
 107
 108         <p>#Command needs to be interpreted depending on the value of this property.</p>
 109
 110         <p>This property is only meaningful together with the #Command
 111         property, thus either <em>both</em> or <em>none</em> of them are present.</p>
 112
 113         @see com::sun::star::sdb::CommandType
 114      */
 115     [optional, property] long CommandType;
 116
 117     /** specifies an additional filter to optionally use.
 118
 119         <p>The Filter string has to form a <code>WHERE</code>-clause, <em>without</em> the
 120         <code>WHERE</code>-string itself.</p>
 121
 122         <p>If a #DataSourceName, #Command and #CommandType
 123         are specified, a RowSet can be created with this information. If the results provided by the
 124         row set are to be additionally filtered, the Filter property can be used.</p>
 125
 126         <p>Note that the Filter property does not make sense if a #ResultSet has been specified
 127         in the DataAccessDescriptor.</p>
 128
 129         @see com::sun::star::sdb::RowSet
 130         @see ResultSet
 131     */
 132     [optional, property] string Filter;
 133
 134     /** specifies an additional <code>ORDER BY</code> clause which should be applied on top of
 135         the given #Command.
 136
 137         <p>The keyword <code>ORDER BY</code> itself is not part of this property.</p>
 138      */
 139     [optional, property] string Order;
 140
 141     /** specifies an additional <code>HAVING</code> clause which should be applied on top of
 142         the given #Command.
 143
 144         <p>The keyword <code>HAVING</code> itself is not part of this property.</p>
 145      */
 146     [optional, property] string HavingClause;
 147
 148     /** specifies an additional <code>GROUP BY</code> clause which should be applied on top of
 149         the given #Command.
 150
 151         <p>The keyword <code>GROUP BY</code> itself is not part of this property.</p>
 152      */
 153     [optional, property] string GroupBy;
 154
 155     /** specifies if the #Command should be analyzed on the client side before sending it
 156         to the database server.
 157
 158         <p>The default value of this property is `TRUE`. By switching it to `FALSE`, you can pass
 159         backend-specific SQL statements, which are not standard SQL, to your database.</p>
 160
 161         <p>This property is usually present together with the #Command and
 162         #CommandType properties, and is evaluated if and only if #CommandType
 163         equals CommandType::COMMAND.</p>
 164     */
 165     [optional, property] boolean EscapeProcessing;
 166
 167     /** specifies an already existent result set to use.
 168
 169         <p>Usually, you use the properties #DataSourceName (alternatively
 170         #ActiveConnection), #Command and #CommandType to specify
 171         how to <em>obtain</em> a result set. However, in scenarios where the provider of a DataAccessDescriptor
 172         has access to an already existent result set, it can pass it along for reusage. This is encouraged
 173         to increase performance.</p>
 174
 175         <p>The object will at least support the com::sun::star::sdbc::ResultSet service.</p>
 176
 177         <p>Note that any superservices of com::sun::star::sdbc::ResultSet
 178         are also allowed. Especially, this member can denote an instance of the
 179         com::sun::star::sdb::RowSet, or an instance obtained
 180         by calling com::sun::star::sdb::XResultSetAccess::createResultSet()
 181         on such a com::sun::star::sdb::RowSet. This becomes important in
 182         conjunction with the #Selection property.</p>
 183
 184         @see com::sun::star::sdb::XResultSetAccess
 185     */
 186     [optional, property] com::sun::star::sdbc::XResultSet ResultSet;
 187
 188     /** specifies a selection to confine the records in a result set.
 189
 190         <p>When you specify a result set either implicitly (#DataSourceName, #Command,
 191         #CommandType) or explicitly (#ResultSet), the set of results can be
 192         additionally refined with this property.</p>
 193
 194         <p>The single elements of the #Selection are either record numbers (see
 195         com::sun::star::sdbc::XResultSet::getRow()), or bookmarks (see
 196         com::sun::star::sdbcx::XRowLocate::getBookmark()).<br/>
 197         It is up to the component which provides or requires a DataAccessDescriptor to specify which of the
 198         two alternatives it expects. If it does <em>not</em> specify this, then the property
 199         #BookmarkSelection becomes mandatory.</p>
 200
 201         <p>If the elements specify bookmarks, and a #ResultSet has been specified, then
 202         this result set is required to support the com::sun::star::sdbcx::XRowLocate interface.</p>
 203     */
 204     [optional, property] sequence< any > Selection;
 205
 206     /** specifies how to interpret #Selection
 207
 208         <p>If present, #BookmarkSelection specifies the semantics of #Selection. If
 209         not present, it's up to the implementing component to specify this semantics.</p>
 210
 211         <p>If `TRUE`, then the single elements of the array specified by #Selection are
 212         bookmarks relative to the result set, if `FALSE`, they're record numbers.</p>
 213
 214         @see com::sun::star::sdbcx::XRowLocate
 215         @see com::sun::star::sdbc::XResultSet
 216         @see com::sun::star::sdb::XResultSetAccess
 217     */
 218     [optional, property] boolean BookmarkSelection;
 219
 220     /** specifies a column name.
 221
 222         <p>This property is usually used together with the #Command and
 223         #CommandType properties.</p>
 224
 225         @see Column
 226     */
 227     [optional, property] string ColumnName;
 228
 229     /** specifies a column object
 230
 231         <p>For reasons of performance and saving resources, a supplier of an DataAccessDescriptor which is
 232         used to describe a column object can pass this object directly, instead of specifying it only implicitly
 233         with the #ColumnName property.</p>
 234
 235         <p>The object will at least support the com::sun::star::sdbcx::Column service, but more
 236         often it will even be a Column from the com::sun::star::sdb module.</p>
 237     */
 238     [optional, property] com::sun::star::beans::XPropertySet Column;
 239 };
 240
 241 }; }; }; };
 242
 243 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */