Difference between revisions of "Documentation/DevGuide/Database/The DataSource Service"
(Initial author Sun Microsystems, Inc.) |
(No difference)
|
Revision as of 12:09, 1 November 2007
- The DataSource Service
- Queries
The com.sun.star.sdb.DataSource service includes all the features of a database defined in OpenOffice.org API. DataSource
provides the following properties for its knowledge about how to connect to a database and which tables to display:
Properties of com.sun.star.sdb.DataSource | |
---|---|
Name | [readonly] string - The name of the data source.
|
URL | string - Indicates a database URL. Valid URL formats are:
|
Info | sequence< com.sun.star.beans.PropertyValue > . A list of arbitrary string tag or value pairs as connection arguments.
|
User | string - The login name of the current user.
|
Password | string - The password of the current user. It is not stored with the data source.
|
IsPasswordRequired | boolean - Indicates that a password is always necessary and might be interactively requested from the user by an interaction handler.
|
IsReadOnly | [readonly] boolean - Determines if database contents may be modified.
|
NumberFormatsSupplier | [readonly] XNumberFormatsSupplier. Provides an object for number formatting.
|
TableFilter | sequence< string > . A list of tables the data source should display. If empty, all tables are hidden. Valid placeholders are % and ? .
|
TableTypeFilter | sequence< string > . A list of table types the DataSource should display. If empty, all table types are rejected. Possible type strings are TABLE , VIEW , and SYSTEM TABLE/code>.
|
SuppressVersionColumns | <code>boolean - Indicates that components displaying data obtained from this data source should suppress columns used for versioning. |
All other capabilities of a DataSource
, such as query definitions, forms, reports, and the actual process of establishing connections are available over its interfaces.
- com.sun.star.sdb.XQueryDefinitionsSupplier provides access to SQL query definitions for a database. The definition of queries is discussed in the next section, Queries.
- com.sun.star.sdb.XCompletedConnection connects to a database. It asks the user to supply necessary information before it connects. The section Connecting Through a DataSource shows how to establish a connection.
- com.sun.star.sdb.XBookmarksSupplier provides access to bookmarks pointing at documents associated with the DataSource, primarily OpenOffice.org API documents containing form components. Although it is optional, it is implemented for all data sources in OpenOffice.org API. The section Forms and Other Links explains database bookmarks.
- com.sun.star.util.XFlushable forces the data source to flush all information including the properties above to the Open Office database file. However, changes work immediately and are stored in the Open Office database file format.com.sun.star.sdb.XFormDocumentsSupplier provides access to forms stored inside the Open Office database file.
- com.sun.star.sdb.XReportDocumentsSupplier provides access to reports stored inside the Open Office database file.
- com.sun.star.sdb.OfficeDatabaseDocument provides all interfaces which the com.sun.star.document.OfficeDocument service supports.
Adding and Editing Datasources
New data sources have to be created by the com.sun.star.lang.XSingleServiceFactory interface of the database context. A new data source can be registered with the database context at its com.sun.star.uno.XNamingService interface and the necessary properties set.
The lifetime of data sources is controlled through the interfaces com.sun.star.lang.XSingleServiceFactory, com.sun.star.uno.XNamingService and com.sun.star.container.XContainer of the database context.
The method createInstance()
of XSingleServiceFactory
creates new generic data sources. They are added to the database context using registerObject()
at the interface com.sun.star.uno.XNamingService. The XNamingService
allows registering data sources, as well as revoking the registration. The following are the methods defined for XNamingService
:
void registerObject( [in] string Name, [in] com::sun::star::uno::XInterface Object) void revokeObject( [in] string Name) com::sun::star::uno::XInterface getRegisteredObject( [in] string Name)
Before data sources can be registered at the database context, they have to be stored with the com.sun.star.frame.XStorable interface. The method storeAsURL
should be used for that purpose.
In the following example, a data source is created for a previously generated Adabas D database named MYDB1 on the local machine. The URL
property has to be present, and for Adabas D the property IsPasswordRequired
should be true, otherwise no interactive connection can be established. The password dialog requests a user name by setting the User property.
// creates a new DataSource public static void createNewDataSource(XMultiServiceFactory _rMSF) throws com.sun.star.uno.Exception { // the XSingleServiceFactory of the database context creates new generic // com.sun.star.sdb.DataSources (!) // retrieve the database context at the global service manager and get its // XSingleServiceFactory interface XSingleServiceFactory xFac = (XSingleServiceFactory)UnoRuntime.queryInterface( XSingleServiceFactory.class, _rMSF.createInstance("com.sun.star.sdb.DatabaseContext")); // instantiate an empty data source at the XSingleServiceFactory // interface of the DatabaseContext Object xDs = xFac.createInstance(); // register it with the database context XNamingService xServ = (XNamingService)UnoRuntime.queryInterface(XNamingService.class, xFac); XStorable store = ( XStorable)UnoRuntime.queryInterface(XStorable.class, xDs); XModel model = ( XModel)UnoRuntime.queryInterface(XModel.class, xDs); store.storeAsURL("file:///c:/test.odb",model.getArgs()); xServ.registerObject("NewDataSourceName", xDs); // setting the necessary data source properties XPropertySet xDsProps = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xDs); // Adabas D URL xDsProps.setPropertyValue("URL", "sdbc:adabas::MYDB1"); // force password dialog xDsProps.setPropertyValue("IsPasswordRequired", new Boolean(true)); // suggest dsadmin as user name xDsProps.setPropertyValue("User", "dsadmin"); store.store(); }
The various possible database URLs are discussed in the section Driver Specifics.
To edit an existing data source, retrieve it by name or by file URL from the com.sun.star.container.XNameAccess interface of the database context and use its com.sun.star.beans.XPropertySet interface to configure it, as required. To store the newly edited data source, you must use the com.sun.star.frame.XStorable interface.
Content on this page is licensed under the Public Documentation License (PDL). |