Mapping of Interface Types

From Apache OpenOffice Wiki
Jump to: navigation, search



A UNO interface type is mapped to a public Java interface with the same name. Unlike for Java classes that represent UNO sequence, enum, struct, and exception types, a null reference is actually a legal value for a Java interface that represents a UNO interface type - the Java null reference represents the UNO null reference.

If a UNO interface type inherits one ore more other interface types, the Java interface extends the corresponding Java interfaces.

The UNO interface type com.sun.star.uno.XInterface is special: Only when that type is used as a base type of another interface type is it mapped to the Java type com.sun.star.uno.XInterface. In all other cases (when used as the component type of a sequence type, as a member of a struct or exception type, or as a parameter or return type of an interface method) it is mapped to java.lang.Object. Nevertheless, valid Java values of that type are only the Java null reference and references to those instances of java.lang.Object that implement com.sun.star.uno.XInterface.

A UNO interface attribute of the form

 [attribute] Type Name { 
     get raises (ExceptionG1, ..., ExceptionGM);
     set raises (ExceptionS1, ..., ExceptionSM);
 };

is represented by two Java interface methods

 Type getName() throws ExceptionG1, ..., ExceptionGM;
 void setName(Type value) throws ExceptionS1, ..., ExceptionSM;

If the attribute is marked readonly, then there is no set method. Whether or not the attribute is marked bound has no impact on the signatures of the generated Java methods.

A UNO interface method of the form

 Type0 name([in] Type1 arg1, [out] Type2 arg2, [inout] Type3 arg3) 
             raises (Exception1, ..., ExceptionN);

is represented by a Java interface method

 Type0 name(Type1 arg1, Type2[] arg2, Type3[] arg3) 
             throws Exception1, ..., ExceptionN;

Whether or not the UNO method is marked oneway has no impact on the signature of the generated Java method. As can be seen, out and inout parameters are handled specially. To help explain this, take the example UNOIDL definitions

  struct FooStruct { 
      long nval;
      string strval;
  };
 
  interface XFoo {
      string funcOne([in] string value);
      FooStruct funcTwo([inout] FooStruct value);
      sequence<byte> funcThree([out] sequence<byte> value);
  };

The semantics of a UNO method call are such that the values of any in or inout parameters are passed from the caller to the callee, and, if the method is not marked oneway and the execution terminated successfully, the callee passes back to the caller the return value and the values of any out or inout parameters. Thus, the handling of in parameters and the return value maps naturally to the semantics of Java method calls. UNO out and inout parameters, however, are mapped to arrays of the corresponding Java types. Each such array must have at least one element (i.e., its length must be at least one; practically, there is no reason why it should ever be larger). Therefore, the Java interface corresponding to the UNO interface XFoo looks like the following:

 public interface XFoo extends com.sun.star.uno.XInterface { 
     String funcOne(String value);
     FooStruct funcTwo(FooStruct[] value);
     byte[] funcThree(byte[][] value);
 }

This is how FooStruct would be mapped to Java:

  public class FooStruct {
      public int nval;
      public String strval;
 
      public FooStruct() {
          strval="";
      }
 
      public FooStruct(int nval, String strval) {
          this.nval = nval;
          this.strval = strval;
      }
  }

When providing a value as an inout parameter, the caller has to write the input value into the element at index zero of the array. When the function returns successfully, the value at index zero reflects the output value, which may be the unmodified input value, a modified copy of the input value, or a completely new value. The object obj implements XFoo:

  // calling the interface in Java
  obj.funcOne(null);                          // error, String value is null
  obj.funcOne("");                            // OK
 
  FooStruct[] inoutstruct= new FooStruct[1];
  obj.funcTwo(inoutstruct);                   // error, inoutstruct[0] is null
 
  inoutstruct[0]= new FooStruct();            // now we initialize inoutstruct[0]
  obj.funcTwo(inoutstruct);                   // OK

When a method receives an argument that is an out parameter, upon successful return, it has to provide a value by storing it at index null of the array.

  // method implementations of interface XFoo
  public String funcOne(/*in*/ String value) {
      assert value != null;                           // otherwise, it is a bug of the caller
      return null;                                    // error; instead use: return "";
  }
 
  public FooStruct funcTwo(/*inout*/ FooStruct[] value) {
      assert value != null && value.length >= 1 && value[0] != null;
      value[0] = null;                                // error; instead use: value[0] = new FooStruct();
      return null;                                    // error; instead use: return new FooStruct();
  }
 
  public byte[] funcThree(/*out*/ byte[][] value) {
      assert value != null && value.length >= 1;
      value[0] = null;                               // error; instead use: value[0] = new byte[0];
      return null;                                   // error; instead use: return new byte[0];
  }


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