Core Interfaces to Implement

From Apache OpenOffice Wiki
Jump to: navigation, search

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

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 through UnoRuntime.queryInterface() or Reference<destInterface>(sourceInterface, UNO_QUERY). The counterpart release() 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.

This interface is used by scripting languages such as Apache OpenOffice Basic to get type information. Apache OpenOffice Basic cannot use the component without it.
  // com::sun::star::lang::XTypeProvider
  sequence<type> getTypes(); 
  sequence<byte> getImplementationId();
It is possible that XTypeProvider and XServiceInfo (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.

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::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

This interface is used to allow other objects to use createInstanceWithArguments() or createInstanceWithArgumentsAndContext() with the component. It should be implemented and the arguments processed in initialize():
  // 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 Apache OpenOffice service manager.
  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.
  void setDelegator( 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).
Personal tools
In other languages