Difference between revisions of "Documentation/DevGuide/ProUNO/Component Context"
Line 17: | Line 17: | ||
The component context only supports the <idl>com.sun.star.uno.XComponentContext</idl> interface. | The component context only supports the <idl>com.sun.star.uno.XComponentContext</idl> interface. | ||
− | + | <syntaxhighlight lang="idl"> | |
// module com::sun::star::uno | // module com::sun::star::uno | ||
interface XComponentContext : XInterface | interface XComponentContext : XInterface | ||
Line 24: | Line 24: | ||
com::sun::star::lang::XMultiComponentFactory getServiceManager(); | com::sun::star::lang::XMultiComponentFactory getServiceManager(); | ||
}; | }; | ||
− | + | </syntaxhighlight> | |
The <code>getValueByName()</code> method returns a named value. The <code>getServiceManager()</code> is a convenient way to retrieve the value named <code>/singleton/com.sun.star.lang.theServiceManager</code>. It returns the <code>ServiceManager</code> singleton, because most components need to access the service manager. The component context offers at least three kinds of named values: | The <code>getValueByName()</code> method returns a named value. The <code>getServiceManager()</code> is a convenient way to retrieve the value named <code>/singleton/com.sun.star.lang.theServiceManager</code>. It returns the <code>ServiceManager</code> singleton, because most components need to access the service manager. The component context offers at least three kinds of named values: | ||
''Singletons (/singletons/...)'' | ''Singletons (/singletons/...)'' | ||
− | :The singleton concept was introduced in [[Documentation/DevGuide/ProUNO/Singletons|Professional UNO - API Concepts - Data Types]]. In | + | :The singleton concept was introduced in [[Documentation/DevGuide/ProUNO/Singletons|Professional UNO - API Concepts - Data Types]]. In OpenOffice.org 1.0.2 there is only the <code>ServiceManager</code> singleton. From OpenOffice 1.x a singleton <code>/singletons/com.sun.star.util.theMacroExpander</code> 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)'' | ''Implementation properties (not yet defined)'' | ||
Line 34: | Line 34: | ||
''Service properties (not yet defined)'' | ''Service properties (not yet defined)'' | ||
− | :These properties can customize a certain service independent | + | :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 <code>XPropertySet</code> interface. |
Note, that in the scheme above, the <code>ComponentContext</code> has a reference to the service manager, but not conversely. | Note, that in the scheme above, the <code>ComponentContext</code> has a reference to the service manager, but not conversely. | ||
Besides the interfaces discussed above, the <code>ServiceManager</code> supports the <idl>com.sun.star.lang.XMultiComponentFactory</idl> interface. | Besides the interfaces discussed above, the <code>ServiceManager</code> supports the <idl>com.sun.star.lang.XMultiComponentFactory</idl> interface. | ||
− | + | <syntaxhighlight lang="idl"> | |
interface XMultiComponentFactory : com::sun::star::uno::XInterface | interface XMultiComponentFactory : com::sun::star::uno::XInterface | ||
{ | { | ||
Line 55: | Line 55: | ||
sequence< string > getAvailableServiceNames(); | sequence< string > getAvailableServiceNames(); | ||
}; | }; | ||
− | + | </syntaxhighlight> | |
It replaces the <code>XMultiServiceFactory</code> interface. It has an additional <code>XComponentContext</code> 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''. | It replaces the <code>XMultiServiceFactory</code> interface. It has an additional <code>XComponentContext</code> 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''. | ||
Line 64: | Line 64: | ||
===Availability=== | ===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 {{ | + | 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 {{AOo}}. Presently, there is no additional benefit from the new API until there is a future release. |
===Compatibility Issues and Migration Path=== | ===Compatibility Issues and Migration Path=== | ||
Line 71: | Line 71: | ||
As discussed previously, both concepts are currently used within the office. The ServiceManager supports the interfaces <idl>com.sun.star.lang.XMultiServiceFactory</idl> and <idl>com.sun.star.lang.XMultiComponentFactory</idl>. Calls to the <code>XMultiServiceFactory</code> interface are delegated to the <code>XMultiComponentFactory</code> interface. The service manager uses its own <code>XComponentContext</code> reference to fill the missing parameter. The component context of the <code>ServiceManager</code> can be retrieved through the <code>XPropertySet</code> interface as 'DefaultContext'. | As discussed previously, both concepts are currently used within the office. The ServiceManager supports the interfaces <idl>com.sun.star.lang.XMultiServiceFactory</idl> and <idl>com.sun.star.lang.XMultiComponentFactory</idl>. Calls to the <code>XMultiServiceFactory</code> interface are delegated to the <code>XMultiComponentFactory</code> interface. The service manager uses its own <code>XComponentContext</code> reference to fill the missing parameter. The component context of the <code>ServiceManager</code> can be retrieved through the <code>XPropertySet</code> interface as 'DefaultContext'. | ||
− | + | <syntaxhighlight lang="java"> | |
// Query for the XPropertySet interface. | // Query for the XPropertySet interface. | ||
// Note xOfficeServiceManager is the object retrieved by the | // Note xOfficeServiceManager is the object retrieved by the | ||
Line 84: | Line 84: | ||
xComponentContext = (XComponentContext) UnoRuntime.queryInterface( | xComponentContext = (XComponentContext) UnoRuntime.queryInterface( | ||
XComponentContext.class, objectDefaultContext); | XComponentContext.class, objectDefaultContext); | ||
− | + | </syntaxhighlight> | |
− | 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 {{ | + | 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 {{AOo}} code will only use the new API. However, the old API will still remain to ensure compatibility. |
{{Note|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 <tt>createInstance()</tt>) breaks the context propagation (see [[:Image:UseServices3.png|Context propagation]]). Therefore, it is recommended to use the new API in every new piece of code that is written.}} | {{Note|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 <tt>createInstance()</tt>) breaks the context propagation (see [[:Image:UseServices3.png|Context propagation]]). Therefore, it is recommended to use the new API in every new piece of code that is written.}} |
Latest revision as of 12:05, 23 December 2020
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 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.
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
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). |