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

From Apache OpenOffice Wiki
Jump to: navigation, search
m (FINAL VERSION FOR L10N)
(adapted to configmgr re-write)
Line 29: Line 29:
 
The <idl>com.sun.star.configuration.ConfigurationProvider</idl> always operates in the user mode, accessing data on behalf of the current user and directing updates to the user's personal layer.
 
The <idl>com.sun.star.configuration.ConfigurationProvider</idl> 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 <idl>com.sun.star.configuration.AdministrationProvider</idl> 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 backend data store 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 {{PRODUCTNAME}} installation. Additionally there are special layers that are used by the Extension Manager for deploying configuration data associated with extensions. For details, see [[Documentation/DevGuide/Extensions/Extensions|Extensions]].  
  
−
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 {{PRODUCTNAME}} installation. To gain administrative access to this layer, no additional parameters are needed. An <idl>com.sun.star.configuration.AdministrationProvider</idl> 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 [[Documentation/DevGuide/Extensions/Extensions|Extensions]].
+
Arguments can be provided that determine the default behavior of views created through this <idl>com.sun.star.configuration.ConfigurationProvider</idl>. The following parameter may be used for this purpose:
−
 
+
−
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 <code>AdministrationProvider</code> is suppose to update configuration data.
+
−
 
+
−
A <idl>com.sun.star.configuration.AdministrationProvider</idl> is created in the same way as a <idl>com.sun.star.configuration.ConfigurationProvider</idl>.
+
−
<source lang="java">
+
−
  // 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));
+
−
</source>
+
−
As you see in the example above, the default <idl>com.sun.star.configuration.AdministrationProvider</idl> supports a special parameter for reinitialization:
+
−
 
+
−
{|border="1" cellpadding=4 style="border-collapse:collapse;"
+
−
|-bgcolor=#EDEDED
+
−
!Parameter Name
+
−
!Type
+
−
!Default
+
−
!Comments
+
−
|-
+
−
|<code>reinitialize</code>
+
−
|<code>boolean</code>
+
−
|<code>false</code>
+
−
|Discard any cached information from previous runs and regenerate from scratch.
+
−
|}
+
−
 
+
−
Some backend implementations use cached data to speed up access. If the <code>reinitialize</code> parameter is <code>true</code>, this cache will be recreated from the XML data when the <code>AdministrationProvider</code> 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 {{PRODUCTNAME}} 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 {{PRODUCTNAME}} installation. The INI entries have a prefix "CFG_" before the parameter name.
+
−
 
+
−
{{Documentation/Note|The list of available backends and the parameters they support may change in a future release. Using these parameters is normally not necessary and therefore is not recommended.}}
+
−
 
+
−
The following parameters are supported to select the backend component to use:
+
−
 
+
−
{|border="1" cellpadding=4 style="border-collapse:collapse;"
+
−
|-bgcolor=#EDEDED
+
−
!Parameter Name
+
−
!Type
+
−
!Default
+
−
!Comments
+
−
|-
+
−
|<code>BackendService</code>
+
−
|<code>string</code>
+
−
|"<idl>com.sun.star.configuration.backend.LocalSingleBackend</idl>"
+
−
|This must be a UNO service or implementation name that can be used to create a service instance. The instance created must support either service <idl>com.sun.star.configuration.backend.Backend</idl> or service <idl>com.sun.star.configuration.backend.SingleBackend</idl>
+
−
|-
+
−
|<code>BackendWrapper</code>
+
−
|<code>string</code>
+
−
|"<idl>com.sun.star.configuration.backend.SingleBackendAdapter</idl>"
+
−
|This parameter is used only, if the service specified by parameter "BackendService" only implements service <idls>com.sun.star.configuration.backend.SingleBackend</idls>, but does not support service <idls>com.sun.star.configuration.backend.Backend</idls>. It must be a UNO service or implementation name that can be used to create a service instance. The instance created must support service <idl>com.sun.star.configuration.backend.BackendAdapter</idl>.
+
−
|}
+
−
 
+
−
The following parameter was formerly supported to select the type of backend to use:
+
−
 
+
−
{|border="1" cellpadding=4 style="border-collapse:collapse;"
+
−
|-bgcolor=#EDEDED
+
−
!Parameter Name
+
−
!Type
+
−
!Default
+
−
!Comments
+
−
|-
+
−
|<code>servertype</code>
+
−
|<code>string</code>
+
−
|<code>"uno"</code>
+
−
|Other values are not supported any more in {{PRODUCTNAME}}. This setting formerly was used to select between several internal backend implementations.
+
−
|}
+
−
 
+
−
For the "<idl>com.sun.star.configuration.backend.LocalSingleBackend</idl>" backend, the following parameters are used to select the location of data:
+
−
 
+
−
{|border="1" cellpadding=4 style="border-collapse:collapse;"
+
−
|-bgcolor=#EDEDED
+
−
!Parameter Name
+
−
!Type
+
−
!Default
+
−
!Comments
+
−
|-
+
−
|<code>SchemaDataUrl</code>
+
−
|<code>string</code> or <code>string[]</code>
+
−
|$(installurl)/share/registry/schema
+
−
 
+
−
+ locations used for extensions
+
−
|This must be a file URL pointing to a directory, a whitespace-separated list of such URLs or a sequence of such URLs.
+
−
 
+
−
The locations are searched in the given order until a schema is found.
+
−
|-
+
−
|<code>DefaultLayerUrls</code>
+
−
|<code>string</code> or <code>string[]</code>
+
−
|$(installurl)/share/registry
+
−
 
+
−
+ locations used for extensions
+
−
|This must be a file URL pointing to a directory, a whitespace-separated list of such URLs or a sequence of such URLs.
+
−
 
+
−
The layers are merged in the given order.
+
−
 
+
−
The data is located in subdirectory data of each location. Additionally locale-specific data can be placed in subdirectory res.
+
−
|-
+
−
|<code>UserLayerUrl</code>
+
−
|<code>string</code>
+
−
|$(userurl)/user/registry
+
−
|This must be a file URL pointing to a directory.
+
−
 
+
−
If this is one of the entries of parameter "<code>DefaultLayerUrls</code>", then only the entries before it will be used as default layers.
+
−
 
+
−
The data is located in the subdirectory data of the given location.
+
−
|}
+
−
 
+
−
Arguments can be provided that determine the default behavior of views created through this <idl>com.sun.star.configuration.ConfigurationProvider</idl>. The following parameters may be used for this purpose:
+
  
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
Line 165: Line 44:
 
|The user's locale.  
 
|The user's locale.  
 
|This parameter was called "<code>locale</code>" in a former version. The old name is still supported for compatibility.  
 
|This parameter was called "<code>locale</code>" in a former version. The old name is still supported for compatibility.  
−
|-
 
−
|<code>EnableAsync</code>
 
−
|<code>boolean</code>
 
−
|<code>true</code>
 
−
|This parameter was called "<code>lazywrite</code>" in a former version. The old name is still supported for compatibility.
 
 
|}
 
|}
  

Revision as of 14:57, 22 June 2010



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.

The backend data store 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. Additionally there are special layers that are used by the Extension Manager for deploying configuration data associated with extensions. For details, see Extensions.

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

Parameter Name Type Default Comments
Locale string The user's locale. This parameter was called "locale" in a former version. The old name is still supported for compatibility.


Documentation caution.png 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.

Content on this page is licensed under the Public Documentation License (PDL).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/DevGuide/Config/Connecting_to_a_Data_Source&oldid=172933"
Personal tools
In other languages