Bootstrapping a Service Manager

From Apache OpenOffice Wiki
Jump to: navigation, search



Bootstrapping a service manager means to create an instance of a service manager that is able to instantiate the UNO objects needed by a user. All UNO applications, that want to use the UnoUrlResolver for connections to the office, have to bootstrap a local service manager in order to create a UnoUrlResolver object. If developers create a new language binding, for instance for a scripting engine, they have to find a way to bootstrap a service manager in the target environment.

There are many methods to bootstrap a UNO C++ application, each requiring one or more registry files to be prepared. Once the registries are prepared, there are different options available to bootstrap your application. A flexible approach is to use UNO bootstrap parameters and the defaultBootstrap_InitialComponentContext() function.

  #include <cppuhelper/bootstrap.hxx>
 
  using namespace com::sun::star::uno;
  using namespace com::sun::star::lang;
  using namespace rtl;
  using namespace cppu;
  int main( )
  {
      // create the initial component context
      Reference< XComponentContext > rComponentContext =
          defaultBootstrap_InitialComponentContext();
 
      // retrieve the service manager from the context
      Reference< XMultiComponentFactory > rServiceManager = 
          rComponentContext()->getServiceManager();
 
      // instantiate a sample service with the service manager.
      Reference< XInterface > rInstance =
          rServiceManger->createInstanceWithContext( 
          OUString::createFromAscii("com.sun.star.bridge.UnoUrlResolver" ),
              rComponentContext );
 
      // continue to connect to the office ....
  }

No arguments, such as a registry name, are passed to this function. These are given using bootstrap parameters. Bootstrap parameters can be passed through a command line, an .ini file or using environment variables.

For bootstrapping the UNO component context, the following two variables are relevant:

  1. UNO_TYPES: Gives a space separated list of type library registry files. Each registry must be given as an absolute or relative file url. Note that some special characters within the path require encoding, for example, a space must become a %20. The registries are opened in read-only.
  2. UNO_SERVICES: Gives a space separated list of registry files with component registration information. The registries are opened in read-only. The same registry may appear in UNO_TYPES and UNO_SERVICES variables.

An absolute file URL must begin with the file:/// prefix (on Windows, it must look like file:///c:/mytestregistry.rdb). To make a file URL relative, the file:/// prefix must be omitted. The relative url is interpreted relative to the current working directory.

Within the paths, use special placeholders.

Bootstrap variable Meaning
$SYSUSERHOME Path of the user's home directory (see osl_getHomeDir())
$SYSBINDIR Path to the directory of the current executable.
$ORIGIN Path to the directory of the ini/rc file.
$SYSUSERCONFIG Path to the directory where the user's configuration data is stored (see osl_getConfigDir())

The advantage of this method is that the executable can be configured after it has been built. The Apache OpenOffice bootstraps the service manager with this mechanism.

Consider the following example:

A tool needs to be written that converts documents between different formats. This is achieved by connecting to Apache OpenOffice and doing the necessary conversions. The tool is named docconv. In the code, the defaultBootstrap_InitialComponentContext() function is used as described above to create the component context. Two registries are prepared: docconv_services.rdb with the registered components and types.rdb that contains the types coming with Apache OpenOffice. Both files are placed beside the executable. The easiest method to configure the application is to create a docconv(.ini|rc) ascii file in the same folder as your executable, that contains the following two lines:

 UNO_TYPES=$ORIGIN/types.rdb
 UNO_SERVICES=$ORIGIN/docconv_services.rdb

No matter where the application is started form, it will always use the mentioned registries. Note that this also works on different machines when the volume is mapped to different location mount points as $SYSBINDIR is evaluated at runtime.

The second possibility is to set UNO_TYPES and UNO_SERVICES as environment variables, but this method has drawbacks. All UNO applications started with this shell use the same registries.

The third possibility is to pass the variables as command line parameters, for instance

 docconv -env:UNO_TYPES=$ORIGIN/types.rdb -env:
 UNO_SERVICES=$ORIGIN/docconv_services.rdb

Note that on UNIX shells, you need to quote the $ with a backslash \.

The command line arguments do not need to be passed to the UNO runtime, because it is generally retrieved from some static variables. How this is done depends on the operating system, but it is hidden from the programmer. The docconv executable should ignore all command line parameters beginning with '-env:'. The easiest way to do this is to ignore argc and argv[] and to use the rtl_getCommandLineArg() functions defined in rtl/process.h header instead which automatically strips the additional parameters.

  1. Combine the methods mentioned above. Command line parameters take precedence over .ini file variables and .ini file parameter take precedence over environment variables. That way, it is possible to overwrite the UNO_SERVICES variable on the command line for one invocation of the program only.
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages