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