UNO Reflection API

From Apache OpenOffice Wiki
Jump to: navigation, search



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.

XTypeProvider Interface

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 OpenOffice.org Basic.

Converter Service

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 <idlml>com.sun.star.script.XTypeConverter:convertTo</idlml>(), the target type is specified as type, allowing any type available in the UNO type system. The method <idlml>com.sun.star.script.XTypeConverter:convertToSimpleType</idlml>() 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.

CoreReflection Service

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()).

The interface 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 XIdlMethod interfaces).

The interface 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 XIdlClass method.

The interface XIdlField or 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 getType() and getAccessMode()) and reads and - if allowed by the access mode - modifies its value for a given instance of the corresponding type (methods get() and set()).

The interface XIdlMethod represents a method of an interface type. It provides information about the method (methods getReturnType(), getParameterTypes(), getParameterInfos(), getExceptionTypes() and getMode()) and invokes the method for a given instance of the corresponding type (method invoke()).

Introspection

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)

or 

 FooType isFoo()  
 setFoo(FooType)

to a property Foo of type FooType.

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 OpenOffice.org application when used in an incorrect manner.

The 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 getMethods() and 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.

Invocation

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.

The XInvocation interface invokes methods and access properties directly by passing their names and additional parameters to the corresponding methods (method invoke(), getValue() and setValue()). It is also possible to ask if a method or property exists with the methods hasMethod() and hasProperty().

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.

The 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 getInfo() and getInfoForName()).

Members of struct com.sun.star.script.InvocationInfo
aName Name of the method or property.
eMemberType Kind of the member (method or property).
PropertyAttribute Only for property members: This field may contain zero or more constants of the com::sun::star::beans::PropertyAttribute constants group. It is not guaranteed that all necessary constants are set to describe the property completely, but a flag will be set if the corresponding characteristic really exists. For example, if the READONLY flag is set, the property is read only. If it is not set, the property nevertheless can be read only. This field is irrelevant for methods and is set to 0.
aType Type of the member, when referring to methods, the return type
aParamTypes Types of method parameters, for properties this sequence is empty
aParamModes Mode of method parameters (in, out, inout), for properties this sequence is empty.

The 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 XInvocationAccess interface.

InvocationAdapterFactory

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 <idlml>com.sun.star.script.XInvocationAdapterFactory2:createAdapter</idlml>() 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 <idlml>com.sun.star.script.XInvocationAdapterFactory:createAdapter</idlml>() method is used.

XTypeDescription

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 <idlml>com.sun.star.container.XHierarchicalNameAccess:getByHierarchicalName</idlml>() method.

The 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 Invocation, Introspection and 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.

UML diagram showing the a Scripting Language Binding
Content on this page is licensed under the Public Documentation License (PDL).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/DevGuide/AdvUNO/UNO_Reflection_API&oldid=200256"
Personal tools
In other languages