Universal Content Broker Configuration |
Contents |
Abstract
|
Abstract |
This document describes ways to configure the Universal Content Broker (UCB). Before a process can use the UCB, it needs to configure it. Configuring the UCB means to register a set of Universal Content Providers (UCPs) at a Content Broker instance. Only UCPs known to the UCB can be used by it to provide content. Generally we provide two ways to configure a UCB:
|
UCP Registration Information |
To register a Content Provider at the UCB you need the following information that must have been provided be the implementer of the UCP:
|
Unconfigured UCBs |
A UCB is called "unconfigured" if it has no Content Providers. Thus it is not able to provide any contents. Each UCB implements the interface XContentProviderManager. This interface offers (among others) the functionality to register UCPs at runtime. To create an unconfigured UCB and configure it manually:
Example 1 Unconfigured UCB using namespace com::sun::star; bool initUCB() { ///////////////////////////////////////////////////////////////////// // Create Process Service Manager. This needs to be done only once // per process! Afterwards it is accessable via // comphelper::getProcessServiceFactory(). ///////////////////////////////////////////////////////////////////// uno::Reference< lang::XMultiServiceFactory > xServiceFactory; try { xServiceFactory = cppu::createRegistryServiceFactory( comphelper::getPathToSystemRegistry(), rtl::OUString(), true ); } catch ( uno::Exception const & ) {} if ( !xServiceFactory.is() ) return false; comphelper::setProcessServiceFactory( xServiceFactory ); ///////////////////////////////////////////////////////////////////// // Create UCB. This needs to be done only once per process! ///////////////////////////////////////////////////////////////////// uno::Reference< uno::XInterface > xUCB; try { xUCB = xServiceFactory->createInstance( rtl::OUString::createFromAscii( "com.sun.star.ucb.UniversalContentBroker" ) ); } catch ( uno::Exception const & ) {} if ( !xUCB.is() ) return false; ///////////////////////////////////////////////////////////////////// // Instanciate UCPs and register them at UCB. ///////////////////////////////////////////////////////////////////// uno::Reference< ucb::XContentProvider > xFileProvider; try { xFileProvider = uno::Reference< ucb::XContentProvider >( xServiceFactory->createInstance( rtl::OUString::createFromAscii( "com.sun.star.ucb.FileContentProvider" ) ), uno::UNO_QUERY ); } catch ( uno::Exception const & ) {} if ( !xFileProvider.is() ) return false; try { xUcb->registerContentProvider( xFileProvider, rtl::OUString::createFromAscii( "file" ), sal_False ); } catch ( ucb::DuplicateProviderException const & {} // Create/register other UCPs... return true; } |
Preconfigured UCBs |
A UCB is called "preconfigured" if it was given a UCB configuration at the time it was instantiated. A UCB configuration contains a set of UCP registration informations. To create a preconfigured UCB:
Note: There is a helper function (ucb::configureUcb) available in the UCBHELPER library, which contains all code necessary to instantiate a preconfigured UCB. Example 2 Preconfigured UCB using namespace com::sun::star; bool initUCB() { ///////////////////////////////////////////////////////////////////// // Create Process Service Manager. This needs to be done only once // per process! Afterwards it is accessable via // comphelper::getProcessServiceFactory(). ///////////////////////////////////////////////////////////////////// uno::Reference< lang::XMultiServiceFactory > xServiceFactory; try { xServiceFactory = cppu::createRegistryServiceFactory( comphelper::getPathToSystemRegistry(), rtl::OUString(), true ); } catch ( uno::Exception const & ) {} if ( !xServiceFactory.is() ) return false; comphelper::setProcessServiceFactory( xServiceFactory ); ///////////////////////////////////////////////////////////////////// // Create UCB. This needs to be done only once per process! ///////////////////////////////////////////////////////////////////// // Supply configuration to use for this UCB instance... uno::Sequence< uno::Any > aArgs( 2 ); aArgs[ 0 ] <<= rtl::OUString::createFromAscii( "Local" ); aArgs[ 1 ] <<= rtl::OUString::createFromAscii( "Office" ); uno::Reference< uno::XInterface > xUCB; try { xUCB = xServiceFactory->createInstanceWithArguments( rtl::OUString::createFromAscii( "com.sun.star.ucb.UniversalContentBroker" ), aArgs ); } catch ( uno::Exception const & ) {} if ( !xUCB.is() ) return false; return true; } |
UCB Configurations |
Each UCB configuration contains data that describe a set of UCPs (UCP registration information). All UCPs contained in a configuration will be registered at the UCB that shall be created using this configuration. A UCB configuration is identified by two keys, which are strings. UCB configurations are defined in XML. The predefined configurations for OpenOffice are defined in the file officecfg/data/org/openoffice/ucb/Configuration.xcd. This file must be adapted to add configurations or to edit existing configurations. The XCD file will be used by the OpenOffice build process to generate an appropriete XML file. This XML file is part of an OpenOffice installation. The UCB will always try to get configuration data from that XML file. Note: There are several predefined UCB configurations. The standard configuration is "Local" and "Office", which generally allows access to all UCPs. Example 3 UCB Configuration (org/openoffice/ucb/Configuration.xcd) <!DOCTYPE schema:package SYSTEM "../schema/schema.description.dtd"> <schema:package package-id="org.openoffice.ucb.Configuration" xml:lang="en-US" xmlns:schema="http://openoffice.org/2000/registry/schema/description" xmlns:default="http://openoffice.org/2000/registry/schema/default" xmlns:cfg="http://openoffice.org/2000/registry/instance"> <schema:templates template-id="org.openoffice.ucb.Configuration"> <!-- ContentProvider --> <schema:group cfg:name="ContentProviderData"> <schema:value cfg:name="ServiceName" cfg:type="string"> </schema:value> <schema:value cfg:name="URLTemplate" cfg:type="string"> </schema:value> <schema:value cfg:name="Arguments" cfg:type="string"> </schema:value> </schema:group> <!-- ContentProvidersDataSecondaryKeys --> <schema:group cfg:name="ContentProvidersDataSecondaryKeys"> <schema:set cfg:name="ProviderData" cfg:element-type="ContentProviderData"/> </schema:group> <!-- ContentProvidersDataPrimaryKeys --> <schema:group cfg:name="ContentProvidersDataPrimaryKeys"> <schema:set cfg:name="SecondaryKeys" cfg:element-type="ContentProvidersDataSecondaryKeys"/> </schema:group> </schema:templates> <schema:component cfg:writable="true" component-id="org.openoffice.ucb.Configuration" cfg:notified="true" cfg:localized="false"> <schema:set cfg:name="ContentProviders" cfg:element-type="ContentProvidersDataPrimaryKeys"> <default:group cfg:name="Local"> <default:set cfg:name="SecondaryKeys" cfg:element-type="ContentProvidersDataSecondaryKeys"> <default:group cfg:name="Office"> <default:set cfg:name="ProviderData" cfg:element-type="ContentProviderData"> <!-- Hierarchy UCP --> <default:group cfg:name="Provider1"> <default:value cfg:name="ServiceName" cfg:type="string"> <default:data>com.sun.star.ucb.HierarchyContentProvider</default:data> </default:value> <default:value cfg:name="URLTemplate" cfg:type="string"> <default:data>vnd.sun.star.hier</default:data> </default:value> <default:value cfg:name="Arguments" cfg:type="string"> <default:data/> </default:value> </default:group> <!-- File UCP --> <default:group cfg:name="Provider2"> <default:value cfg:name="ServiceName" cfg:type="string"> <default:data>com.sun.star.ucb.FileContentProvider</default:data> </default:value> <default:value cfg:name="URLTemplate" cfg:type="string"> <default:data>file</default:data> </default:value> <default:value cfg:name="Arguments" cfg:type="string"> <default:data/> </default:value> </default:group> <!-- Other UCPs go here --> </default:set> </default:group> </default:set> </default:group> </schema:set> </schema:component> </schema:package> |
Content Provider Proxies |
As the reader may have noticed, the UNO service implementing a UCP must be instantiated at the time the Content Provider is registered at the UCB Again, this is done using XContentProviderManager's registerContentProvider method. In some cases this can consume to much resources, because instantiating a UNO service means loading the libraries containing its code. And as a convention each UNO component should reside in its own library. That's why we offer a special UNO service, that provides a generic proxy for a UCP. It's main purpose is to delay loading of the real UCP's code until it is really needed. Generally this will be not the case before the first createContentIdentifier/queryContent calls are done at the proxy. Instead of registering the real instantiated UCP at the UCB, a proxy will be created for the UCP. The UCP registration information will be passed to the proxy. The proxy will use this information to instantiate the real UCP on demand only. There is almost no performance overhead with this mechanism. Note: When using preconfigured UCBs, the UCB implementation will use proxies instead of the real UCPs to avoid wasting resources. |
|
|
Author: Kai
Sommerfeld ($Date: 2001/04/20 11:13:50 $) |
|