Component Context

OpenOffice.org Developer's Guide

Professional UNO

< Previous Section

Next Section >

• Introduction
• API Concepts

• Data Types

• Simple Types
• The Any Type
• Interfaces
• Services
• Structs
• Predefined Values
• Sequences
• Modules
• Exceptions
• Singletons

• Understanding the API Reference

• UNO Concepts

• UNO Interprocess Connections

• Starting OpenOffice.org in Listening Mode
• Importing a UNO Object
• Characteristics of the Interprocess Bridge
• Opening a Connection
• Creating the Bridge
• Closing a Connection
• Example: A Connection Aware Client

• Service Manager and Component Context

• Service Manager
• Component Context

• Using UNO Interfaces
• Properties
• Collections and Containers
• Event Model
• Exception Handling
• Lifetime of UNO objects

• acquire() and release()
• The XComponent Interface
• Children of the XEventListener Interface
• Weak Objects and References
• Differences Between the Lifetime of C++ and Java Objects

• Object Identity

• UNO Language Bindings

• Java Language Binding

• Getting a Service Manager
• Transparent Use of Office UNO Components
• Handling Interfaces
• Type Mappings

• Mapping of Sequence Types
• Mapping of Enum Types
• Mapping of Struct Types
• Mapping of Exception Types
• Mapping of Interface Types
• Mapping of UNOIDL
• Mapping of Services
• Mapping of Singletons
• Inexact approximation of UNO Value Semantics

• C++ Language Binding

• Establishing Interprocess Connections
• Transparent Use of Office UNO Components
• Type Mappings

• Mapping of Struct Types
• Mapping of Interface Types
• Mapping of Sequence Types
• Mapping of Services
• Mapping of Singletons

• Using Weak References
• Exception Handling in C++

• OpenOffice.org Basic

• Handling UNO Objects

• Instantiating UNO Services
• Getting Information about UNO Objects

• Mapping of UNO and Basic Types

• Mapping of Simple Types
• Mapping of Sequences and Arrays
• Mapping of Structs
• Mapping of Enums and Constant Groups

• Case Sensitivity
• Exception Handling
• Listeners

• Automation Bridge

• The Service Manager Component
• Using UNO from Automation

• Calling Functions and Accessing Properties
• Return Values
• Usage of Types

• Using Automation Objects from UNO
• Type Mappings

• Default Mappings

• Mapping of Simple Types
• Mapping of Hyper and Decimal
• Mapping of String
• Mapping of Interfaces and Structures
• Mapping of Sequence
• Mapping of Type

• Conversion Mappings
• Client-Side Conversions
• Value Objects
• Exceptions and Errorcodes

• Automation Objects with UNO Interfaces
• DCOM
• The Bridge Services
• Unsupported COM Features

• CLI Language Binding

• The Language Binding DLLs
• Type Mapping

• Type Name Decoration
• Type Mappings
• Additional Structures

• Lifetime Management and Obtaining Interfaces
• Writing Client Programs

• The Override Problem
• Important Interfaces and Implementations

< Previous Page

Next Page >

The service manager was described above as the main factory that is passed to every new instantiated component. Often a component needs more functionality or information that must be exchangeable after deployment of an application. In this context, the service manager approach is limited.

Therefore, the concept of the component context was created. In future, it will be the central object in every UNO application. It is basically a read-only container offering named values. One of the named values is the service manager. The component context is passed to a component during its instantiation. This can be understood as an environment where components live (the relationship is similar to shell environment variables and an executable program).

ComponentContext and the ServiceManager

ComponentContext API

The component context only supports the com.sun.star.uno.XComponentContext interface.

  // module com::sun::star::uno
  interface XComponentContext : XInterface
  {
      any getValueByName( [in] string Name );
      com::sun::star::lang::XMultiComponentFactory getServiceManager();
  };

The getValueByName() method returns a named value. The getServiceManager() is a convenient way to retrieve the value named /singleton/com.sun.star.lang.theServiceManager. It returns the ServiceManager singleton, because most components need to access the service manager. The component context offers at least three kinds of named values:

Singletons (/singletons/...)

The singleton concept was introduced in Professional UNO - API Concepts - Data Types. In OpenOffice.org 1.0.2 there is only the ServiceManager singleton. From OpenOffice 1.x a singleton /singletons/com.sun.star.util.theMacroExpander has been added, which can be used to expand macros in configuration files. Other possible singletons can be found in the IDL reference.

Implementation properties (not yet defined)

These properties customize a certain implementation and are specified in the module description of each component. A module description is an xml-based description of a module (DLL or jar file) which contains the formal description of one or more components.

Service properties (not yet defined)

These properties can customize a certain service independent of the implementation and are specified in the IDL specification of a service. Note that service context properties are different from service properties. Service context properties are not subject to change and are the same for every instance of the service that shares the same component context. Service properties are different for each instance and can be changed at runtime through the XPropertySet interface.

Note, that in the scheme above, the ComponentContext has a reference to the service manager, but not conversely.

Besides the interfaces discussed above, the ServiceManager supports the com.sun.star.lang.XMultiComponentFactory interface.

  interface XMultiComponentFactory : com::sun::star::uno::XInterface
  { 
           com::sun::star::uno::XInterface createInstanceWithContext(
               [in] string aServiceSpecifier,
               [in] com::sun::star::uno::XComponentContext Context )
               raises (com::sun::star::uno::Exception);
 
           com::sun::star::uno::XInterface createInstanceWithArgumentsAndContext(
               [in] string ServiceSpecifier, 
               [in] sequence<any> Arguments,
               [in] com::sun::star::uno::XComponentContext Context )
               raises (com::sun::star::uno::Exception);
 
           sequence< string > getAvailableServiceNames();
  };

It replaces the XMultiServiceFactory interface. It has an additional XComponentContext parameter for the two object creation methods. This parameter enables the caller to define the component context that the new instance of the component receives. Most components use their initial component context to instantiate new components. This allows for context propagation.

Context propagation.

The illustration above shows the context propagation. A user might want a special component to get a customized context. Therefore, the user creates a new context by simply wrapping an existing one. The user overrides the desired values and delegates the properties that he is not interested into the original C1 context. The user defines which context Instance A and B receive. Instance A and B propagate their context to every new object that they create. Thus, the user has established two instance trees, the first tree completely uses the context Ctx C1, while the second tree uses Ctx C2.

Availability

The final API for the component context is available in StarOffice 6.0 and OpenOffice 1.0. Use this API instead of the API explained in the service manager section. Currently the component context does not have a persistent storage, so named values can not be added to the context of a deployed Apache OpenOffice. Presently, there is no additional benefit from the new API until there is a future release.

Compatibility Issues and Migration Path

Compromise between service-manger-only and component context concept

As discussed previously, both concepts are currently used within the office. The ServiceManager supports the interfaces com.sun.star.lang.XMultiServiceFactory and com.sun.star.lang.XMultiComponentFactory. Calls to the XMultiServiceFactory interface are delegated to the XMultiComponentFactory interface. The service manager uses its own XComponentContext reference to fill the missing parameter. The component context of the ServiceManager can be retrieved through the XPropertySet interface as 'DefaultContext'.

  // Query for the XPropertySet interface.
  // Note xOfficeServiceManager is the object retrieved by the 
  // UNO URL resolver 
  XPropertySet xPropertySet = (XPropertySet)
           UnoRuntime.queryInterface(XPropertySet.class, xOfficeServiceManager);
 
  // Get the default context from the office server.
  Object oDefaultContext = xpropertysetMultiComponentFactory.getPropertyValue("DefaultContext");
 
  // Query for the interface XComponentContext.
  xComponentContext = (XComponentContext) UnoRuntime.queryInterface(
           XComponentContext.class, objectDefaultContext);

This solution allows the use of the same service manager instance, regardless if it uses the old or new style API. In the future, the whole Apache OpenOffice code will only use the new API. However, the old API will still remain to ensure compatibility.

The described compromise has a drawback. The service manager now knows the component context, that was not necessary in the original design. Thus, every component that uses the old API (plain createInstance()) breaks the context propagation (see Context propagation). Therefore, it is recommended to use the new API in every new piece of code that is written.

Content on this page is licensed under the Public Documentation License (PDL).