Importing a UNO Object

From Apache OpenOffice Wiki
Jump to: navigation, search



The most common use case of interprocess connections is to import a reference to a UNO object from an exporting server. For instance, most of the Java examples described in this manual retrieve a reference to the Apache OpenOffice ComponentContext. The correct way to do this is using the com.sun.star.bridge.UnoUrlResolver service. Its main interface com.sun.star.bridge.XUnoUrlResolver is defined in the following way:

  interface XUnoUrlResolver: com::sun::star::uno::XInterface
  {
      /** resolves an object on the UNO URL */
      com::sun::star::uno::XInterface resolve( [in] string sUnoUrl )  
          raises (com::sun::star::connection::NoConnectException,  
                  com::sun::star::connection::ConnectionSetupException,  
                  com::sun::star::lang::IllegalArgumentException); 
  };

The string passed to the resolve() method is called a UNO URL. It must have the following format:

A UNO URL scheme

An example URL could be uno:socket,host=localhost,port=2002;urp;StarOffice.ServiceManager. The parts of this URL are:

  1. The URL schema uno:. This identifies the URL as UNO URL and distinguishes it from others, such as http: or ftp: URLs.
  2. A string which characterizes the type of connection to be used to access the other process. Optionally, directly after this string, a comma separated list of name-value pairs can follow, where name and value are separated by a '='. The currently supported connection types are described in Opening a Connection. The connection type specifies the transport mechanism used to transfer a byte stream, for example, TCP/IP sockets or named pipes.
  3. A string which characterizes the type of protocol used to communicate over the established byte stream connection. The string can be followed by a comma separated list of name-value pairs, which can be used to customize the protocol to specific needs. The suggested protocol is urp (UNO Remote Protocol). Some useful parameters are explained below. Refer to the document named UNO-URL at www.openoffice.org/udk for the complete specification.
  4. A process must explicitly export a certain object by a distinct name. It is not possible to access an arbitrary UNO object (which would be possible with IOR in CORBA, for instance).

The following example demonstrates how to import an object using the UnoUrlResolver:

  XComponentContext xLocalContext =
      com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);
 
  // initial serviceManager
  XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
 
  // create a URL resolver
  Object urlResolver = xLocalServiceManager.createInstanceWithContext(
      "com.sun.star.bridge.UnoUrlResolver", xLocalContext);
 
  // query for the XUnoUrlResolver interface
  XUnoUrlResolver xUrlResolver =
      (XUnoUrlResolver) UnoRuntime.queryInterface(XUnoUrlResolver.class, urlResolver);
 
  // Import the object
  Object rInitialObject = xUrlResolver.resolve( 
      "uno:socket,host=localhost,port=2002;urp;StarOffice.ServiceManager");
 
  // XComponentContext
  if (null != rInitialObject) {
      System.out.println("initial object successfully retrieved");
  } else {
      System.out.println("given initial-object name unknown at server side");
  }

The usage of the UnoUrlResolver has certain disadvantages. You cannot:

  • be notified when the bridge terminates for whatever reasons
  • close the underlying interprocess connection
  • offer a local object as an initial object to the remote process

These issues are addressed by the underlying API, which is explained in Opening a Connection.

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