Language:

The Free and Open Productivity Suite
Apache OpenOffice 4.1.3 released

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


:: com :: sun :: star :: sdb ::

service DataSource
Description
is a factory to establish database connections. It should be registered at a ::com::sun::star::uno::NamingService.
See also
DatabaseContext
Developers Guide
Database - The DataSource Service

Exported Interfaces - Summary
::com::sun::star::beans::XPropertySet
(referenced entity's summary:)
provides information about and access to the properties from an implementation.
XCompletedConnection

useful for establishing connections with the completion of connection parameters provided during user interaction.

::com::sun::star::sdbc::XIsolatedConnection

useful for establishing isolated connections which are not shared among others as it is the case when using XCompletedConnection or ::com::sun::star::sdbc::XDataSource. (details)

::com::sun::star::util::XFlushable

is provided to flush a DataSource within to a Database Context.

XQueryDefinitionsSupplier

provides the access to DataSource related queries. (details)

::com::sun::star::sdbc::XDataSource
(referenced entity's summary:)
is used for establishing connections via a factory which is identified by its name. A DataSource object is typically registered by a naming service provider.
XBookmarksSupplier

provides access to bookmarks to documents associated with the data source (details)

Properties' Summary
[ readonly ] string
Name
is the name of the data source.  
string
URL
indicates a database url of the form
jdbc:subprotocol:subname or sdbc:subprotocol:subname  
sequence< ::com::sun::star::beans::PropertyValue >
Info
is a list of arbitrary string tag/value pairs as connection arguments  
[ readonly ] ::com::sun::star::beans::XPropertySet
Settings
[ OPTIONAL ]
is a convenience wrapper around the Info property.  
string
User
determines a users login name.  
string
Password
determines a users password. The password is not persistent.  
boolean
IsPasswordRequired
indicates that a password is always necessary.  
boolean
SuppressVersionColumns
indicates that components displaying data obtained from this data source should suppress columns used for versioning.  
[ readonly ] boolean
IsReadOnly
determines whether modifications on the data source are allowed or not.  
[ readonly ] ::com::sun::star::util::XNumberFormatsSupplier
NumberFormatsSupplier
provides an object for formatting numbers.  
sequence< string >
TableFilter
defines a list of tables, on which the DataSource should have it's focus. If empty, all tables are rejected.  
sequence< string >
TableTypeFilter
defines a list of table types, on which the DataSource should have it's focus. If empty, all table types are rejected.  
Exported Interfaces - Details
::com::sun::star::beans::XPropertySet
(referenced entity's summary:)
provides information about and access to the properties from an implementation.
XCompletedConnection
Description
useful for establishing connections with the completion of connection parameters provided during user interaction.
::com::sun::star::sdbc::XIsolatedConnection
Description
useful for establishing isolated connections which are not shared among others as it is the case when using XCompletedConnection or ::com::sun::star::sdbc::XDataSource.
Since
OOo 1.1.2
See also
XCompletedConnection, ::com::sun::star::sdbc::XDataSource
::com::sun::star::util::XFlushable
Description
is provided to flush a DataSource within to a Database Context.
XQueryDefinitionsSupplier
Description
provides the access to DataSource related queries.

The object returned by the XQueryDefinitionsSupplier::getQueryDefinitions() supports the DefinitionContainer service.

::com::sun::star::sdbc::XDataSource
(referenced entity's summary:)
is used for establishing connections via a factory which is identified by its name. A DataSource object is typically registered by a naming service provider.
XBookmarksSupplier
Usage Restrictions
optional
Description
provides access to bookmarks to documents associated with the data source

The object returned by the XBookmarksSupplier::getBookmarks() supports the DefinitionContainer service.

Properties' Details
Name
[ readonly ] string Name;
Description
is the name of the data source.

If the data source is registered at the database context, then the Name property denotes the registration name. Otherwise, the name property contains the URL of the file which the database document associated with the data source is based on.

If the same data source is registered under different names, the value of the Name property is not defined.

URL
string URL;
Description
indicates a database url of the form
jdbc:subprotocol:subname or sdbc:subprotocol:subname
Info
sequence< ::com::sun::star::beans::PropertyValue > Info;
Description
is a list of arbitrary string tag/value pairs as connection arguments

The DataSource itself does not attempt to interpret any of those values.

Instead, the values in this property have two use cases:

  • Upon creating a connection, for every value in this sequence it's checked whether the ::com::sun::star::sdbc::XDriver which is to provide the connection supports a setting with the respective name, using its If so, the settings is passed to the drivers's If not, the setting is ignored.
  • External components may use the settings to carry arbitrary information with the data source. Usually, this is used to control the behaviour of components working with the data source.
Settings
[ readonly ] ::com::sun::star::beans::XPropertySet Settings;
Usage Restrictions
optional
Description
is a convenience wrapper around the Info property.

Since fiddling around with a sequence of property values is somewhat uncomfortable in all known UNO language bindings (especially for tasks like simply changing the value of an existing value), the Settings property wraps the Info property for easier single-value access.

You should use the Setting property if you need to access a few properties only, and the Info property if you need access to all existent settings at once.

The object represented by this property supports the ::com::sun::star::beans::PropertyBag service. That is, you can at runtime add arbitrary new properties to the bag.

Additionally, the property bag supports default values of properties, and thus the ::com::sun::star::beans::XPropertyState interface. If you add an own property to the bag using ::com::sun::star::beans::XPropertyContainer::addProperty, you need to specifiy an initial value, which is also used as default value (exceptions see below).

Effectively, the property bag represented by Settings contains two classes of properties: Pre-defined ones and user-defined ones.

Pre-defined properties are properties which are potentially used by the data source, the application UI for the data source, or a particular backend driver employed by the data source. There's a large set of such properties, no all of them are effectively used for a concrete data source, nonetheless, they're all present in the Settings.
Such properties are not removeable from the bag, that is, their ::com::sun::star::beans::PropertyAttribute::REMOVEABLE attribute is not set.
Usually, you'll find that all of this properties have the ::com::sun::star::beans::PropertyState::PropertyState_DEFAULT_VALUE state.

User-defined properties are the ones which are added at runtime by any instance. They might or might not be removeable, this depends on whether or not the code adding them specifies the ::com::sun::star::beans::PropertyAttribute::REMOVEABLE attribute. Also, they might or might not have a default value, determined by the ::com::sun::star::beans::PropertyAttribute::MAYBEDEFAULT attribute at the time they're added to the bag.

When a data source is made persistent, then properties which are not removeable (which are assumed to be the pre-defined properties) are ignored when they are in DEFAULT state. All other properties are always made persistent, except when an explicit ::com::sun::star::beans::PropertyAttribute::TRANSIENT attribute prohibits this.

Similar, when you obtain the Info property of a DataSource, the Settings bag is asked for all its property values, and the ones which are removeable and in state default are stripped, and not returned in the Info sequence.

User
string User;
Description
determines a users login name.
Password
string Password;
Description
determines a users password. The password is not persistent.
IsPasswordRequired
boolean IsPasswordRequired;
Description
indicates that a password is always necessary.
SuppressVersionColumns
boolean SuppressVersionColumns;
Description
indicates that components displaying data obtained from this data source should suppress columns used for versioning.
IsReadOnly
[ readonly ] boolean IsReadOnly;
Description
determines whether modifications on the data source are allowed or not.
NumberFormatsSupplier
[ readonly ] ::com::sun::star::util::XNumberFormatsSupplier NumberFormatsSupplier;
Description
provides an object for formatting numbers.
TableFilter
sequence< string > TableFilter;
Description
defines a list of tables, on which the DataSource should have it's focus. If empty, all tables are rejected.
TableTypeFilter
sequence< string > TableTypeFilter;
Description
defines a list of table types, on which the DataSource should have it's focus. If empty, all table types are rejected.

 
Top of Page

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache and the Apache feather logo are trademarks of The Apache Software Foundation. OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.