Package org.oorexx.uno

# Class RgfReflectUNO

java.lang.Object
org.oorexx.uno.RgfReflectUNO

public class RgfReflectUNO extends Object
This class allows reflecting UNO objects and types using the type descriptions and usually returns results as strings only (to facilitate interaction with scripting languages); originally devised for Open Object Rexx (cf. http://www.ooRexx.org).

    ------------------------ Apache Version 2.0 license -------------------------
        Copyright (C) 2006-2011 Rony G. Flatscher

        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at

            http://www.apache.org/licenses/LICENSE-2.0

        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
     -----------------------------------------------------------------------------

Version:
  1.0.3, 2011-02-15
Author:
  Rony G. Flatscher

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static boolean`
  `bDebug`
  Controls issuing some debug messages, if set to `true`.
  `static String`
  `version`
  Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Object`
  `findInterfaceWithMember(Object o, String needle, boolean bReturnString, int howMany, boolean bExtendSearch)`
  Looks for the interface in a service object (`o`) containing a member (a method or attribute) of the given `name`.
  `static com.sun.star.uno.XComponentContext`
  `getContext()`
  Returns the value of the current XComponentObject in use, or null, if not set yet.
  `static String`
  `getDefinition(Object o)`
  Returns a blank delimited string containing the UNOIDL definitions of an UNO object (or a string denoting the fully qualified UNOIDL name).
  `static String`
  `getInterfaceNamesViaReflection(Object o)`
  Returns a blank delimited String of the interface names that are defined in UNOIDL for the service object.
  `static String`
  `getProperties(Object o)`
  Creates and returns a blank delimited string of property definitions available for the service object `o`.
  `static String`
  `getServiceNamesViaReflection(Object o)`
  Returns a blank delimited String of service names that are defined in UNOIDL for the service object.
  `static String`
  `getTypeName(Object o)`
  Returns string indicating the type of the supplied UNO object.
  `static String`
  `getXTypeProviderTypeNames(Object o)`
  Returns a blank delimited string of names of the provided interface types.
  `static String`
  `queryInterfaceName(Object o, String name, boolean bExtendSearch)`
  Looks up a (partially qualified) given interface name case-insensitively and returns the fully-qualified mixed case interface name.
  `static Object`
  `queryInterfaceObjectByName(Object o, String name, boolean bExtendSearch)`
  Looks up a (partially qualified) given interface name case-insensitively, carries out the appropriate `UnoRuntime.queryInterface()` and returns its result.
  `static String`
  `queryServiceName(Object o, String name)`
  Looks up a (partially qualified) given service name case-insensitively and returns the fully-qualified mixed case service name.
  `static com.sun.star.uno.XComponentContext`
  `setContext(com.sun.star.uno.XComponentContext ctxt)`
  Sets the component context and gets singletons and type descriptions from it.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### version

    public static String version
    Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.

  - ### bDebug

    public static boolean bDebug
    Controls issuing some debug messages, if set to `true`. Default value: `false`.

- ## Method Details

  - ### getContext

    public static com.sun.star.uno.XComponentContext getContext()
    Returns the value of the current XComponentObject in use, or null, if not set yet.
    Returns:
      The component context object that is used for this class or `null`, if not set.

  - ### setContext

    public static com.sun.star.uno.XComponentContext setContext(com.sun.star.uno.XComponentContext ctxt)
    Sets the component context and gets singletons and type descriptions from it. (Will invoke the private method `"setUpPropertyAttributesHashTable()"`.)
    Parameters:
      `ctxt` - component context object to be used for this class, if `null`, then a default component context is created using "com.sun.star.comp.helper.Bootstrap.bootstrap()".
    Returns:
      The component context object that is used for this class.

  - ### getTypeName

    public static String getTypeName(Object o)
    Returns string indicating the type of the supplied UNO object. All of the possible return values are documented at the end of `getDefinition(Object o)` ("…strings representing UNO-Types…").
    Parameters:
      `o` - UNO object or fully qualified string referring to an UNOIDL definition
    Returns:
      String spelling out the UNO type or empty string, if type cannot be determined

  - ### getDefinition

    public static String getDefinition(Object o)
    Returns a blank delimited string containing the UNOIDL definitions of an UNO object (or a string denoting the fully qualified UNOIDL name).
    Here are the encodings for the different UNOIDL types:

    TypeClass | Encoding
    --- | ---
    UNO_CONSTANTS | `UNO_CONSTANTS|fully-qualified-name|datatype member-name|value…` Remark: the following UNO `"datatype"`s are allowed for constants: `UNO_BOOLEAN` (Java: `boolean`), `UNO_BYTE` (Java: `byte`), `UNO_SHORT` (Java: `short`), `UNO_UNSIGNED_SHORT` (Java: `short`), `UNO_LONG` (Java: `int`), `UNO_UNSIGNED_LONG` (Java: `int`), `UNO_HYPER` (Java: `long`), `UNO_UNSIGNED_HYPER` (Java: `long`), `UNO_FLOAT` (Java: `float`), `UNO_DOUBLE` (Java: `double`).
    UNO_ENUM | `UNO_ENUM|fully-qualified-name|default-value member-name|value…` Remark: this is always of UNO type `UNO_LONG` (ie. a 32-bit integer, Java type: `int`)
    UNO_EXCEPTION | `UNO_EXCEPTION|fully-qualified-name member-name|fullDatatype…`
    UNO_INTERFACE | `UNO_INTERFACE|fully-qualified-name member-name|member-definition… where "member-definition" is one of: UNO_ATTRIBUTE|[READONLY]|fullDatatype… UNO_METHOD|[ONEWAY]|return-value-fullDatatype|[argName:fullDatatype[,…]|[exception[,…]]`
    UNO_MODULE | `UNO_MODULE|fully-qualified-name fully-qualified-member-name|UNO-Type…`
    UNO_SERVICE | `UNO_SERVICE|fully-qualified-name|[implementationName]member-name|member-definition… where "member-definition" is one of: UNO_INTERFACE|[OPTIONAL]|defined_by_service UNO_SERVICE|[OPTIONAL]|defined_by_service UNO_PROPERTY|[modifier[,…]]|fullDatatype|defined_by_service` Remark: if a service object is reflected that implements more than one service definition, than the "fully-qualified-name" of that compound service is created by concatenating all service names with the plus sign (+). Each of these constituting service definitions (if available via reflection) is then used to create the entire definition of that "compound service" object in hand, documenting all defined interfaces, services and properties. Remark ad `"UNO_PROPERTY"`: the modifier values may be one or a (comma-delimited) combination of: `"MAYBEVOID", "BOUND", "CONSTRAINED", "TRANSIENT", "READONLY", "MAYBEAMBIGUOUS", "MAYBEDEFAULT", "REMOVEABLE", "OPTIONAL"`.
    UNO_SINGLETON | `UNO_SINGLETON|fully-qualified-name|[old-style-servicename]` Remark: old-style-servicename or empty string if an instance of an interface
    UNO_STRUCT | `UNO_STRUCT|fully-qualified-name member-name|fullDatatype…`
    UNO_TYPEDEF | `UNO_TYPEDEF|fully-qualified-name referenced-type|UNO-Type`

    `"fullDatatype"` is encoded as follows:

      `fully-qualified-datatype-name:UNO-TypeClass:[referenced-type]:[UNO-TypeClass]`

      If a datatype is of type `UNO_TYPEDEF`, then its "referenced-type-name" is given together with its respective UNO-TypeClass.

    The following strings representing UNO-Types ("TypeClasses") may be encountered:

      `"UNO_ANY", "UNO_ARRAY", "UNO_BOOLEAN", "UNO_BYTE", "UNO_CHAR", "UNO_CONSTANT", "UNO_CONSTANTS", "UNO_DOUBLE", "UNO_ENUM", "UNO_EXCEPTION", "UNO_FLOAT", "UNO_HYPER", "UNO_INTERFACE", "UNO_INTERFACE_ATTRIBUTE" "UNO_INTERFACE_METHOD", "UNO_LONG", "UNO_MODULE", "UNO_PROPERTY", "UNO_SEQUENCE", "UNO_SERVICE", "UNO_SHORT", "UNO_SINGLETON", "UNO_STRING", "UNO_STRUCT", "UNO_TYPE", "UNO_TYPEDEF", "UNO_UNION", "UNO_UNKNOWN", "UNO_UNSIGNED_HYPER", "UNO_UNSIGNED_LONG", "UNO_UNSIGNED_SHORT", "UNO_VOID"`.

      Remark: The UNO "`TypeClass`" constant names use the respective names above, but without the lead-in string "`UNO_`" (this makes the type information from methods of this class unambiguous).

    The UNO datatypes map to Java as follows:

      UNO Datatype | Java Datatype
      --- | ---
      `UNO_ANY` | `com.sun.star.uno.Any` or `java.lang.Object`
      `UNO_VOID` | `void`
      `UNO_BOOLEAN` | `boolean`
      `UNO_BYTE` (8-bit) | `byte`
      `UNO_CHAR` (16-bit) | `char`
      `UNO_SHORT` (16-bit) | `short`
      `UNO_UNSIGNED_SHORT` (16-bit) | `short`
      `UNO_LONG` (32-bit) | `int`
      `UNO_UNSIGNED_LONG` (32-bit) | `int`
      `UNO_HYPER` (64-bit) | `long`
      `UNO_UNSIGNED_HYPER` (64-bit) | `long`
      `UNO_FLOAT` | `float`
      `UNO_DOUBLE` | `double`

    Parameters:
      `o` - UNO service object or string fully qualifying a service definition in an UNOIDL module
    Returns:
      string containing the UNOIDL definitions, each element delimited with a blank, each element's definition parts delimited with a vertical bar (|).

  - ### getXTypeProviderTypeNames

    public static String getXTypeProviderTypeNames(Object o)
    Returns a blank delimited string of names of the provided interface types. Cf. UNO's `com.sun.star.lang.XTypeProvider` interface which is applied to the service object `o`.
    Parameters:
      `o` - a service object which gets queried of its provided interface types using the XTypeProvider interface
    Returns:
      blank delimited string of interface names, empty string if none available

  - ### queryInterfaceObjectByName

    public static Object queryInterfaceObjectByName(Object o, String name, boolean bExtendSearch)
    Looks up a (partially qualified) given interface name case-insensitively, carries out the appropriate `UnoRuntime.queryInterface()` and returns its result.
    Parameters:
      `name` - which may qualify the desired interface fully or partly, case does not matter either. If `name` denotes an existing Java class, that class is used to carry out the UnoRuntime.queryInterface(...). Otherwise an interface class is searched at runtime using `XTypeProvider` and possibly reflection.
      `o` - is the object from which the interface should be queried from
      `bExtendSearch` - `true`: if interface cannot be found in the `XTypeProvider` list, then extend search using full reflection; it could be the case that `XTypeProvider` does not provide all available interfaces! (as of OOo 2.0, 2005-12-20)
    Returns:
      the desired interface object, if successful, `null` else

  - ### getInterfaceNamesViaReflection

    public static String getInterfaceNamesViaReflection(Object o)
    Returns a blank delimited String of the interface names that are defined in UNOIDL for the service object.
    Parameters:
      `o` - service object to analyze
    Returns:
      a blank delimited string of service names (or empty string)

  - ### getServiceNamesViaReflection

    public static String getServiceNamesViaReflection(Object o)
    Returns a blank delimited String of service names that are defined in UNOIDL for the service object.
    Parameters:
      `o` - service object to analyze
    Returns:
      a blank delimited string of service names (or empty string)

  - ### getProperties

    public static String getProperties(Object o)
    Creates and returns a blank delimited string of property definitions available for the service object `o`. To find out about all available interfaces in a service object at runtime use `getXTypeProviderTypeNames(Object o)`, to find the interface in which a member (a method or an attribute) got defined at runtime use `findInterfaceWithMember(Object o, String needle, boolean bReturnString, int howMany, boolean bExtendSearch)`.
    Parameters:
      `o` - a service object
    Returns:
      blank delimited string of property definitions in the form `property-name|full-datatype-name:UNO-TypeClass:[referenced-type]:[UNTO-TypeClass]`.

  - ### findInterfaceWithMember

    public static Object findInterfaceWithMember(Object o, String needle, boolean bReturnString, int howMany, boolean bExtendSearch)
    Looks for the interface in a service object (`o`) containing a member (a method or attribute) of the given `name`. This method uses the `XTypeProvider` interface to search the available interfaces at runtime. To find out about all properties of a service object at runtime use `getProperties(Object o)`.
    Parameters:
      `o` - service object to analyze
      `needle` - denotes the name to look for case-independently
      `bReturnString` - if `true` then the string encoded INTERFACE information (cf. `getDefinition(Object o)`) is returned having the denoted member(s), otherwise the queried interface object is returned, which can be immediately addressed to invoke the member method or access the member attribute.
      `howMany` - determines how many members matching `needle` should be searched and returned. Only relevant, if `bReturnString` is `true`. interfaces that contain the sought for member should be returned. A number less than 1 indicates to return all matching interface definitions (separated by a newline character 0x0A).
      `bExtendSearch` - `true`: if interface cannot be found in the `XTYpeProvider` list, then extend search using full reflection; it could be the case that `XTYpeProvider` does not provide all available interfaces! (as of OOo 2.0, 2005-12-20)
    Returns:
      either a string (`bReturnString==true`, can be empty, if no definitions were found) or the desired interface object (`bReturnString==false`, can be null `null`) depending on the value of parameter

  - ### queryInterfaceName

    public static String queryInterfaceName(Object o, String name, boolean bExtendSearch)
    Looks up a (partially qualified) given interface name case-insensitively and returns the fully-qualified mixed case interface name.
    Parameters:
      `o` - service object to analyze
      `name` - denotes the name to look for case-independently
      `bExtendSearch` - `true`: if interface cannot be found in the `XTYpeProvider` list, then extend search using full reflection; it could be the case that `XTYpeProvider` does not provide all available interfaces! (as of OOo 2.0, 2005-12-20)
    Returns:
      fully-qualified interface name or empty string, if not found.

  - ### queryServiceName

    public static String queryServiceName(Object o, String name)
    Looks up a (partially qualified) given service name case-insensitively and returns the fully-qualified mixed case service name.
    Parameters:
      `o` - service object to analyze
      `name` - denotes the name to look for case-independently
    Returns:
      fully-qualified service name or empty string, if not found.