xref: /trunk/main/offapi/com/sun/star/sdb/DataSource.idl (revision c4dc0a1a)
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