Difference between revisions of "Documentation/DevGuide/Config/Connecting to a Data Source"

Revision as of 19:44, 4 April 2008

The first step to access the configuration database is to connect to a configuration data source.

To obtain a provider instance ask the global com.sun.star.lang.ServiceManager for a com.sun.star.configuration.ConfigurationProvider. Typically the first lines of code to get access to configuration data look similar to the following:

  // get my global service manager 
  XMultiServiceFactory xServiceManager = (XMultiServiceFactory)UnoRuntime.queryInterface(
  XMultiServiceFactory.class, this.getRemoteServiceManager(
      "uno:socket,host=localhost,port=2083;urp;StarOffice.ServiceManager")); 
 
  final String sProviderService = "com.sun.star.configuration.ConfigurationProvider";
 
  // create the provider and remember it as a XMultiServiceFactory
  XMultiServiceFactory xProvider = (XMultiServiceFactory)
      UnoRuntime.queryInterface(XMultiServiceFactory.class, 
          xServiceManager.createInstance(sProviderService));

This code creates a default com.sun.star.configuration.ConfigurationProvider. The most important interface a com.sun.star.configuration.ConfigurationProvider implements is com.sun.star.lang.XMultiServiceFactory that is used to create further configuration objects.

The com.sun.star.configuration.ConfigurationProvider always operates in the user mode, accessing data on behalf of the current user and directing updates to the user's personal layer.

For administrative access to manipulate the default layers the com.sun.star.configuration.AdministrationProvider is used. When creating this service, additional parameters can be used that select the layer for updates or that contain credentials used to authorize administrative access. The backend that is used determines which default layers exist, how they are addressed and how administrative access is authorized.

The standard file-based backend has several shared layers. One of these layers is used to store shared default data. The files for this layer are located in the share directory of the OpenOffice.org installation. To gain administrative access to this layer, no additional parameters are needed. An com.sun.star.configuration.AdministrationProvider for this backend automatically tries to read and write this shared layer. Additionally there are special layers that are used by the Extension Manager for deploying configuration data associated with extensions. For details, see Extensions.

Authorization for the file-based backend is done by the operating system based upon file access privileges. The current user requires write privileges in the shared configuration directory if an AdministrationProvider is suppose to update configuration data.

A com.sun.star.configuration.AdministrationProvider is created in the same way as a com.sun.star.configuration.ConfigurationProvider.

  // get my global service manager
  XMultiServiceFactory xServiceManager = getServiceManager();
 
  // get the arguments to use 
  com.sun.star.beans.PropertyValue aReinitialize = new com.sun.star.beans.PropertyValue()
  aReinitialize.Name = "reinitialize"
  aReinitialize.Value = new Boolean(true);
 
  Object[] aProviderArguments = new Object[1];
  aProviderArguments[0] = aReinitialize;
 
  final String sAdminService = "com.sun.star.configuration.AdministrationProvider";
 
  // create the provider and remember it as a XMultiServiceFactory
  XMultiServiceFactory xAdminProvider = (XMultiServiceFactory)
      UnoRuntime.queryInterface(XMultiServiceFactory.class,
          xServiceManager.createInstanceWithArguments(sAdminService,aProviderArguments));

As you see in the example above, the default com.sun.star.configuration.AdministrationProvider supports a special parameter for reinitialization:

Some backend implementations use cached data to speed up access. If the reinitialize parameter is true, this cache will be recreated from the XML data when the AdministrationProvider is created. With the current implementation, the parameter has no effect.

When establishing the connection, specify the parameters that select the backend to use and additional backend-specific parameters to select the data source. When there are no parameters given, the standard configuration backend and data source of the OpenOffice.org installation is used.

The standard values for these parameters may be found in the configuration file configmgr(.ini|rc) (.ini on Windows, rc on Unix) in the program directory of the OpenOffice.org installation. The INI entries have a prefix "CFG_" before the parameter name.

Template:Documentation/Note

The following parameters are supported to select the backend component to use:

The following parameter was formerly supported to select the type of backend to use:

For the "com.sun.star.configuration.backend.LocalSingleBackend" backend, the following parameters are used to select the location of data:

Arguments can be provided that determine the default behavior of views created through this com.sun.star.configuration.ConfigurationProvider. The following parameters may be used for this purpose:

The default configuration provider obtained when no arguments are given will always be the same object. Be careful not to call <idlml>com.sun.star.lang.XComponent:dispose</idlml>() on this shared com.sun.star.configuration.ConfigurationProvider. If you provide any arguments, then a new instance is created. You must then call <idlml>com.sun.star.lang.XComponent:dispose</idlml>() on this com.sun.star.configuration.ConfigurationProvider.