The Free and Open Productivity Suite
Follow us on Twitter: @ApacheOO

OpenOffice.orgUniversal Content Broker Configuration


Contents

Abstract
UCP Registration Information
Unconfigured UCBs
Preconfigured UCBs
UCB Configurations
Content Provider Proxies


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:

  • Create a "raw" UCB with no UCPs registered and register all needed UCPs manually.

  • Define a UCB configuration and create a UCB automatically configured with the UCPs given in that configuration.


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:

  • The UNO service name to use to instantiate the UCP (for example com.sun.star.ucb.FileContentProvider). Each UCP must be implemented and registered as a UNO service. Refer to the UNO Development Kit Project for more information on UNO services.

  • An URL template, used by the UCB to select among the registered UCPs the one that best 'fits' an incomming URL (XContentIdentifier). This can be either the name of an URL scheme (e.g., file will select the given UCP for all file URLs) or a 'limited' regular expression (e.g., "http://"[^/?#]*".com"([/?#].*)? will select the given UCP for all http URLs in the com domain). See the documentation of XContentProviderManager's registerContentProvider method for details about those regular expressions.

  • Additional arguments that may be needed by 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:

  • Create and set the UNO Service Manager.

  • Create an instance of the UNO service "com.sun.star.ucb.UniversalContentBroker".

  • Register the appropriate UCPs by using the UCB's XContentProviderManager interface.


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:

  • Create and set the UNO Service Manager.

  • Create an instance of the UNO service "com.sun.star.ucb.UniversalContentBroker". Pass the configuration to use as parameters to the creation function. The UCB instance returned will have registered all UCPs defined in the given configuration.

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 $)
Copyright 2001 OpenOffice.org Foundation. All Rights Reserved.



Apache Software Foundation

Copyright & License | Privacy | Website Feedback | Contact Us | Donate | Thanks

Apache, the Apache feather logo, and OpenOffice are trademarks of The Apache Software Foundation. OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.