Difference between revisions of "Documentation/DevGuide/ProUNO/Java/Mapping of Interface Types"
m |
m |
||
Line 31: | Line 31: | ||
A UNO interface method of the form | A UNO interface method of the form | ||
− | Type0 name([in] Type1 arg1, [out] Type2 arg2, [inout] Type3 arg3) raises (Exception1, ..., ExceptionN); | + | Type0 name([in] Type1 arg1, [out] Type2 arg2, [inout] Type3 arg3) |
+ | raises (Exception1, ..., ExceptionN); | ||
is represented by a Java interface method | is represented by a Java interface method | ||
− | Type0 name(Type1 arg1, Type2[] arg2, Type3[] arg3) throws Exception1, ..., ExceptionN; | + | Type0 name(Type1 arg1, Type2[] arg2, Type3[] arg3) |
+ | throws Exception1, ..., ExceptionN; | ||
Whether or not the UNO method is marked <code>oneway</code> has no impact on the signature of the generated Java method. As can be seen, <code>out</code> and <code>inout</code> parameters are handled specially. To help explain this, take the example UNOIDL definitions | Whether or not the UNO method is marked <code>oneway</code> has no impact on the signature of the generated Java method. As can be seen, <code>out</code> and <code>inout</code> parameters are handled specially. To help explain this, take the example UNOIDL definitions |
Revision as of 04:10, 3 July 2008
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). |