Registries in UNO |
This document provides information about meaning and usage of UNO-registries within arbitrary UNO processes.
UNO-registries store binary data in a tree-like structure. It has nothing to do with the windows registry (except that they follow a similar concept). UNO-registries mainly store two types of data
UNO has chosen to store these information into a typelibrary, so that the same data is reusable from any bridge. This is in opposite to for instance the CORBA approach, where for every datatype C-code is generated which needs to be compiled and linked into huge libraries.
Both types of data are absolutely necessary to run a UNO-C++ process. Lack of the one or the other information generally leads to fast termination or crash of the program, so please avoid this. UNO processes in general open there registries during startup and close them when the process terminates.
Both types of data are in general stored into a file with a .rdb-suffix ( registry database ).
This documents explains more details about the two types of data, explains the tools how to prepare a proper registry and the different possibilities about how to bootstrap a C++ process with a registry. Another chapter deals with the registries used in OpenOffice.org.
$ regview applicat.rdb /UCR
dumps all type descriptions used within the office to stdout. One can check if a certain type is included within the registry by invoking the following command
$ regview applicat.rdb /UCR/com/sun/star/bridge/XUnoUrlResolver /UCR/com/sun/star/bridge/XUnoUrlResolver Value: Type = RG_VALUETYPE_BINARY Size = 461 Data = minor version: 0 major version: 1 type: 'interface' uik: { 0x00000000-0x0000-0x0000-0x00000000-0x00000000 } name: 'com/sun/star/bridge/XUnoUrlResolver' super name: 'com/sun/star/uno/XInterface' Doku: "" IDL source file: "O:\UDK303\src\udkapi\com\sun\star\bridge\XUnoUrlResolver.idl" number of fields: 0 number of methods: 1 method #0: com/sun/star/uno/XInterface resolve([in] string sUnoUrl) raises com/sun/star/connection/NoConnectException, com/sun/star/connection/ConnectionSetupException, com/sun/star/lang/IllegalArgumentException Doku: "" number of references: 0
The regview-tool knows the format of the binary blob containing the typedescription and dumps it in a human readable form.
For an installed OpenOffice.org, the applicat.rdb contains the registry information. The data
is stored within the /IMPLEMENTATIONS and /SERVICES key. Below you can find a sample
SERVICES key for the com.sun.star.io.Pipe
-service.
$ regview applicat.rdb /SERVICES/com.sun.star.io.Pipe /SERVICES/com.sun.star.io.Pipe Value: Type = RG_VALUETYPE_STRINGLIST Size = 38 Len = 1 Data = 0 = "com.sun.star.comp.io.stm.Pipe"
It just contains one implementation name (it may contain more than one, but in general only the first is used). Within the IMPLEMENTATIONS section, you can find the following entry :
$ regview applicat.rdb /IMPLEMENTATIONS/com.sun.star.comp.io.stm.Pipe /IMPLEMENTATIONS/com.sun.star.comp.io.stm.Pipe / UNO / ACTIVATOR Value: Type = RG_VALUETYPE_STRING Size = 34 Data = "com.sun.star.loader.SharedLibrary" / SERVICES / com.sun.star.io.Pipe / LOCATION Value: Type = RG_VALUETYPE_STRING Size = 8 Data = "stm.dll"
The implementations section holds three types of data.
com.sun.star.loader.SharedLibrary
).
There are various tools to create, modify and use registries. The command line options are discussed in detail here. This chapter shows some common use cases.
The regmerge tool is used to merge multiple registries into a subkey of an existing or new registry. For instance
$ regmerge new.rdb / test1.rdb test2.rdb
merges the contents of test1.rdb and test2.rdb into the file new.rdb. The names of the keys are preserved, because both registries are merged into the root-key. In case new.rdb existed before, the previous contents remain in new.rdb unless there exist identical keynames in either test1.rdb and test2.rdb. In this case, the content of these keys is overwritten with the ones in test1.rdb or test2.rdb. So the above command is semantically identical to
$ regmerge new.rdb / test1.rdb $ regmerge new.rdb / test2.rdb
$ regmerge myapp_types.rdb /UCR test1.urd test2.urd
merges the contents of test1.urd and test2.urd into the file myapp_types.rdb. The names of the keys in test1.urd and test2.urd get a /UCR prepended. ( The files produced by the idl-compiler have a .urd-suffix. The regmerge tool needs to be run before the typelibrary can be used in a program, because the /UCR key must be prepended ).
Components can be registered using the regcomp-tool. In the example below the components necessary to establish an interprocess connection (e.g. to a running OpenOffice.org) get registered into the myapp_services.rdb.
$ regcomp -register -r myapp_services.rdb \ -c uuresolver.dll \ -c brdgfctr.dll \ -c acceptor.dll \ -c connectr.dll \ -c remotebridge.dll(\ means here command line continuation).
The option -r gives the registry, where the information shall be written to. If it doesn't exist, it is created, otherwise the new data is added (in case there are older keys, they get overwritten). The option -c can be given multiple times, it is followed by a single library name, that shall be registered.
Registering a java-component is currently more complicated (we are working on improving the process). It works only in a installed office environment (office-install/program must be your current working directory), the office setup must point to a valid java installation (you may start jvmsetup from the office/program directory to verify this), and java must be enabled (see Extras/Options/General/Security). On Windows, you MUST copy the regcomp.exe into the office/program directory.
$ regcomp -register -br applicat.rdb \ -l com.sun.star.loader.Java2 \ -r applict.rdb \ -c file:///i:/o641d3pro/program/JavaTestComponent.jar
The -br option is used to give the regcomp-tool a registry to work on, because the regcomp-tool doesn't know, in which library the java-loader is to be found. The -l option gives the service name of the loader to use for the component (it must be com.sun.star.loader.Java2 ). The option can be omitted for C++ components, because regcomp defaults to the com.sun.star.loader.SharedLibrary loader. The option -c gives the (MANDATORY ABSOLUTE) file URL to the java component.
There are several tools, that currently access the typelibrary directly, they are mainly used during building.
StarOffice 6.0 (or OpenOffice.org 1.0) uses 2 registries, the applicat.rdb (which can be found at office-install/program/applicat.rdb) and the user60.rdb (which can be found in the home directory on Unix and within the application data directory of your personal windows profile).
The applicat.rdb contains all types which are used by the office. During setup, all chosen components get registered also into the applicat.rdb.
The user-specific user60.rdb is opened for write access and is by default empty.
Merged types can't be removed anymore. It offers maximal startup performance, as there is only one registry. In a network installation, the component is available for EVERY user. This may lead to problems in a network installation, in case there are running offices using the applicat.rdb during the merge process. This should be avoided.
The new component can then be easily removed later on (by changing the bootstrap variables to there original values). It maybe a little slower during startup (as type lookups are now performed over two registries). No matter how the bootstrap variables are modified (see below), it is safe to do it in a network installation also with running user-offices.
There are multiple ways to modify the bootstrap variables (see therefor the UNO bootstrapping document). Here are only two suggestions.
after installation, the uno.ini contains the following lines
[Bootstrap] UNO_TYPES=$SYSBINDIR/applicat.rdb UNO_SERVICES=$SYSBINDIR/applicat.rdbPlease change this to something like
[Bootstrap] UNO_TYPES=$SYSBINDIR/applicat.rdb $SYSBINDIR/mycomponent_types.rdb UNO_SERVICES=$SYSBINDIR/applicat.rdb $SYSBINDIR/mycomponent_services.rdbThe new component then gets available as soon as the offices get restarted (note that also the quickstarter needs to be terminated to really terminate the office process !).
e.g.
soffice "-env:UNO_TYPES=$SYSBINDIR/applicat.rdb file:///path/to/local/mycomponent_types.rdb" \ "-env:UNO_SERVICES=$SYSBINDIR/applicat.rdb file:///path/to/local/mycomponent_services.rdb"Here only this office is started with the new component enabled (make sure, the office really has terminated before !!).
In the ODK examples can be found a BASIC library called regcomp, which can simply be imported into the office via Tools/Macro/Organizer/Libraries/Append. Starting the first basic macro from this library opens a dialog which allows to select a component to be registered. (This is a very new feature, it may not yet be within your version of the ODK).
In this case, registration data will be written into the user60.rdb and is therefor available only for the current office-user. The component is useable directly after registration. You currently cannot add new types via this method, in case your component needs this, you need to do it in one of the ways described above.
There are many ways to bootstrap an UNO C++ application (probably too many). For every way you need to properly prepare one or multiple registry files.
TODO
Author: Joerg
Budischewski ($Date: 2004/11/27 04:05:11 $)
Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA. |