Handling Interfaces

From Apache OpenOffice Wiki
Jump to: navigation, search



The service manager is created in the server process and the Java UNO remote bridge ensures that its XInterface is transported back to the client. A Java proxy object is constructed that can be used by the client code. This object is called the initial object, because it is the first object created by the bridge. When another object is obtained through this object, then the bridge creates a new proxy. For instance, if a function is called that returns an interface. That is, the original object is actually running in the server process (the office) and calls to the proxy are forwarded by the bridge. Not only interfaces are converted, but function arguments, return values and exceptions.

The Java bridge maps objects on a per-interface basis, that is, in the first step only the interface is converted that is returned by a function described in the API reference. For example, if you have the service manager and use it to create another component, you initially get a com.sun.star.uno.XInterface:

  XInterface xint= (XInterface)
  serviceManager.createInstance("com.sun.star.bridge.oleautomation.Factory");

You know from the service description that Factory implements a com.sun.star.lang.XMultiServiceFactory interface. However, you cannot cast the object or call the interface function on the object, since the object is only a proxy for just one interface, XInterface. Therefore, you have to use a mechanism that is provided with the Java bridge that generates proxy objects on demand. For example:

  XMultiServiceFactory xfac = (XMultiServiceFactory) UnoRuntime.queryInterface(
      XMultiServiceFactory.class, xint);

If xint is a proxy, then queryInterface() hands out another proxy for XMultiServiceFactory provided that the original object implements it.

Documentation note.png Starting with OpenOffice.org 3.2, you can leave out the cast to XMultiServiceFactory in the example above; through the use of generics (introduced in Java 5), the Java compiler will figure this out itself.

Interface proxies can be used as arguments in function calls on other proxy objects. For example:

  // client side
  // obj is a proxy interface and returns another interface through its func() method
  XSomething ret = obj.func();
 
  // anotherObject is a proxy interface, too. Its method func(XSomething arg)
  // takes the interface ret obtained from obj
  anotherObject.func(ret);

In the server process, the obj object would receive the original ret object as a function argument.

It is also possible to have Java components on the client side. As well, they can be used as function arguments, then the bridge would set up proxies for them in the server process.

Not all language concepts of UNO have a corresponding language element in Java. For example, there are no structs and all-purpose out parameters. Refer to Type Mappings for how those concepts are mapped.

Interface handling normally involves the ability of com.sun.star.uno.XInterface to acquire and release objects by reference counting. In Java, the programmer does not bother with acquire() and release(), since the Java UNO runtime automatically acquires objects on the server side when com.sun.star.uno.UnoRuntime.queryInterface() is used. Conversely, when the Java garbage collector deletes your references, the Java UNO runtime releases the corresponding office objects. If a UNO object is written in Java, no reference counting is used to control its lifetime. The garbage collector takes that responsibility.

Sometimes it is necessary to find out if two interfaces belong to the same object. In Java, you would compare the references with the equality operator '=='. This works as long as the interfaces refer to a local Java object. Often the interfaces are proxies and the real objects reside in a remote process. There can be several proxies that belong to the same object, because objects are bridged on a per-interface basis. Those proxies are Java objects and comparing their references would not establish them as parts of the same object. To determine if interfaces are part of the same UNO object, use the method areSame() at the com.sun.star.uno.UnoRuntime class:

  static public boolean areSame(Object object1, Object object2)
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages