Using UNO Interfaces

OpenOffice.org Developer's Guide

Professional UNO

< Previous Section

Next Section >

• Introduction
• API Concepts

• Data Types

• Simple Types
• The Any Type
• Interfaces
• Services
• Structs
• Predefined Values
• Sequences
• Modules
• Exceptions
• Singletons

• Understanding the API Reference

• UNO Concepts

• UNO Interprocess Connections

• Starting OpenOffice.org in Listening Mode
• Importing a UNO Object
• Characteristics of the Interprocess Bridge
• Opening a Connection
• Creating the Bridge
• Closing a Connection
• Example: A Connection Aware Client

• Service Manager and Component Context

• Service Manager
• Component Context

• Using UNO Interfaces
• Properties
• Collections and Containers
• Event Model
• Exception Handling
• Lifetime of UNO objects

• acquire() and release()
• The XComponent Interface
• Children of the XEventListener Interface
• Weak Objects and References
• Differences Between the Lifetime of C++ and Java Objects

• Object Identity

• UNO Language Bindings

• Java Language Binding

• Getting a Service Manager
• Transparent Use of Office UNO Components
• Handling Interfaces
• Type Mappings

• Mapping of Sequence Types
• Mapping of Enum Types
• Mapping of Struct Types
• Mapping of Exception Types
• Mapping of Interface Types
• Mapping of UNOIDL
• Mapping of Services
• Mapping of Singletons
• Inexact approximation of UNO Value Semantics

• C++ Language Binding

• Establishing Interprocess Connections
• Transparent Use of Office UNO Components
• Type Mappings

• Mapping of Struct Types
• Mapping of Interface Types
• Mapping of Sequence Types
• Mapping of Services
• Mapping of Singletons

• Using Weak References
• Exception Handling in C++

• OpenOffice.org Basic

• Handling UNO Objects

• Instantiating UNO Services
• Getting Information about UNO Objects

• Mapping of UNO and Basic Types

• Mapping of Simple Types
• Mapping of Sequences and Arrays
• Mapping of Structs
• Mapping of Enums and Constant Groups

• Case Sensitivity
• Exception Handling
• Listeners

• Automation Bridge

• The Service Manager Component
• Using UNO from Automation

• Calling Functions and Accessing Properties
• Return Values
• Usage of Types

• Using Automation Objects from UNO
• Type Mappings

• Default Mappings

• Mapping of Simple Types
• Mapping of Hyper and Decimal
• Mapping of String
• Mapping of Interfaces and Structures
• Mapping of Sequence
• Mapping of Type

• Conversion Mappings
• Client-Side Conversions
• Value Objects
• Exceptions and Errorcodes

• Automation Objects with UNO Interfaces
• DCOM
• The Bridge Services
• Unsupported COM Features

• CLI Language Binding

• The Language Binding DLLs
• Type Mapping

• Type Name Decoration
• Type Mappings
• Additional Structures

• Lifetime Management and Obtaining Interfaces
• Writing Client Programs

• The Override Problem
• Important Interfaces and Implementations

< Previous Page

Next Page >

Every UNO object must inherit from the interface com.sun.star.uno.XInterface. Before using an object, know how to use it and how long it will function. By prescribing XInterface to be the base interface for each and every UNO interface, UNO lays the groundwork for object communication. For historic reasons, the UNOIDL description of XInterface lists the functionality that is associated with XInterface in the C++ (or binary UNO) language binding; other language bindings offer similar functionality by different mechanisms:

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

The methods acquire() and release() handle the lifetime of the UNO object by reference counting. Detailed information about Reference counting is discussed in Lifetime of UNO objects. All current language bindings take care of acquire() and release() internally whenever there is a reference to a UNO object.

The queryInterface() method obtains other interfaces exported by the object. The caller asks the implementation of the object if it supports the interface specified by the type argument. The type parameter must denote a UNO interface type. The call may return with an interface reference of the requested type or with a void any. In C++ or Java simply test if the result is not equal null.

Unknowingly, we encountered XInterface when the service manager was asked to create a service instance:

  XComponentContext xLocalContext =
      com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);
  
  // initial serviceManager
  XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
  
  // create a urlresolver
  Object urlResolver = xLocalServiceManager.createInstanceWithContext(
      "com.sun.star.bridge.UnoUrlResolver", xLocalContext);

The IDL specification of XMultiComponentFactory shows:

  // module com::sun::star::lang
  interface XMultiComponentFactory : com::sun::star::uno::XInterface
  { 
      com::sun::star::uno::XInterface createInstanceWithContext(
              [in] string aServiceSpecifier,
              [in] com::sun::star::uno::XComponentContext Context )
          raises (com::sun::star::uno::Exception);
          ...
  }

The above code shows that createInstanceWithContext() provides an instance of the given service, but it only returns a com.sun.star.uno.XInterface. This is mapped to java.lang.Object by the Java UNO binding afterwards.

In order to access a service, you need to know which interfaces the service exports. This information is available in the IDL reference. For instance, for the com.sun.star.bridge.UnoUrlResolver service, you learn:

  // module com::sun::star::bridge
  service UnoUrlResolver: XUnoUrlResolver;

This means the service you ordered at the service manager must support com.sun.star.bridge.XUnoUrlResolver. Next query the returned object for this interface:

  // query urlResolver for its com.sun.star.bridge.XUnoUrlResolver interface
  XUnoUrlResolver xUrlResolver = (XUnoUrlResolver) 
      UnoRuntime.queryInterface(UnoUrlResolver.class, urlResolver);
  
  // test if the interface was available
  if (null == xUrlResolver) {
      throw new java.lang.Exception(
          "Error: UrlResolver service does not export XUnoUrlResolver interface");
  }
  // use the interface
  Object remoteObject = xUrlResolver.resolve(
      "uno:socket,host=0,port=2002;urp;StarOffice.ServiceManager");

For a new-style service like com.sun.star.bridge.UnoUrlResolver, there is a superior way to obtain an instance of it, see Mapping of Services for Java and Mapping of Services for C++.

The object decides whether or not it returns the interface. You have encountered a bug if the object does not return an interface that is specified to be mandatory in a service. When the interface reference is retrieved, invoke a call on the reference according to the interface specification. You can follow this strategy with every service you instantiate at a service manager, leading to success.

With this method, you may not only get UNO objects through the service manager, but also by normal interface calls:

  // Module com::sun::star::text
  interface XTextRange: com::sun::star::uno::XInterface
  { 
      XText getText(); 
      XTextRange getStart(); 
      ....
  };

The returned interface types are specified in the operations, so that calls can be invoked directly on the returned interface. Often, an object implementing multiple interfaces are returned, instead of an object implementing one certain interface.

You can then query the returned object for the other interfaces specified in the given old-style service, here com.sun.star.drawing.Text.

UNO has a number of generic interfaces. For example, the interface com.sun.star.frame.XComponentLoader:

  // module com::sun::star::frame
  interface XComponentLoader: com::sun::star::uno::XInterface
  {
      com::sun::star::lang::XComponent loadComponentFromURL( [in] string aURL,
              [in] string aTargetFrameName,
              [in] long nSearchFlags,
              [in] sequence<com::sun::star::beans::PropertyValue> aArgs )
          raises( com::sun::star::io::IOException,
                  com::sun::star::lang::IllegalArgumentException );
  };

It becomes difficult to find which interfaces are supported beside XComponent, because the kind of returned document (text, calc, draw, etc.) depends on the incoming URL.

These dependencies are described in the appropriate chapters of this manual.

Tools such as the InstanceInspector component is a quick method to find out which interfaces a certain object supports. The InstanceInspector component comes with the Apache OpenOffice SDK that allows the inspection of a certain objects at runtime. Do not rely on implementation details of certain objects. If an object supports more interfaces than specified in the service description, query the interface and perform calls. The code may only work for this distinct office version and not work with an update of the office!

Unfortunately, there may still be bugs in the service specifications. Please provide feedback about missing interfaces to Apache OpenOffice to ensure that the specification is fixed and that you can rely on the support of this interface.

There are certain specifications a queryInterface() implementation must not violate:

• If queryInterface() on a specific object returned a valid interface reference for a given type, it must return a valid reference for any successive queryInterface() calls on this object for the same type.
• If queryInterface() on a specific object returned a null reference for a given type, it must always return a null reference for the same type.
• If queryInterface() on reference A returns reference B, queryInterface() on B for Type A must return interface reference A or calls made on the returned reference must be equivalent to calls made on reference A.
• If queryInterface() on a reference A returns reference B, queryInterface() on A and B for XInterface must return the same interface reference (object identity).

These specifications must not be violated because a UNO runtime environment may choose to cache queryInterface() calls. The rules are basically identical to the rules of QueryInterface in MS COM.

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