XInterface

OpenOffice.org Developer's Guide

Writing UNO Components

< Previous Section

Next Section >

• Required Files
• Using UNOIDL to Specify New Components

• Writing the Specification

• Preprocessing
• Grouping Definitions in Modules
• Simple Types
• Defining an Interface
• Defining a Service
• Defining a Sequence
• Defining a Struct
• Defining an Exception
• Predefining Values
• Using Comments
• Singleton
• Reserved Types
• Published Entities

• Generating Source Code from UNOIDL Definitions

• Component Architecture
• Core Interfaces to Implement

• XInterface
• XTypeProvider
• XServiceInfo
• XWeak
• XComponent
• XInitialization
• XMain
• XAggregation
• XUnoTunnel

• Simple Component in Java

• Class Definition with Helper Class
• Implementing Your Own Interfaces
• Providing a Single Factory Using a Helper Method
• Write Registration Info Using a Helper Method
• Implementing without Helpers
• Storing the Service Manager for Further Use
• Create Instance with Arguments
• Possible Structures for Java Components
• Running and Debugging Java Components

• Register Component File
• Make Registration Available to OpenOffice.org
• Test the Registration
• Debugging
• The Java Environment in OpenOffice.org
• Troubleshooting

• C++ Component

• Class Definition with Helper Template Classes
• Implementing your own Interfaces
• Providing a Single Factory Using a Helper Method
• Write Registration Info Using a Helper Method
• Provide Implementation Environment
• Implementing without Helpers
• Storing the Service Manager for Further Use
• Create Instance with Arguments
• Multiple Components in One Dynamic Link Library
• Building and Testing C++ Components

• Integrating Components into OpenOffice.org

• Protocol Handler

• Implementation
• Configuration
• Installation

• Jobs

• Execution Environment
• Implementation
• Initialization
• Returning Results
• Configuration
• Installation
• Using the vnd.sun.star.jobs: URL Schema
• List of Supported Events

• Add-Ons

• Guidelines
• Configuration

• Menus
• Toolbars
• Images for Toolbars and Menus
• Help Integration

• Installation

• Disable Commands
• Intercepting Context Menus

• File Naming Conventions
• Deployment Options for Components

• Command Line Registry Tools
• Manual Component Installation
• Bootstrapping a Service Manager
• Special Service Manager Configurations

• The UNO Executable

• Standalone Use Case
• Server Use Case
• Using the UNO Executable

• Accessing Dialogs

• Assigning Component Methods to Control Events
• Using Dialogs in Components

< Previous Page

Next Page >

All service implementations must implement com.sun.star.uno.XInterface. If a Java component is derived from a Java helper class that comes with the SDK, it supports XInterface automatically. Otherwise, it is sufficient to add XInterface or any other UNO interface to the implements list. The Java UNO runtime takes care of XInterface. In C++, there are helper classes to inherit that already implement XInterface. However, if XInterface is to be implemented manually, consider the code below.

The IDL specification for com.sun.star.uno.XInterface looks like this:

  // module com::sun::star::uno
  interface XInterface
  {
      any queryInterface( [in] type aType ); 
      [oneway] void acquire(); 
      [oneway] void release(); 
  };

Requirements for queryInterface()

When queryInterface() is called, the caller asks the implementation if it supports the interface specified by the type argument. The UNOIDL base type stores the name of a type and its com.sun.star.uno.TypeClass. The call must return an interface reference of the requested type if it is available or a void any if it is not. There are certain conditions a queryInterface() implementation must meet:

Constant Behaviour

If queryInterface() on a specific object has once returned a valid interface reference for a given type, it must always return a valid reference for any subsequent queryInterface() call for the same type on this object. A query for XInterface must always return the same reference.

If queryInterface() on a specific object has once returned a void any for a given type, it must always return a void any for the same type.

Symmetry

If queryInterface() for XBar on a reference xFoo returns a reference xBar, then queryInterface() on reference xBar for type XFoo must return xFoo or calls made on the returned reference must be equivalent to calls to xFoo.

Object Identity

In C++, two objects are the same if their XInterface are the same. The queryInterface() for XInterface will have to be called on both. In Java, check for the identity by calling the runtime function com.sun.star.uni.UnoRuntime.areSame().

The reason for this specifications is that a UNO runtime environment may choose to cache queryInterface() calls. The rules are identical to the rules of the function QueryInterface() in MS COM.

If you want to implement queryInterface() in Java, for example, you want to export less interfaces than you implement, your class must implement the Java interface com.sun.star.uno.IQueryInterface.

Reference Counting

The methods acquire() and release() handle the lifetime of the UNO object. This is discussed in detail in chapter Lifetime of UNO objects. Acquire and release must be implemented in a thread-safe fashion. This is demonstrated in C++ in the section about C++ components below.

Content on this page is licensed under the Public Documentation License (PDL).