Core Interfaces to Implement
- Component Architecture
- Core Interfaces to Implement
It is important to know where the interfaces to implement are located. The interfaces here are located at the object implementations in the component. When writing UNO components, the desired methods have to be implemented into the application and also, the core interfaces used to enable communication with the UNO environment. Some of them are mandatory, but there are others to choose from.
Interface | Required | Should be implemented | Optional | Special Cases | Helper class available for C++ and Java |
---|---|---|---|---|---|
XInterface | |||||
XTypeProvider | |||||
XServiceInfo | |||||
XWeak | |||||
XComponent | |||||
XInitialization | |||||
XMain | |||||
XAggregation | |||||
XUnoTunnel |
The interfaces listed in the table above have been characterized here briefly. More descriptions of each interface are provided later, as well as if helpers are available and which conditions apply.
- The component will not work without it. The base interface
XInterface
gives access to higher interfaces of the service and allows other objects to tell the service when it is no longer needed, so that it can destroy itself.
// com::sun::star::uno::XInterface any queryInterface( [in] type aType ); [oneway] void acquire(); // increase reference counter in your service implementation [oneway] void release(); // decrease reference counter, delete object when counter becomes zero
- Usually developers do not call
acquire()
explicitly, because it is called automatically by the language bindings when a reference to a component is retrieved throughUnoRuntime.queryInterface()
orReference<destInterface>(sourceInterface, UNO_QUERY)
. The counterpartrelease()
is called automatically when the reference goes out of scope in C++ or when the Java garbage collector throws away the object holding the reference.
com.sun.star.lang.XTypeProvider
- This interface is used by scripting languages such as OpenOffice.org Basic to get type information. OpenOffice.org Basic cannot use the component without it.
// com::sun::star::lang::XTypeProvider sequence<type> getTypes(); sequence<byte> getImplementationId();
- It is possible that
XTypeProvider
andXServiceInfo
(below) will be deprecated in the future, and that alternative, language-binding-specific mechanisms will be made available to query an object for its characteristics.
com.sun.star.lang.XServiceInfo
- This interface is used by other objects to get information about the service implementation.
// com::sun::star::lang::XServiceInfo string getImplementationName(); boolean supportsService( [in] string ServiceName ); sequence<string> getSupportedServiceNames();
- This interface allows clients to keep a weak reference to the object. A weak reference does not prevent the object from being destroyed if another client keeps a hard reference to it, therefore it allows a hard reference to be retrieved again. The technique is used to avoid cyclic references. Even if the interface is not required by you, it could be implemented for a client that may want to establish a weak reference to an instance of your object.
// com.sun.star.uno.XWeak com::sun::star::uno::XAdapter queryAdapter(); // creates Adapter
- This interface is used if cyclic references can occur in the component holding another object and the other object is holding a reference to that component. It can be specified in the service description who shall destroy the object.
// com::sun::star::lang::XComponent void dispose(); //an object owning your component may order it to delete itself using dispose() void addEventListener(com::sun::star::lang::XEventListener xListener); // add dispose listeners void removeEventListener (com::sun::star::lang::XEventListener aListener); // remove them
com.sun.star.lang.XInitialization
- This interface is used to allow other objects to use
createInstanceWithArguments()
orcreateInstanceWithArgumentsAndContext()
with the component. It should be implemented and the arguments processed ininitialize()
:
// com::sun::star::lang::XInitialization void initialize(sequence< any > aArguments) raises (com::sun::star::uno::Exception);
- This interface is for use with the uno executable to instantiate the component independently from the OpenOffice.org service manager.
// com.sun.star.lang.XMain long run (sequence< string > aArguments);
- This interfaces makes the implementation cooperate in an aggregation. If implemented, other objects can aggregate to the implementation. Aggregated objects behave as if they were one. If another object aggregates the component, it holds the component and delegates calls to it, so that the component seems to be one with the aggregating object.
// com.sun.star.uno.XAggregation void setDelegator(com.sun.star.uno.XInterface pDelegator); any queryAggregation(type aType);
- This interface provides a pointer to the component to another component in the same process. This can be achieved with
XUnoTunnel
.XUnoTunnel
should not be used by new components, because it is to be used for integration of existing implementations, if all else fails.
By now you should be able to decide which interfaces are interesting in your case. Sometimes the decision for or against an interface depends on the necessary effort as well. The following section discusses for each of the above interfaces how you can take advantage of pre-implemented helper classes in Java or C++, and what must happen in a possible implementation, no matter which language is used.
Content on this page is licensed under the Public Documentation License (PDL). |