Difference between revisions of "Documentation/DevGuide/ProUNO/Component Context"

From Apache OpenOffice Wiki
Jump to: navigation, search
m
m (ComponentContext API: typos)
Line 60: Line 60:
 
[[Image:UseServices3.png|none|thumb|400px|Context propagation.]]
 
[[Image:UseServices3.png|none|thumb|400px|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 y 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.
+
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===
 
===Availability===

Revision as of 10:35, 17 February 2009

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.org 1.1, 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 from 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 OpenOffice.org. 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 future, the whole OpenOffice.org code will only use the new API. However, the old API will still remain to ensure compatibility.

Template:Documentation/Note

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages