Difference between revisions of "Documentation/DevGuide/WritingUNO/Core Interfaces to Implement"

Revision as of 08:48, 13 May 2009

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.

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.

com.sun.star.uno.XInterface

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.

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

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();

com.sun.star.uno.XWeak

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

com.sun.star.lang.XComponent

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() 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);

com.sun.star.lang.XMain

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);

com.sun.star.uno.XAggregation

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);

com.sun.star.lang.XUnoTunnel

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.