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

From Apache OpenOffice Wiki
Jump to: navigation, search
m (1 revision(s))
m (FINAL VERSION FOR L10N)
(6 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
|NextPage=Documentation/DevGuide/WritingUNO/XInterface
 
|NextPage=Documentation/DevGuide/WritingUNO/XInterface
 
}}
 
}}
 +
{{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:Core Interfaces to Implement}}
 
{{DISPLAYTITLE:Core Interfaces to Implement}}
 
<!--<idltopic>com.sun.star.uno.XInterface;com.sun.star.lang.XTypeProvider;com.sun.star.lang.XServiceInfo;com.sun.star.uno.XWeak;com.sun.star.lang.XComponent;com.sun.star.lang.XInitialization;com.sun.star.lang.XMain;com.sun.star.uno.XAggregation;com.sun.star.lang.XUnoTunnel</idltopic>-->
 
<!--<idltopic>com.sun.star.uno.XInterface;com.sun.star.lang.XTypeProvider;com.sun.star.lang.XServiceInfo;com.sun.star.uno.XWeak;com.sun.star.lang.XComponent;com.sun.star.lang.XInitialization;com.sun.star.lang.XMain;com.sun.star.uno.XAggregation;com.sun.star.lang.XUnoTunnel</idltopic>-->
Line 87: Line 88:
  
 
:The component will not work without it. The base interface <code>XInterface</code> 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.  
 
:The component will not work without it. The base interface <code>XInterface</code> 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.  
 
+
<source lang="idl">
 
   // com::sun::star::uno::XInterface
 
   // com::sun::star::uno::XInterface
 
    
 
    
Line 94: Line 95:
 
   [oneway] void release(); // decrease reference counter, delete object when counter becomes zero
 
   [oneway] void release(); // decrease reference counter, delete object when counter becomes zero
  
 
+
</source>
 
:Usually developers do not call <code>acquire()</code> explicitly, because it is called automatically by the language bindings when a reference to a component is retrieved through <code>UnoRuntime.queryInterface()</code> or <code>Reference<destInterface>(sourceInterface, UNO_QUERY)</code>. The counterpart <code>release()</code> 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.
 
:Usually developers do not call <code>acquire()</code> explicitly, because it is called automatically by the language bindings when a reference to a component is retrieved through <code>UnoRuntime.queryInterface()</code> or <code>Reference<destInterface>(sourceInterface, UNO_QUERY)</code>. The counterpart <code>release()</code> 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.
  
Line 100: Line 101:
  
 
:This interface is used by scripting languages such as {{PRODUCTNAME}} Basic to get type information. {{PRODUCTNAME}} Basic cannot use the component without it.
 
:This interface is used by scripting languages such as {{PRODUCTNAME}} Basic to get type information. {{PRODUCTNAME}} Basic cannot use the component without it.
 
+
<source lang="idl">
 
   // com::sun::star::lang::XTypeProvider
 
   // com::sun::star::lang::XTypeProvider
 
      
 
      
Line 106: Line 107:
 
   sequence<byte> getImplementationId();  
 
   sequence<byte> getImplementationId();  
  
 
+
</source>
 
:It is possible that <code>XTypeProvider</code> and <code>XServiceInfo</code> (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.
 
:It is possible that <code>XTypeProvider</code> and <code>XServiceInfo</code> (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.
  
Line 112: Line 113:
  
 
:This interface is used by other objects to get information about the service implementation.
 
:This interface is used by other objects to get information about the service implementation.
 
+
<source lang="idl">
 
   // com::sun::star::lang::XServiceInfo
 
   // com::sun::star::lang::XServiceInfo
 
    
 
    
Line 118: Line 119:
 
   boolean supportsService( [in] string ServiceName );  
 
   boolean supportsService( [in] string ServiceName );  
 
   sequence<string> getSupportedServiceNames();  
 
   sequence<string> getSupportedServiceNames();  
 
+
</source>
 
<idl>com.sun.star.uno.XWeak</idl>  
 
<idl>com.sun.star.uno.XWeak</idl>  
  
 
: 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.
 
: 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.
 
+
<source lang="idl">
 
   // com.sun.star.uno.XWeak
 
   // com.sun.star.uno.XWeak
 
    
 
    
 
   com::sun::star::uno::XAdapter queryAdapter(); // creates Adapter  
 
   com::sun::star::uno::XAdapter queryAdapter(); // creates Adapter  
 
+
</source>
 
<idl>com.sun.star.lang.XComponent</idl>  
 
<idl>com.sun.star.lang.XComponent</idl>  
  
 
: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.  
 
: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.  
 
+
<source lang="idl">
 
   // com::sun::star::lang::XComponent
 
   // com::sun::star::lang::XComponent
 
    
 
    
Line 136: Line 137:
 
   void addEventListener(com::sun::star::lang::XEventListener xListener); // add dispose listeners
 
   void addEventListener(com::sun::star::lang::XEventListener xListener); // add dispose listeners
 
   void removeEventListener (com::sun::star::lang::XEventListener aListener); // remove them
 
   void removeEventListener (com::sun::star::lang::XEventListener aListener); // remove them
 
+
</source>
 
<idl>com.sun.star.lang.XInitialization</idl>  
 
<idl>com.sun.star.lang.XInitialization</idl>  
  
 
:This interface is used to allow other objects to use <code>createInstanceWithArguments()</code> or <code>createInstanceWithArgumentsAndContext()</code> with the component. It should be implemented and the arguments processed in <code>initialize()</code>:
 
:This interface is used to allow other objects to use <code>createInstanceWithArguments()</code> or <code>createInstanceWithArgumentsAndContext()</code> with the component. It should be implemented and the arguments processed in <code>initialize()</code>:
 
+
<source lang="idl">
 
   // com::sun::star::lang::XInitialization
 
   // com::sun::star::lang::XInitialization
 
    
 
    
 
   void initialize(sequence< any > aArguments) raises (com::sun::star::uno::Exception);  
 
   void initialize(sequence< any > aArguments) raises (com::sun::star::uno::Exception);  
 
+
</source>
 
<idl>com.sun.star.lang.XMain</idl>  
 
<idl>com.sun.star.lang.XMain</idl>  
  
 
:This interface is for use with the uno executable to instantiate the component independently from the {{PRODUCTNAME}} service manager.
 
:This interface is for use with the uno executable to instantiate the component independently from the {{PRODUCTNAME}} service manager.
 
+
<source lang="idl">
 
   // com.sun.star.lang.XMain
 
   // com.sun.star.lang.XMain
 
    
 
    
 
   long run (sequence< string > aArguments);  
 
   long run (sequence< string > aArguments);  
 
+
</source>
 
<idl>com.sun.star.uno.XAggregation</idl>  
 
<idl>com.sun.star.uno.XAggregation</idl>  
  
 
: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.
 
: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.
 
+
<source lang="idl">
 
   // com.sun.star.uno.XAggregation
 
   // com.sun.star.uno.XAggregation
 
    
 
    
 
   void setDelegator(com.sun.star.uno.XInterface pDelegator);
 
   void setDelegator(com.sun.star.uno.XInterface pDelegator);
 
   any queryAggregation(type aType);
 
   any queryAggregation(type aType);
 
+
</source>
 
<idl>com.sun.star.lang.XUnoTunnel</idl>  
 
<idl>com.sun.star.lang.XUnoTunnel</idl>  
  
Line 169: Line 170:
  
 
{{PDL1}}
 
{{PDL1}}
[[Category: Writing UNO Components]]
+
 
 +
[[Category:Documentation/Developer's Guide/Writing UNO Components]]

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.

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.

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.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages