UNO Reflection API
This section describes the UNO Reflection API. This API includes services and interfaces that can be used to get information about interfaces and objects at runtime.
The interface com.sun.star.lang.XTypeProvider allows the developer to retrieve all types provided by an object. These types are usually interface types and the
XTypeProvider interface can be used at runtime to detect which interfaces are supported by an object. This interface should be supported by every object to make it scriptable from Apache OpenOffice Basic.
The service com.sun.star.script.Converter supporting the interface com.sun.star.script.XTypeConverter provides basic functionality that is important in the reflection context. It converts values to a particular type. For the method convertTo(), the target type is specified as type, allowing any type available in the UNO type system. The method convertToSimpleType() converts a value into a simple type that is specified by the corresponding com.sun.star.uno.TypeClass. If the requested conversion is not feasible, both methods throw a com.sun.star.script.CannotConvertException.
The service com.sun.star.reflection.CoreReflection supporting the interface com.sun.star.reflection.XIdlReflection is an important entry point for the Uno Reflection API. The
XIdlReflection interface has two methods that each return a com.sun.star.reflection.XIdlClass interface for a given name (method
forName()) or any value (method getType()).
XIdlClass is one of the central interfaces of the Reflection API. It provides information about types, especially about class or interface, and struct types. Besides general information, for example, to check type identity through the method
equals() or to determine a type or class name by means of the method
getName(), it is possible to ask for the fields or members, and methods supported by an interface type (method
getFields() returning a sequence of
XIdlField interfaces and method
getMethods() returning a sequence of
XIdlField is deprecated and should not be used. Instead the interface com.sun.star.reflection.XIdlField2 is available by querying it from an
XIdlField interface returned by an
XIdlField2 represents a struct member of a struct or get or set accessor methods of an interface type. It provides information about the field (methods
getAccessMode()) and reads and - if allowed by the access mode - modifies its value for a given instance of the corresponding type (methods
XIdlMethod represents a method of an interface type. It provides information about the method (methods
getMode()) and invokes the method for a given instance of the corresponding type (method
The service com.sun.star.beans.Introspection supporting the interface com.sun.star.beans.XIntrospection is used to inspect an object of interface or struct type to obtain information about its members and methods. Unlike the
CoreReflection service, and the
XIdlClass interface ,the inspection is not limited to one interface type but to all interfaces supported by an object. To detect the interfaces supported by an object, the Introspection service queries for the
XTypeProvider interface. If an object does not support this interface, the introspection does not work correctly.
To inspect an object, pass it as an any value to the
inspect() method of
XIntrospection. The result of the introspection process is returned as com.sun.star.beans.XIntrospectionAccess interface. This interface is used to obtain information about the inspected object. All information returned refers to the complete object as a combination of several interfaces. When accessing an object through
XIntrospectionAccess, it is impossible to distinguish between the different interfaces.
The com.sun.star.beans.XIntrospectionAccess interface provides a list of all properties (method getProperties()) and methods (method
getMethods()) supported by the object. The introspection maps methods matching the pattern
FooType getFoo() setFoo(FooType)
to a property
Foo of type
com.sun.star.beans.XIntrospectionAccess also supports a categorization of properties and methods. For instance, it is possible to exclude "dangerous" methods, such as the reference counting methods acquire() and release() from the set of methods returned by
getMethods(). When the Introspection service is used to bind a new scripting language, it is useful to block the access to functionality that could crash the entire Apache OpenOffice application when used in an incorrect manner.
XIntrospectionAccess interface does not allow the developer to invoke methods and access properties directly. To invoke methods, the invoke() method of the
XIdlMethod interfaces returned by the methods
getMethod() are used. To access properties, a com.sun.star.beans.XPropertySet interface is used that can be queried from the queryAdapter() method. This method also provides adapter interfaces for other generic access interfaces like com.sun.star.container.XNameAccess and com.sun.star.container.XIndexAccess, if these interfaces are also supported by the original object.
The service com.sun.star.script.Invocation supporting the interface com.sun.star.lang.XSingleServiceFactory provides a generic, high-level access (higher compared to the
Introspection service) to the properties and methods of an object. The object that should be accessed through
Introspection is passed to the createInstanceWithArguments() method. The returned
XInterface can then be queried for com.sun.star.script.XInvocation2 derived from com.sun.star.script.XInvocation.
XInvocation interface invokes methods and access properties directly by passing their names and additional parameters to the corresponding methods (method
setValue()). It is also possible to ask if a method or property exists with the methods
When invoking a method with
invoke(), the parameters are passed as a sequence of any values. The Invocation service automatically converts these arguments, if possible to the appropriate target types using the com.sun.star.script.Converter service that is further described below. The
Introspection functionality is suitable for binding scripting languages to UNO that are not or only weakly typed.
XInvocation2 interface extends the
Invocation functionality by methods to ask for further information about the properties and methods of the object represented by the
Invocation instance. It is possible to ask for the names of all the properties and methods (method
getMemberNames()) and detailed information about them represented by the com.sun.star.script.InvocationInfo struct type (methods
|Members of struct com.sun.star.script.InvocationInfo|
||Name of the method or property.|
||Kind of the member (method or property).|
||Only for property members: This field may contain zero or more constants of the |
||Type of the member, when referring to methods, the return type|
||Types of method parameters, for properties this sequence is empty|
||Mode of method parameters (|
Invocation service is based on the
Introspection service. The
XInvocation interface has a method
getIntrospection() to ask for the corresponding
XIntrospectionAccess interface. The
Invocation implementation currently implemented in OpenOffice.org supports this, but in general, an implementation of
XInvocation does not provide access to an
The service com.sun.star.script.InvocationAdapterFactory supporting the interfaces com.sun.star.script.XInvocationAdapterFactory and com.sun.star.script.XInvocationAdapterFactory2 are used to create adapters that map a generic
XInvocation interface to specific interfaces. This functionality is especially essential for creating scripting language bindings that do not only access UNO from the scripting language, but also to implement UNO objects using the scripting language. Without the
InvocationAdapterFactory functionality, this would only be possible if the scripting language supported the implementation of interfaces directly.
By means of the
InvocationAdapterFactory functionality it is only necessary to map the scripting language specific native invocation interface, for example, realized by an OLE
IDispatch interface, to the UNO
XInvocation interface. Then, any combination of interfaces needed to represent the services supported by a UNO object are provided as an adapter using the createAdapter() method.
Another important use of the invocation adapter is to create listener interfaces that are passed to the corresponding
add...Listener() method of an UNO interface and maps to the methods of an interface to
XInvocation. In this case, usually the createAdapter() method is used.
Internally, types in UNO are represented by the type type. This type also has an interface representation com.sun.star.reflection.XTypeDescription. A number of interfaces derived from
XTypeDescription represent types. These interfaces are:
The corresponding services are com.sun.star.reflection.TypeDescriptionManager and com.sun.star.reflection.TypeDescriptionProvider. These services support com.sun.star.container.XHierarchicalNameAccess and asks for a type description interface by passing the fully qualified type name to the getByHierarchicalName() method.
TypeDescription services and interfaces are listed here for completeness. Ordinarily this functionality would not be used when binding a scripting language to UNO, because the high-level services
Reflection provide all the functionality required. If the binding is implemented in C++, the
type type and the corresponding C API are used directly.
The following illustration provides an overview of how the described services and interfaces work together. Each arrow expresses a "uses" relationship. The interfaces listed for a service are not necessarily supported by the service directly, but contain interfaces that are strongly related to the services.
|Content on this page is licensed under the Public Documentation License (PDL).|