offapi/com/sun/star/sdb/DataSource.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: DataSource.idl,v $
  10  * $Revision: 1.19 $
  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_sdb_DataSource_idl__
  31 #define __com_sun_star_sdb_DataSource_idl__
  32
  33 #ifndef __com_sun_star_io_XPersistObject_idl__
  34 #include <com/sun/star/io/XPersistObject.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_beans_XPropertySet_idl__
  38 #include <com/sun/star/beans/XPropertySet.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_beans_PropertyValue_idl__
  42 #include <com/sun/star/beans/PropertyValue.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_util_XFlushable_idl__
  46 #include <com/sun/star/util/XFlushable.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_util_XNumberFormatsSupplier_idl__
  50 #include <com/sun/star/util/XNumberFormatsSupplier.idl>
  51 #endif
  52
  53
  54  module com {  module sun {  module star {  module sdbc {
  55      published interface XIsolatedConnection;
  56      published interface XDataSource;
  57  };};};};
  58
  59
  60  module com {  module sun {  module star {  module sdb {
  61
  62  published interface XCompletedConnection;
  63  published interface XQueryDefinitionsSupplier;
  64  published interface XBookmarksSupplier;
  65
  66
  67 /** is a factory to establish database connections. It should be registered at
  68     a <type scope="com::sun::star::uno">NamingService</type>.
  69     @see com::sun::star::sdb::DatabaseContext
  70  */
  71 published service DataSource
  72 {
  73     interface com::sun::star::beans::XPropertySet;
  74
  75
  76     /** useful for establishing connections with the completion of connection parameters
  77                 provided during user interaction.
  78      */
  79     interface XCompletedConnection;
  80
  81     /** useful for establishing isolated connections which are not shared among others
  82         as it is the case when using <type>XCompletedConnection</type> or <type scope="com::sun::star::sdbc">XDataSource</type>.
  83         @see XCompletedConnection
  84         @see com::sun::star::sdbc::XDataSource
  85         @since OOo 1.1.2
  86      */
  87     interface com::sun::star::sdbc::XIsolatedConnection;
  88
  89
  90     /** is provided to flush a DataSource within to a Database Context.
  91      */
  92     interface com::sun::star::util::XFlushable;
  93
  94
  95     /** provides the access to DataSource related queries.
  96         <p>
  97         The object returned by the
  98         <method scope="com::sun::star::sdb">XQueryDefinitionsSupplier::getQueryDefinitions()</method>
  99         supports the
 100         <type scope="com::sun::star::sdb">DefinitionContainer</type>
 101         service.
 102         </p>
 103      */
 104     interface XQueryDefinitionsSupplier;
 105
 106     /* useful for establishing connections and to get and set the login timeout.
 107     */
 108     interface com::sun::star::sdbc::XDataSource;
 109
 110     /** provides access to bookmarks to documents associated with the data source
 111         <p>
 112         The object returned by the
 113         <method scope="com::sun::star::sdb">XBookmarksSupplier::getBookmarks()</method>
 114         supports the
 115         <type scope="com::sun::star::sdb">DefinitionContainer</type>
 116         service.
 117         </p>
 118      */
 119     [optional] interface XBookmarksSupplier;
 120
 121     /** is the name of the data source.
 122
 123         <p>If the data source is registered at the database context, then the <code>Name</code> property
 124         denotes the registration name. Otherwise, the name property contains the URL of the file which the
 125         database document associated with the data source is based on.</p>
 126
 127         <p>If the same data source is registered under different names, the value of the <code>Name</code>
 128         property is not defined.</p>
 129      */
 130     [readonly, property] string Name;
 131
 132
 133     /** indicates a database url of the form <br>
 134         <code> jdbc:<em>subprotocol</em>:<em>subname</em></code>
 135         or
 136         <code>sdbc:<em>subprotocol</em>:<em>subname</em></code>
 137      */
 138     [property] string URL;
 139
 140
 141     /** is a list of arbitrary string tag/value pairs as connection arguments
 142
 143         <p>The <type>DataSource</type> itself does not attempt to interpret any of those values.</p>
 144
 145         <p>Instead, the values in this property have two use cases:
 146         <ul><li>Upon creating a connection, for every value in this sequence it's checked
 147                 whether the <type scope="com::sun::star::sdbc">XDriver</type> which is to provide
 148                 the connection supports a setting with the respective name, using its
 149                 <member scope="com::sun::star::sdbc">XDriver::getPropertyInfo<member> method.br/>
 150                 If so, the settings is passed to the drivers's
 151                 <member scope="com::sun::star::sdbc">XDriver::connect<member> method. If not,
 152                 the setting is ignored.</li>
 153             <li>External components may use the settings to carry arbitrary information with
 154                 the data source. Usually, this is used to control the behaviour of components
 155                 working with the data source.</li>
 156         </ul>
 157     */
 158     [property] sequence<com::sun::star::beans::PropertyValue> Info;
 159
 160     /** is a convenience wrapper around the <member>Info</member> property.
 161
 162         <p>Since fiddling around with a sequence of property values is somewhat uncomfortable
 163         in all known UNO language bindings (especially for tasks like simply changing the value
 164         of an existing value), the <member>Settings</member> property wraps the <member>Info</member>
 165         property for easier single-value access.</p>
 166
 167         <p>You should use the <member>Setting</member> property if you need to access a few properties only,
 168         and the <member>Info</member> property if you need access to all existent settings at once.</p>
 169
 170         <p>The object represented by this property supports the <type scope="com::sun::star::beans">PropertyBag</type>
 171         service. That is, you can at runtime add arbitrary new properties to the bag.</p>
 172
 173         <p>Additionally, the property bag supports default values of properties, and thus the
 174         <type scope="com::sun::star::beans">XPropertyState</type> interface. If you add an own property to
 175         the bag using <member scope="com::sun::star::beans">XPropertyContainer::addProperty</member>, you need
 176         to specifiy an initial value, which is also used as default value (exceptions see below).</p>
 177
 178         <p>Effectively, the property bag represented by <code>Settings</code> contains two classes of properties:
 179         Pre-defined ones and user-defined ones.</p>
 180
 181         <p><em>Pre-defined</em> properties are properties which are potentially used by the data source, the
 182         application UI for the data source, or a particular backend driver employed by the data source. There's
 183         a large set of such properties, no all of them are effectively used for a concrete data source, nonetheless,
 184         they're all present in the <code>Settings</code>.<br/>
 185         Such properties are not removeable from the bag, that is, their
 186         <member scope="com::sun::star::beans">PropertyAttribute::REMOVEABLE</member> attribute is <em>not</em> set.<br/>
 187         Usually, you'll find that all of this properties have the
 188         <member scope="com::sun::star::beans::">PropertyState::PropertyState_DEFAULT_VALUE</member> state.</p>
 189
 190         <p><em>User-defined</em> properties are the ones which are added at runtime by any instance. They might or might
 191         not be removeable, this depends on whether or not the code adding them specifies the
 192         <member scope="com::sun::star::beans">PropertyAttribute::REMOVEABLE</member> attribute. Also, they might
 193         or might not have a default value, determined by the
 194         <member scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</member> attribute at the time they're added
 195         to the bag.</p>
 196
 197         <p>When a data source is made persistent, then properties which are not removeable (which are assumed to be the
 198         pre-defined properties) are ignored when they are in <code>DEFAULT</code> state. All other properties are
 199         always made persistent, except when an explicit
 200         <member scope="com::sun::star::beans">PropertyAttribute::TRANSIENT</member> attribute prohibits this.</p>
 201
 202         <p>Similar, when you obtain the <member>Info</member> property of a <code>DataSource</code>, the
 203         <code>Settings</code> bag is asked for all its property values, and the ones which are removeable and
 204         in state default are stripped, and <em>not</em> returned in the <code>Info</code> sequence.</p>
 205     */
 206     [property, readonly, optional] com::sun::star::beans::XPropertySet Settings;
 207
 208     /** determines a users login name.
 209      */
 210     [property] string User;
 211
 212
 213     /** determines a users password. The password is not persistent.
 214      */
 215     [property] string Password;
 216
 217
 218     /** indicates that a password is always necessary.
 219      */
 220     [property] boolean IsPasswordRequired;
 221
 222
 223     /** indicates that components displaying data obtained from this
 224         data source should suppress columns used for versioning.
 225      */
 226     [property] boolean SuppressVersionColumns;
 227
 228
 229     /** determines whether modifications on the data source are allowed or not.
 230      */
 231     [readonly, property] boolean IsReadOnly;
 232
 233
 234     /** provides an object for formatting numbers.
 235      */
 236     [readonly, property] com::sun::star::util::XNumberFormatsSupplier
 237                         NumberFormatsSupplier;
 238
 239
 240     /** defines a list of tables, on which the DataSource should have it's focus.
 241         If empty, all tables are rejected.
 242
 243     */
 244     [property] sequence<string> TableFilter;
 245
 246
 247     /** defines a list of table types, on which the DataSource should have it's focus.
 248              If empty, all table types are rejected.
 249
 250     */
 251     [property] sequence<string> TableTypeFilter;
 252 };
 253
 254 //=============================================================================
 255
 256 }; }; }; };
 257
 258 #endif