Uno/Java/Specifications/Type Mapping

Mapping between Uno and Java Types

See UNO Type System for a specification of the UNO type system and some related terms.

Mapping Types

The mapping between UNO types and Java types is as follows:

• VOID: void.
• BOOLEAN: boolean.
• BYTE: byte.
• SHORT: short.
• UNSIGNED SHORT: short. (UNO 2¹⁵ maps to Java −2¹⁵, …, UNO 2¹⁶ − 1 maps to Java −1.)
• LONG: int.
• UNSIGNED LONG: int. (UNO 2³¹ maps to Java −2³¹, …, UNO 2³² − 1 maps to Java −1.)
• HYPER: long.
• UNSIGNED HYPER: long. (UNO 2⁶³ maps to Java −2⁶³, …, UNO 2⁶⁴ − 1 maps to Java −1.)
• FLOAT: float.
• DOUBLE: double.
• CHAR: char.
• STRING: java.lang.String. (Only non-null references are valid values.)
• TYPE: com.sun.star.uno.Type. (Only non-null references are valid values.)
• ANY: java.lang.Object. (See Section Mapping Values of Type ANY for a discussion of valid values.)
• Sequence type of component type T: array of mapped type T′, where T′ is recursively defined by this list. (Only non-null references are valid values.)
• Enum type named N: class type named N′, extending com.sun.star.uno.Enum. (Only non-null references are valid values.)
• Struct type named N, possibly derived from a base struct type named N2: class type named N&prime, extending (a) the mapped type N2′ in case N is derived from N2, or (b) java.lang.Object otherwise. (Only non-null references are valid values.)
• Exception type named N, possibly derived from a base exception type named N2: class type named N′, extending (a) java.lang.Exception if N is com.sun.star.uno.Exception, or (b) java.lang.RuntimeException if N is com.sun.star.uno.RuntimeException, or (c) the mapped type N2′ in case N is derived from N2. (Only non-null references are valid values.)
• Interface type named N, with direct bases named N₁, …, N_k, k ≥ 0: interface type named N′, extending the mapped types N₁′, …, N_k′. The interface type named 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 value of an interface method) it is mapped to the Java type java.lang.Object. (See Section Mapping Values for a discussion of valid values.)

Mapping Values

Values of type VOID are not mapped (type VOID is only used in two places: as a return type for interface methods, where it denotes no return value—see Section Interface Methods; and as a possible type contained in a value of type ANY—see Section Mapping Values of Type ANY).

Values of type BOOLEAN, BYTE, SHORT, LONG, HYPER, FLOAT, DOUBLE, and CHAR are mapped directly to values of the corresponding Java types.

Values of type UNSIGNED SHORT, UNSIGNED LONG, and UNSIGNED HYPER are mapped to values of the corresponding (signed) Java types, modulo 2^N.

Values of type STRING are mapped to non-null references to java.lang.String.

Values of type TYPE are mapped to non-null references to com.sun.star.uno.Type.

Values of sequence types are mapped to non-null references to the corresponding Java array types. (Non-null references to other array types that are assignment compatible to those types may also be used, but that can cause java.lang.ArrayStoreExceptions.)

Values of enum types, struct types, and exception types are mapped to non-null references to the corresponding Java class types.

Values of interface types (i.e., the null reference plus references to UNO objects implementing those interfaces) are mapped to references to Java objects that implement (directly, or indirectly through inheritance) the corresponding Java interface types and that do not extend any of com.sun.star.uno.Any, com.sun.star.uno.Enum, com.sun.star.uno.Type</code>, and java.lang.Throwable. Particularly, the UNO null reference maps to the Java null reference. Even though com.sun.star.uno.XInterface is mapped to java.lang.Object in certain cases (see Section Mapping Types), 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 and do not extend any of com.sun.star.uno.Any, com.sun.star.uno.Enum, com.sun.star.uno.Type, and java.lang.Throwable.

Mapping Values of Type ANY

Generally, there is a mapping between UNO ANY values and instances of the Java class type com.sun.star.uno.Any. Conceptionally, for a UNO ANY represented as 〈t, v〉 (where t is of type TYPE and v is of type t), the corresponding com.sun.star.uno.Any instance can be represented as 〈t′, v′〉 (where t′ is of type com.sun.star.uno.Type and v′ is of type java.lang.Object). Given a type t (which cannot be ANY), the general mapping between v and v′ is as follows:

• VOID: no mapping of values (this is where the concept breaks that com.sun.star.uno.Any is represented as 〈t′, v′〉).
• BOOLEAN: non-null references to java.lang.Boolean.
• BYTE: non-null references to java.lang.Byte.
• SHORT: non-null references to java.lang.Short.
• UNSIGNED SHORT: non-null references to java.lang.Short. (UNO 2¹⁵maps to Java −2¹⁵, …, UNO 2¹⁶ − 1 maps to Java −1.)
• LONG: non-null references to java.lang.Integer.
• UNSIGNED LONG: non-null references to java.lang.Integer. (UNO 2³¹ maps to Java −2³¹, …, UNO 2³² − 1 maps to Java −1.)
• HYPER: non-null references to java.lang.Long.
• UNSIGNED HYPER: non-null references to java.lang.Long. (UNO 2⁶³ maps to Java −2⁶³, …, UNO 2⁶⁴ − 1 maps to Java −1.)
• FLOAT: non-null references to java.lang.Float.
• DOUBLE: non-null references to java.lang.Double.
• CHAR: non-null references to java.lang.Character.
• STRING: non-null references to java.lang.String.
• TYPE: non-null references to com.sun.star.uno.Type.
• Sequence type of component type T: non-null references to arrays of mapped type T′, where T′ is as defined in Section Mapping Types. (Non-null references to other array types that are assignment compatible to T′[] may also be used, but that can cause java.lang.ArrayStoreExceptions.)
• Enum type named N: non-null references to mapped type N′.
• Struct type named N: non-null references to mapped type N′.
• Exception type named N: non-null references to mapped type N′.
• Interface type named N: references to classes implementing the mapped type N′.

For certain UNO ANY values 〈t, v〉, the corresponding Java value (which would generally be an instance of com.sun.star.uno.Any represented as 〈t′, v′〉) can also be shortcut to v′. This holds when t is any of the following:

• Any of BOOLEAN, BYTE, SHORT, LONG, HYPER, FLOAT, DOUBLE, CHAR, STRING, or TYPE.
• Any sequence type whose component type is contained in the following list:
  • Any of BOOLEAN, BYTE, SHORT, LONG, HYPER, FLOAT, DOUBLE, CHAR, or STRING.
  • TYPE, provided that the Java array value v′ is exactly of the corresponding Java array type t′, not of another, assignment-compatible array type. (Unfortunately, the Java type com.sun.star.uno.Type is not final.)
  • ANY, provided that the Java array value v′ is exactly of a Java array type with a base component type of either java.lang.Object or com.sun.star.uno.Any, not of another, assignment-compatible array type.
  • Any sequence type whose component type is recursively contained in this list.
  • Any enum type, plain struct type, or exception type, provided that the Java array value v′ is exactly of the corresponding Java array type t′, not of another, assignment-compatible array type.
  • Any interface type named N, provided that the Java array value v′ is exactly of a Java array type with a base component type of N′, not of another, assignment-compatible array type. If N is com.sun.star.uno.XInterface, the corresponding N′ is the Java interface type com.sun.star.uno.XInterface, not java.lang.Object.
• Any enum type, plain struct type, or exception type, provided that theJava value v′ is exactly of the corresponding type t′, not of another, assignment-compatible type.
• The interface type named com.sun.star.uno.XInterface.

This is an optimization, avoiding creation of instances of class com.sun.star.uno.Any.

Examples

A UNO ANY containing the value 5 of type LONG can be mapped either

• to an instance of com.sun.star.uno.Any, containing a java.lang.Integer of value 5, or
• directly to an instance of java.lang.Integer containing 5.

A UNO ANY containing a sequence of type LONG with one element of value 5 can be mapped either

• to an instance of com.sun.star.uno.Any, containing an int[] with one element of value 5, or
• directly to an instance of int[] with one element of value 5,

but it cannot be mapped to an instance of java.lang.Integer[] (or a com.sun.star.uno.Any containing a java.lang.Integer[]).

A UNO ANY containing the null reference to the interface type named com.sun.star.uno.XInterface can be mapped either

• to an instance of com.sun.star.uno.Any, containing the Java value null, or
• directly to the Java value null.

But a UNO ANY containing the null reference to some interface type other than com.sun.star.uno.XInterface must always be mapped as an instance of com.sun.star.uno.Any.

A UNO ANY containing a sequence of interface type com.sun.star.uno.XInterface, which in turn has as a single element the null reference, can be mapped either

• to an instance of com.sun.star.uno.Any, containing a java.lang.Object[] with one element of value null, or
• to an instance of com.sun.star.uno.Any, containing a com.sun.star.uno.XInterface[] with one element of value null, or
• directly to an instance of com.sun.star.uno.XInterface[] with one element of value null,

but it cannot be mapped to a plain instance of java.lang.Object[].

A UNO ANY containing a sequence of type ANY can be mapped either

• to an instance of com.sun.star.uno.Any, containing a java.lang.Object[], or
• to an instance of com.sun.star.uno.Any, containing a com.sun.star.uno.Any[], or
• directly to an instance of java.lang.Object[], or
• directly to an instance of com.sun.star.uno.Any[].

Interface Methods

UNO interface methods use types for the return value, any parameters, and any exception specifications. The return value must be of non-exception type, the parameters must be of non-void, non-exception types, and the exception specifications must be of exception types. Parameters may be in, out, or in-out parameters. Generally, the mapping of types and values used in interface methods is as described in Section Mapping Values, but out and in-out parameters need further special handling.

Out and in-out parameters of type T are mapped to Java arrays of mapped type T′ (see Section Mapping Types). At runtime, the (Java) argument will be a non-null reference to an array of exactly the mapped type T′ (not another, assignment-compatible type) and length at least 1. For in-out parameters, the value of the first element will be the (Java-mapped) in argument; for out parameters, the value of the first element will be undefined. Upon normal return (i.e., no exception is thrown), the first element of that array must contain the (Java-mapped) out argument.