Difference between revisions of "Documentation/DevGuide/ProUNO/Component Context"
m (→ComponentContext API: typos) |
OOoWikiBot (Talk | contribs) m (FINAL VERSION FOR L10N) |
||
Line 6: | Line 6: | ||
|NextPage=Documentation/DevGuide/ProUNO/Using UNO Interfaces | |NextPage=Documentation/DevGuide/ProUNO/Using UNO Interfaces | ||
}} | }} | ||
− | + | {{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/{{SUBPAGENAME}}}} | |
{{DISPLAYTITLE:Component Context}} | {{DISPLAYTITLE:Component Context}} | ||
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. | 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. |
Revision as of 07:55, 13 May 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 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.
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
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.
Content on this page is licensed under the Public Documentation License (PDL). |