The DataSource Service

From Apache OpenOffice Wiki
Jump to: navigation, search



The com.sun.star.sdb.DataSource service includes all the features of a database defined in Apache OpenOffice 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:
  • jdbc: subprotocol : subname
  • sdbc: subprotocol : subname
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.
SuppressVersionColumns 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.

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 username 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 username
      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).
Personal tools
In other languages