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 215 maps to Java −215, …, UNO 216 − 1 maps to Java −1.)LONG
:int
.UNSIGNED LONG
:int
. (UNO 231 maps to Java −231, …, UNO 232 − 1 maps to Java −1.)HYPER
:long
.UNSIGNED HYPER
:long
. (UNO 263 maps to Java −263, …, UNO 264 − 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 iscom.sun.star.uno.Exception
, or (b)java.lang.RuntimeException
if N iscom.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 N1, …, Nk, k ≥ 0: interface type named N′, extending the mapped types N1′, …, Nk′. 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 typecom.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 typejava.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 2N.
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, 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 thatcom.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 215maps to Java −215, …, UNO 216 − 1 maps to Java −1.)LONG
: non-null references to java.lang.Integer.UNSIGNED LONG
: non-null references to java.lang.Integer. (UNO 231 maps to Java −231, …, UNO 232 − 1 maps to Java −1.)HYPER
: non-null references to java.lang.Long.UNSIGNED HYPER
: non-null references to java.lang.Long. (UNO 263 maps to Java −263, …, UNO 264 − 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 causejava.lang.ArrayStoreException
s.) - 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
, orTYPE
. - Any sequence type whose component type is contained in the following list:
- Any of
BOOLEAN
,BYTE
,SHORT
,LONG
,HYPER
,FLOAT
,DOUBLE
,CHAR
, orSTRING
. 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 typecom.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 eitherjava.lang.Object
orcom.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 typecom.sun.star.uno.XInterface
, notjava.lang.Object
.
- Any of
- 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 typeLONG
can be mapped either
- to an instance of
com.sun.star.uno.Any
, containing ajava.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 anint[]
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 ajava.lang.Object[]
with one element of value null, or - to an instance of
com.sun.star.uno.Any
, containing acom.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 ajava.lang.Object[]
, or - to an instance of
com.sun.star.uno.Any
, containing acom.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.