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 */ 68published 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 256