offapi/com/sun/star/sdb/DataSource.idl

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