Creating the Bridge

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 >

The interaction of services that are needed to initiate a UNO interprocess bridge. The interfaces have been simplified.

The XConnection instance can now be used to establish a UNO interprocess bridge on top of the connection, regardless if the connection was established with a Connector or Acceptor service (or another method). To do this, you must instantiate the service com.sun.star.bridge.BridgeFactory. It supports the com.sun.star.bridge.XBridgeFactory interface.

  interface XBridgeFactory: com::sun::star::uno::XInterface
  { 
      XBridge createBridge( 
              [in] string sName, 
              [in] string sProtocol , 
              [in] com::sun::star::connection::XConnection aConnection , 
              [in] XInstanceProvider anInstanceProvider ) 
          raises ( BridgeExistsException , com::sun::star::lang::IllegalArgumentException ); 
      XBridge getBridge( [in] string sName ); 
      sequence < XBridge > getExistingBridges( ); 
  };

The BridgeFactory service administrates all UNO interprocess connections. The createBridge() method creates a new bridge:

• You can give the bridge a distinct name with the sName argument. Later the bridge can be retrieved by using the getBridge() method with this name. This allows two independent code pieces to share the same interprocess bridge. If you call createBridge() with the name of an already working interprocess bridge, a BridgeExistsException is thrown. When you pass an empty string, you always create a new anonymous bridge, which can never be retrieved by getBridge() and which never throws a BridgeExistsException.

• The second parameter specifies the protocol to be used on the connection. Currently, only the 'urp' protocol is supported. In the UNO URL, this string is separated by two ';'. The urp string may be followed by a comma separated list of name-value pairs describing properties for the bridge protocol. The urp specification can be found on the wiki Uno Remote Protocol.

• The third parameter is the XConnection interface as it was retrieved by Connector/Acceptor service.

• The fourth parameter is a UNO object, which supports the com.sun.star.bridge.XInstanceProvider interface. This parameter may be a null reference if you do not want to export a local object to the remote process.

  interface XInstanceProvider: com::sun::star::uno::XInterface
  { 
      com::sun::star::uno::XInterface getInstance( [in] string sInstanceName ) 
           raises ( com::sun::star::container::NoSuchElementException ); 
  }; 
  </source>
The <code>BridgeFactory</code> returns a <idl>com.sun.star.bridge.XBridge</idl> interface.
  <source lang="idl">
  interface XBridge: com::sun::star::uno::XInterface
  { 
      XInterface getInstance( [in] string sInstanceName ); 
      string getName(); 
      string getDescription(); 
  };

The XBridge.getInstance() method retrieves an initial object from the remote counterpart. The local XBridge.getInstance() call arrives in the remote process as an XInstanceProvider.getInstance() call. The object returned can be controlled by the string sInstanceName. It completely depends on the implementation of XInstanceProvider, which object it returns.

The XBridge interface can be queried for a com.sun.star.lang.XComponent interface, that adds a com.sun.star.lang.XEventListener to the bridge. This listener will be terminated when the underlying connection closes (see above). You can also call dispose() on the XComponent interface explicitly, which closes the underlying connection and initiates the bridge shutdown procedure.

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