[ Previous document | Content Table | Next document ]

4    Writing UNO Components

OpenOffice.org can be extended by UNO components. UNO components are shared libraries or jar files with the ability to instantiate objects that can integrate themselves into the UNO environment. A UNO component can access existing features of OpenOffice.org, and it can be used from within OpenOffice.org through the object communication mechanisms provided by UNO.

OpenOffice.org provides many entry points for these extensions.

From OpenOffice.org 1.1 there is comprehensive support for component extensions. The entire product cycle of a component is now covered:

The design and development of components has been made easier by adding wizards for components to the NetBeans IDE. They are described in the directory docs/DevStudioWizard of the SDK. There are wizards for general components, for Calc AddIns and for IDL files.

Components can integrate themselves into the user interface, using simple configuration files. You can add new menus, toolbar items, and help items for a component simply by editing XML configuration files.

Component deployment is performed by a package installer, which inserts new components and their user interface extensions into networked and single installations of OpenOffice.org. During the production phase the package installer makes it simple to maintain components, to introduce bug fixes and new versions of a component. When a packaged component is no longer needed, it can  easily be removed. This way, OpenOffice.org keeps the promise of being open for modular extensions.

Last but not least, this is not the only way to add features to the office. Learning how to write components and how to use the OpenOffice.org API at the same time teaches you the techniques used in the OpenOffice.org code base, thus enabling you to work with the existing OpenOffice.org source code, extend it or introduce bug fixes.

Components are the basis for all of these extensions. This chapter teaches you how to write UNO components. It assumes that you have at least read the chapter 2 First Steps and—depending on your target language—the section about the Java or C++ language binding in 3 Professional UNO.

4.1    Required Files

OpenOffice.org Software Development Kit (SDK)

The SDK provides a build environment for your projects, separate from the OpenOffice.org build environment. It contains the necessary tools for UNO development, C and C++ libraries and include files, Java packages, UNO type definitions and example code. But most of the necessary libraries and Java UNO packages are shared with an existing OpenOffice.org installation which is a prerequisite for a SDK.

The SDK development tools (executables) contained in the SDK are used in the following chapter. Become familiar with the following table that lists the executables from the SDK. These executables are found in the platform specific bin folder of the SDK installation. In Windows, they are in the folder <SDK>\windows\bin, on Linux they are stored in <SDK>/linux/bin and on Solaris in <SDK>/solaris/bin.

Executable

Description

idlc

The UNOIDL compiler that creates binary type description files with the extension .urd for registry database files.

idlcpp

The idlc preprocessor used by idlc.

cppumaker

The C++ UNO maker that generates headers with UNO types mapped from binary type descriptions to C++ from binary type descriptions.

javamaker

Java maker that generates interface and class definitions for UNO types mapped from binary type descriptions to Java from binary type descriptions.

xml2cmp

XML to Component that can extract type names from XML object descriptions for use with cppumaker and javamaker, creates functions.

regmerge

The registry merge that merges binary type descriptions into registry files.

regcomp

The register component that tells a registry database file that there is a new component and where it can be found.

pkgchk

The package check that installs components into an installed OpenOffice.org.

regview

The registry view that outputs the content of a registry database file in readable format.

autodoc

The automatic documentation tool that evaluates Javadoc style comments in idl files and generates documentation from them.

rdbmaker

The registry database maker that creates registry files with selected types and their dependencies.

uno

The UNO executable. It is a standalone UNO environment which is able to run UNO components supporting the com.sun.star.lang.XMain interface, one possible use is:
$ uno -s ServiceName -r MyRegistry.rdb -- MyMainClass arg1

GNU Make

The makefiles in the SDK assume that the GNU make is used. Documentation for GNU make command line options and syntax are available at www.gnu.org. In Windows, not every GNU make seems stable, notably some versions of Cygwin make were reported to have problems with the SDK makefiles. Other GNU make binaries, such as the one from unixutils.sourceforge.net work well even on the Windows command line. The package UnxUtils comes with a zsh shell and numerous utilities, such as find, sed. To install UnxUtils, download and unpack the archive, and add <UnxUtils>\usr\local\wbin to the PATH environment variable. Now launch sh.exe from <UnxUtils>\bin and issue the command make from within zsh or use the Windows command line to run make. For further information about zsh, go to zsh.sunsite.dk.

4.2    Using UNOIDL to Specify New Components

Component development does not necessarily start with the declaration of new interfaces or new types. Try to use the interfaces and types already defined in the OpenOffice.org API. If existing interfaces cover your requirements and you need to know how to implement them in your own component, go to section 4.3 Writing UNO Components - Component Architecture. The following describes how to declare your own interfaces and other types you might need.

UNO uses its own meta language UNOIDL (UNO Interface Definition Language) to specify types. Using a meta language for this purpose enables you to generate language specific code, such as header files and class definitions, to implement objects in any target language supported by UNO. UNOIDL keeps the foundations of UNO language independent and takes the burden of mechanic language adaptation from the developer's shoulders when implementing UNO objects.

To define a new interface, service or other compound type, write its specification in UNOIDL, then compile it with the UNOIDL compiler idlc. After compilation, merge the resulting binary type description into a registry database that is used by cppumaker and javamaker during the make process to create necessary header and class files, and used by UNO during runtime to provide runtime type information. The chapter 3 Professional UNO provides the various type mappings used by cppumaker and javamaker in the language binding sections. Refer to the section 4.9.2 Writing UNO Components - Deployment Options for Components - Background: UNO Registries - UNO Type Library for details about type information in the registry database..

Note graphics marks a special text section

When writing your own specifications, please consult the chapter A IDL Design Guide which treats design principles and conventions used in API specifications. Follow the rules for universality, orthogonality, inheritance and uniformity of the API as described in the Design Guide.

4.2.1    Writing the Specification

There are similarities between C++, CORBA IDL and UNOIDL, especially concerning the syntax and the general usage of the compiler. If you are familiar with reading C++ or CORBA IDL, you will be able to understand much of UNOIDL, as well.

As a first example, consider the IDL specification for the com.sun.star.bridge.XUnoUrlResolver interface. An idl file usually starts with a number of preprocessor directives, followed by module instructions and a type definition:

#ifndef __com_sun_star_bridge_XUnoUrlResolver_idl__

#define __com_sun_star_bridge_XUnoUrlResolver_idl__

 

#include <com/sun/star/uno/XInterface.idl>

#include <com/sun/star/lang/IllegalArgumentException.idl>

#include <com/sun/star/connection/ConnectionSetupException.idl>

#include <com/sun/star/connection/NoConnectException.idl>

 

module com {  module sun {  module star {  module bridge {

 

/** service <type scope="com::sun::star::bridge">UnoUrlResolver</type>

        implements this interface.

 */

interface XUnoUrlResolver: com::sun::star::uno::XInterface

{

    // method com::sun::star::bridge::XUnoUrlResolver::resolve

    /** resolves an object, on the UNO URL.

     */

    com::sun::star::uno::XInterface resolve( [in] string sUnoUrl )

        raises (com::sun::star::connection::NoConnectException,

                com::sun::star::connection::ConnectionSetupException,

                com::sun::star::lang::IllegalArgumentException);

};

 

}; }; }; };

#endif

We will discuss this idl file step by step below, and we will write our own UNOIDL specification as soon as possible. The file specifying com.sun.star.bridge.XUnoUrlResolver is located in the idl folder of your SDK installation, <SDK>/idl/com/sun/star/bridge/XUnoUrlResolver.idl.

UNOIDL definition file names have the extension . idl by convention. The descriptions must use the US ASCII character set without special characters and separate symbols by whitespace, i.e. blanks, tabs or linefeeds.

Preprocessing

Just like a C++ compiler, the UNOIDL compiler idlc can only use types it already knows. The idlc knows 15 fundamental types such as boolean, int or string (they are summarized below). Whenever a type other than a fundamental type is used in the idl file, its declaration has to be included first. For instance, to derive an interface from the interface XInterface, include the corresponding file XInterface.idl. Including means telling the preprocessor to read a given file and execute the instructions found in it.

#include <com/sun/star/uno/XInterface.idl> // searched in include path given in -I parameter

#include "com/sun/star/uno/XInterface.idl" // searched in current path, then in include path

There are two ways to include idl files. A file name in angled brackets is searched on the include path passed to idlc using its -I option. File names in double quotes are first searched on the current path and then on the include path.

The XUnoUrlResolver definition above includes com.sun.star.uno.XInterface and the three exceptions thrown by the method resolve(), com.sun.star.lang.IllegalArgumentException, com.sun.star.connection.ConnectionSetupException and com.sun.star.connection.NoConnectException.

Furthermore, to avoid warnings about redefinition of already included types, use #ifndef and #define as shown above. Note how the entire definition for XUnoUrlResolver is enclosed between #ifndef and #endif. The first thing the preprocessor does is to check if the flag __com_sun_star_bridge_XUnoUrlResolver_idl__ has already been defined. If not, the flag is defined and idlc continues with the definition of XUnoUrlResolver.

Adhere to the naming scheme for include flags used by the OpenOffice.org developers: Use the file name of the IDL file that is to be included, add double underscores at the beginning and end of the macro, and replace all slashes and dots by underscores.

For other preprocessing instructions supported by idlc refer to Bjarne Stroustrup: The C++ Programming Language.

Grouping Definitions in Modules

To avoid name clashes and allow for a better API structure, UNOIDL supports naming scopes. The corresponding instruction is module:

module mymodule {

};

Instructions are only known inside the module mymodule for every type defined within the pair of braces of this module {} . Within each module, the type identifiers are unique. This makes an UNOIDL module similar to a Java package or a C++ namespace.

Modules may be nested. The following code shows the interface XUnoUrlResolver contained in the module bridge that is contained in the module star, which is in turn contained in the module sun of the module com.

module com {  module sun {  module star {  module bridge {

    // interface XUnoUrlResolver in module com::sun::star::bridge

}; }; }; };

It is customary to write module names in lower case letters. Use your own module hierarchy for your IDL types. To contribute code to OpenOffice.org, use the org::openoffice namespace or com::sun::star. Discuss the name choice with the leader of the API project on www.openoffice.org to add to the latter modules. The com::sun::star namespace mirrors the historical roots of OpenOffice.org in StarOffice and will probably be kept for compatibility purposes.

Types defined in UNOIDL modules have to be referenced using full-type or scoped names, that is, you must enter all modules your type is contained in and separate the modules by the scope operator ::. For instance, to reference XUnoUrlResolver in another idl definition file, write com::sun::star::bridge::XUnoUrlResolver.

Besides, modules have an advantage  when it comes to generating language specific files. The tools cppumaker and javamaker automatically create subdirectories for every referenced module, if required. Headers and class definitions are kept in their own folders without any further effort.

Fundamental Types

Before we can go about defining our first interface, you need to know the fundamental types you may use in your interface definition. You should already be familiar with the fundamental UNO types from the chapters 2 First Steps and 3 Professional UNO. Since we have to use them in idl definition files, we repeat the type keywords and their meaning here.

Fundamental UNO type

Type description

char

16-bit unicode character type

boolean

boolean type; true and false

byte

8-bit ordinal integer type

short

signed 16-bit ordinal integer type

unsigned short

unsigned 16-bit ordinal integer type

long

signed 32-bit ordinal integer type

unsigned long

unsigned 32-bit integer type

hyper

signed 64-bit ordinal integer type

unsigned hyper

unsigned 64-bit ordinal integer type

float

processor dependent float

double

processor dependent double

string

string of 16-bit unicode characters

any

universal type, takes every fundamental or compound UNO type, similar to Variant in other environments or Object in Java

void

Indicates that a method does not provide a return value

Defining an Interface

Interfaces describe aspects of objects. To specify a new behavior for the component, start with an interface definition that comprises the methods offering the new behavior. Define a pair of plain get and set methods in a single step using the attribute instruction. Alternatively, choose to define your own operations with arbitrary arguments and exceptions by writing the operation signature, and the exceptions the operation throws. We will first write a small interface definition with attribute instructions, then consider the resolve() operation in XUNoUrlResolver.

Let us assume we want to contribute an ImageShrink component to OpenOffice.org to create thumbnail images for use in OpenOffice.org tables. There is already a com.sun.star.document.XFilter Interface offering methods supporting file conversion. In addition, a method is required to get and set the source and target directories, and the size of the thumbnails to create. It is common practice that a service and its prime interface have corresponding names, so our component shall have an org::openoffice::test::XImageShrink interface with methods to do so through get and set methods.

Attributes

The attribute instruction creates these methods for the experimental interface definition:

Look at the specification for our XImageShrink interface: (Components/Thumbs/org/openoffice/test/XImageShrink.idl)

#ifndef __org_openoffice_test_XImageShrink_idl__

#define __org_openoffice_test_XImageShrink_idl__

#include <com/sun/star/uno/XInterface.idl>

#include <com/sun/star/awt/Size.idl>

module org { module openoffice { module test {

interface XImageShrink : com::sun::star::uno::XInterface

{

    [attribute] string SourceDirectory;

    [attribute] string DestinationDirectory;

    [attribute] com::sun::star::awt::Size Dimension;

};

}; }; };

#endif

Note graphics marks a special text section

OpenOffice.org API interfaces do not use attributes anymore, because it entices programmers into ignoring exceptions. They are confusing, because attributes are mapped as prefixed get/set methods in an implementation language like Java or C++. It is sometimes difficult to match these methods with the original attribute declaration. Also note, that attribute definitions in UNOIDL interfaces do not declare any data fields, just the access methods.

We protect the interface from being redefined using #ifndef, then added #include com.sun.star.uno.XInterface and the struct com.sun.star.awt.Size. These were found in the API reference using its global index. Our interface will be known in the org::openoffice::test module, so it is nested in the corresponding module instructions.

Define an interface using the interface instruction. It opens with the keyword interface, gives an interface name and derives the new interface from a parent interface (also called super interface). It then defines the interface body in braces. The interface instruction concludes with a semicolon.

In this case, the introduced interface is XImageShrink. By convention, all interface identifiers start with an X. Every interface must inherit from the base interface for all UNO interfaces XInterface or from one of its derived interfaces. UNO supports single inheritance, so you may only inherit from one interface. Inheritance is expressed by a colon : followed by the fully qualified name of the parent type. The fully qualified name of a UNOIDL type is its identifier, including all containing modules separated by the scope operator ::. Here we derive from com::sun::star::uno::XInterface directly.

Pay attention to the following important text section

UNOIDL allows forward declaration of interfaces used as parameters, return values or struct members. However, an interface you want to derive from must be a fully defined interface.

After the super interface the interface body begins. It may contain attribute instructions or operations. Consider the interface body of XImageShrink. It contains three attributes and no operation. The operations are discussed below.

An attribute instruction opens with the keyword attribute in square brackets, then it gives a known type and an identifier for the attribute, and concludes with a semicolon.

In our example, the string attributes named SourceDirectory and DestinationDirectory and a com::sun::star::awt::Size attribute known as Dimension were defined:

    [attribute] string SourceDirectory;

    [attribute] string DestinationDirectory;

    [attribute] com::sun::star::awt::Size Dimension;

During code generation, the attribute instruction leads to pairs of get and set methods. For instance, the Java interface generated by javamaker from this type description contains the following six methods. Note that no exceptions can be specified for attribute methods:

    // from attribute SourceDir

    public String getSourceDirectory();

    public void setSourceDirectory(String _sourcedir);

    // from attribute DestinationDir

    public String getDestinationDirectory();

    public void setDestinationDirectory(String _destinationdir);

    // from attribute Dimension

    public com.sun.star.awt.Size getDimension();

    public void setDimension(com.sun.star.awt.Size _dimension);

As an option, define that an attribute cannot be changed from the outside using a readonly flag. To set this flag, write [attribute, readonly]. The effect is that only a get() method is created during code generation, but not a set() method.

Operations

When writing a real component, define the operations by providing their signature and the exceptions they throw in the idl file. Our XUnoUrlResolver example above features a resolve() operation taking a UNO URL and throwing three exceptions.

interface XUnoUrlResolver: com::sun::star::uno::XInterface

{

    com::sun::star::uno::XInterface resolve( [in] string sUnoUrl )

        raises (com::sun::star::connection::NoConnectException,

                com::sun::star::connection::ConnectionSetupException,

                com::sun::star::lang::IllegalArgumentException);

};

The basic structure of an operation is similar to C++ functions or Java methods. The operation is defined giving a known return type, the operation name, an argument list in brackets () and if necessary, a list of the exceptions the operation may throw. The argument list, the exception clause raises () and an optional [ oneway ] flag preceding the operation are special in UNOIDL.

Direction Flags for Operations

Description

in

Specifies that t he operation shall evaluate the argument as input parameter, but it cannot change it.

out

Specifies that t he argument does not parameterize the operation, instead the operation uses the argument as output parameter.

inout

Specifies that the operation is parameterized by the argument and that the operation uses the argument as output parameter as well.

Pay attention to the following important text section

You may not override an attribute or an operation inherited from a parent interface, that would not make sense in an abstract specification anyway. Furthermore, overloading is not possible. The qualified interface identifier in conjunction with the name of the method creates a unique method name.

Defining a Service

UNOIDL Services combine interfaces and properties to specify a certain functionality. In addition, services can include other services. For these purposes, the instructions interface, property and service are used within service specifications. Usually services are the basis for an object implementation, although there are services in the OpenOffice.org API that only serve as foundation or addition to other services, but are not meant to be implemented by themselves.

We are ready to assemble our ImageShrink service. Our service will read image files from a source directory and write shrinked versions of the found images to a destination directory. Our XImageShrink interface offers the needed capabilities, together with the interface com.sun.star.document.XFilter that supports two methods:

boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor)

void cancel()

The following code shows the ImageShrink service specification: (Components/Thumbs/org/openoffice/test/ImageShrink.idl)

#ifndef __org_openoffice_test_ImageShrink_idl__

#define __org_openoffice_test_ImageShrink_idl__

#include <org/openoffice/test/XImageShrink.idl>

module org { module openoffice { module test {

service ImageShrink

{

    interface org::openoffice::test::XImageShrink;

    interface com::sun::star::document::XFilter;

};

}; }; };

#endif

Define a service using the service instruction. It opens with the keyword service, followed by a service name and the service body in braces. The service instruction concludes with a semicolon. Here we defined a service ImageShrink. The first letter of a service name should be an upper-case letter. The body of a service can reference interfaces and services using interface and service instructions, and it can identify properties supported by the service through [property] instructions.

Property Flags

Description

optional

Property is non-mandatory.

readonly

The value of the property cannot be changed using the setter methods for properties, such as setPropertyValue(string name).

bound

Changes of values are broadcast to com.sun.star.beans.XPropertyChangeListeners registered with the component.

constrained

The component must broadcast an event before a value changes, listeners can veto.

maybeambiguous

The value cannot be determined in some cases, for example, in multiple selections.

maybedefault

The value might come from a style or the application environment instead of from the object itself.

maybevoid

The property type determines the range of possible values, but sometimes there may be situations where there is no information available. Instead of defining special values for each type denoting that there are no meaningful values, the UNO type void can be used. Its meaning is comparable to null in relational databases.

removable

The property is removable. If a property is made removable, you must check for the existence of a property using hasPropertyByName() at the interface com.sun.star.beans.XPropertySetInfo and consider providing the capability to add or remove properties using com.sun.star.beans.XPropertyContainer.

transient

The property will not be stored if the object is serialized (made persistent).

Note graphics marks a special text section

Some services, which specify no interfaces at all, only properties, are used as a sequence of com.sun.star.beans.PropertyValue in OpenOffice.org, for example, com.sun.star.document.MediaDescriptor.

The following UNOIDL snippet shows the service, the interfaces and the properties supported by the service com.sun.star.text.TextDocument as defined in UNOIDL. Note the optional interfaces and the optional and read-only properties.

service TextDocument

{

    service com::sun::star::document::OfficeDocument;

    interface com::sun::star::text::XTextDocument;

    interface com::sun::star::util::XSearchable;

    interface com::sun::star::util::XRefreshable;

    interface com::sun::star::util::XNumberFormatsSupplier;

    [optional] interface com::sun::star::text::XFootnotesSupplier;

    [optional] interface com::sun::star::text::XEndnotesSupplier;

    [optional] interface com::sun::star::util::XReplaceable;

    [optional] interface com::sun::star::text::XPagePrintable;

    [optional] interface com::sun::star::text::XReferenceMarksSupplier;

    [optional] interface com::sun::star::text::XLineNumberingSupplier;

    [optional] interface com::sun::star::text::XChapterNumberingSupplier;

    [optional] interface com::sun::star::beans::XPropertySet;

    [optional] interface com::sun::star::text::XTextGraphicObjectsSupplier;

    [optional] interface com::sun::star::text::XTextEmbeddedObjectsSupplier;

    [optional] interface com::sun::star::text::XTextTablesSupplier;

    [optional] interface com::sun::star::style::XStyleFamiliesSupplier;

    [optional, property] com::sun::star::lang::Locale CharLocale;

    [optional, property] string WordSeparator;

    [optional, readonly, property] long CharacterCount;

    [optional, readonly, property] long ParagraphCount;

    [optional, readonly, property] long WordCount;

};

Pay attention to the following important text section

You might encounter two more instructions in service bodies. The instruction observes can stand in front of interface references and means that the given interfaces must be "observed". Since the observes instruction is disapproved of, no further explanation is provided.
If a service references another service using the keyword
needs in front of the reference, then this service depends on the availability of the needed service at runtime. Newly specified services should not use needs as it is considered too implementation specific.

Defining a Sequence

A sequence in UNOIDL is an array containing a variable number of elements of the same UNOIDL type. The following is an example of a sequence term:

// this term could occur in a UNOIDL definition block somewhere

sequence< com::sun::star::uno::XInterface >

It starts with the keyword sequence and gives the element type enclosed in angle brackets <>. The element type must be a known type. A sequence type can be used as parameter, return value, property or struct member just like any other type. Sequences can also be nested, if necessary.

// this could be a nested sequence definition

sequence< sequence< long > >

// this could be an operation using sequences in some interface definition

sequence< string > getNamesOfIndex(sequence< long > indexes);

Defining a Struct

A struct is a compound type which puts together arbitrary UNOIDL types to form a new data type. Its member data are not encapsulated, rather they are publicly available. Structs are frequently used to handle related data easily, and the event structs broadcast to event listeners.

A struct instruction opens with the keyword struct, gives an identifier for the new struct type and has a struct body in braces. It is terminated by a semicolon. The struct body contains a list of struct member declarations that are defined by a known type and an identifier for the struct member. The member declarations must end with a semicolon, as well.

#ifndef __com_sun_star_reflection_ParamInfo_idl__

#define __com_sun_star_reflection_ParamInfo_idl__

#include <com/sun/star/reflection/ParamMode.idl>

 

module com {  module sun {  module star {  module reflection {

 

interface XIdlClass; // forward interface declaration

 

struct ParamInfo

{

    string aName;

    ParamMode aMode;

    XIdlClass aType;

};

 

}; }; }; };

#endif

UNOIDL supports inheritance of struct types. Inheritance is expressed by a colon : followed by the full name of the parent type. A struct type recursively inherits all members of the parent struct and their parents. For instance, derive from the struct com.sun.star.lang.EventObject to put additional information about new events into customized event objects to send to event listeners.

// com.sun.star.beans.PropertyChangeEvent inherits from com.sun.star.lang.EventObject

// and adds property-related information to the event object

struct PropertyChangeEvent : com::sun::star::lang::EventObject

{

    string PropertyName;

    boolean Further;

    long PropertyHandle;

    any OldValue;

    any NewValue;

};

Defining an Exception

An exception type is a type that contains information about an error. If an operation detects an error that halts the normal process flow, it must raise an exception and send information about the error back to the caller through an exception object. This causes the caller to interrupt its normal program flow as well and react according to the information received in the exception object. For details about exceptions and their implementation, refer to the chapters 3.4 Professional UNO - UNO Language Bindings and 3.3.6 Professional UNO - UNO Concepts - Exception Handling.

There are a number of exceptions to use. The exceptions should be sufficient in many cases, because a message string can be sent back to the caller. When defining an exception, do it in such a way that other developers could reuse it in their contexts.

An exception instruction opens with the keyword exception, gives an identifier for the new exception type and has an exception body in braces. It is terminated by a semicolon. The exception body contains a list of exception member declarations that are defined by a known type and an identifier for the exception member. The member declarations must end with a semicolon, as well.

Exceptions must be based on com.sun.star.uno.Exception or com.sun.star.uno.RuntimeException, directly or indirectly through derived exceptions of these two exceptions. com.sun.star.uno.Exceptions can only be thrown in operations specified to raise them while com.sun.star.uno.RuntimeExceptions can always occur. Inheritance is expressed by a colon :, followed by the full name of the parent type.

// com.sun.star.uno.Exception is the base exception for all exceptions

exception Exception {

    string Message;

    XInterface Context;

};

// com.sun.star.lang.IllegalArgumentException tells the caller which

// argument caused trouble

exception IllegalArgumentException: com::sun::star::uno::Exception

{

    /** identifies the position of the illegal argument.

        <p>This field is -1 if the position is not known.</p>

     */

    short ArgumentPosition;

 

};

// com.sun.star.uno.RuntimeException is the base exception for serious errors

// usually caused by programming errors or problems with the runtime environment

exception RuntimeException : com::sun::star::uno::Exception {

};

// com.sun.star.uno.SecurityException is a more specific RuntimeException

exception SecurityException : com::sun::star::uno::RuntimeException {

};

Predefining Values

Predefined values can be provided, so that implementers do not have to use cryptic numbers or other literal values. There are two kinds of predefined values, constants and enums. Constants can contain values of any fundamental UNOIDL type, except string. The enums are automatically numbered long values.

Const and Constants

The constants type is a container for const types. A constants instruction opens with the keyword constants, gives an identifier for the new group of const values and has the body in braces. It terminates with a semicolon. The constants body contains a list of const definitions that define the values of the members starting with the keyword const followed by a known type name and the identifier for the const in uppercase letters. Each const definition must assign a value to the const using an equals sign. The value must match the given type and can be an integer or floating point number, or a character, or a suitable const value or an arithmetic term based on the operators in the table below. The const definitions must end with a semicolon, as well.

#ifndef __com_sun_star_awt_FontWeight_idl__

#define __com_sun_star_awt_FontWeight_idl__

module com {  module sun {  module star {  module awt {

constants FontWeight

{

    const float DONTKNOW = 0.000000;

    const float THIN = 50.000000;

    const float ULTRALIGHT = 60.000000;

    const float LIGHT = 75.000000;

    const float SEMILIGHT = 90.000000;

    const float NORMAL = 100.000000;

    const float SEMIBOLD = 110.000000;

    const float BOLD = 150.000000;

    const float ULTRABOLD = 175.000000;

    const float BLACK = 200.000000;  

};

}; }; }; };

Operators Allowed in const

Meaning

+

addition

-

subtraction

*

multiplication

/

division

%

modulo division

-

negative sign

+

positive sign

|

bitwise or

^

bitwise xor

&

bitwise and

~

bitwise not

>> <<

bitwise shift right, shift left

Tip graphics marks a hint section in the text

Use constants to group const types. In the Java language, binding a constants group leads to one class for all const members, whereas a single const is mapped to an entire class.

Enum

An enum type holds a group of predefined long values and maps them to meaningful symbols. It is equivalent to the enumeration type in C++. An enum instruction opens with the keyword enum, gives an identifier for the new group of enum values and has an enum body in braces. It terminates with a semicolon. The enum body contains a comma-separated list of symbols in uppercase letters that are automatically mapped to long values counting from zero, by default.

#ifndef __com_sun_star_style_ParagraphAdjust_idl__

#define __com_sun_star_style_ParagraphAdjust_idl__

 

module com {  module sun {  module star {  module style {

enum ParagraphAdjust

{

    LEFT,

    RIGHT,

    BLOCK,

    CENTER,

    STRETCH

};

}; }; }; };

#endif

In this example, com.sun.star.style.ParagraphAdjust:LEFT corresponds to 0, ParagraphAdjust.RIGHT corresponds to 1 and so forth.

An enum member can also be set to a long value using the equals sign. All the following enum values are then incremented starting from this value. If there is another assignment later in the code, the counting starts with that assignment:

enum Error {

    SYSTEM = 10, // value 10

    RUNTIME,     // value 11

    FATAL,       // value 12

    USER = 30,   // value 30

    SOFT         // value 31

};

Pay attention to the following important text section

The explicit use of enum values is deprecated and should not be used. It is a historical characteristic of the enum type but it makes not really sense and makes, for example language bindings unnecessarily complicated.

Using Comments

Comments are code sections ignored by idlc. In UNOIDL, use C++ style comments. A double slash // marks the rest of the line as comment. Text enclosed between /* and */ is a comment that may span over multiple lines.

service ImageShrink

{

    // the following lines define interfaces:

    interface org::openoffice::test::XImageShrink; // our home-grown interface

    interface com::sun::star::document::XFilter;

    /* we could reference other interfaces, services and properties here.

       However, the keywords uses and needs are deprecated

    */

};

Based on the above, there are documentation comments that are extracted when idl files are processed with autodoc, the UNOIDL documentation generator. Instead of writing /* or //to mark a plain comment, write /** or /// to create a documentation comment.

/** Don't repeat asterisks within multiple line comments,

  * <- as shown here

  */

/// Don't write multiple line documentation comments using triple slashes,

/// since only this last line will make it into the documentation

Our XUnoUrlResolver sample idl file contains plain comments and documentation comments.

/** service <type scope="com::sun::star::bridge">UnoUrlResolver</type>

    implements this interface.

 */

interface XUnoUrlResolver: com::sun::star::uno::XInterface

{

    // method com::sun::star::bridge::XUnoUrlResolver::resolve

    /** resolves an object, on the UNO URL.

     */

    ...

}

Note the additional <type/> tag in the documentation comment pointing out that the service UnoUrlResolver implements the interface XUnoUrlResolver. This tag becomes a hyperlink in HTML documentation generated from this file. The chapter B IDL Documentation Guide provides a comprehensive description for UNOIDL documentation comments.

Singleton

A singleton instruction defines a global name for a service instance and determines that there can only be one instance of this service that must be reachable under this name. In the future, there will be the capability of retrieving the singleton instance from the component context using the name of the singleton. If the singleton has not been instantiated yet, the component context creates it. A singleton instruction looks like this:

singleton theServiceManager {

    service com::sun::star::lang::ServiceManager;

};

Reserved Types

There are types in UNOIDL which are reserved for future use. The idlc will refuse to compile the specifications if they are tried.

Array

The keyword array is reserved, but it cannot be used in UNOIDL. There will be sets containing a fixed number of elements, as opposed to sequences, that can have an arbitrary number of elements.

Union

There is also a reserved keyword for union types that cannot be used in UNOIDL. A union will look at a variable value from more than one perspective. For instance, a union for a long value is defined and this same value is accessed as a whole, or accessed by its high and low part separately through a union.

4.2.2    Generating Source Code from UNOIDL Definitions

The type description provided in .idl files is used in the subsequent process to create type information for the service manager and to generate header and class files. Processing the UNOIDL definitions is a three-step process.

  1. Compile the .idl files using idlc. The result are .urd files (UNO reflection data) containing binary type descriptions.

  2. Merge the .urd files into a registry database using regmerge. The registry database files have the extension .rdb (registry database). They contain binary data describing types in a tree-like structure starting with / as the root. The default key for type descriptions is the /UCR key (UNO core reflection).

  3. Generate sources from registry files using javamaker or cppumaker . The tools javamaker and cppumaker map UNOIDL types to Java and C++ as described in the chapter 3.4 Professional UNO - UNO Language Bindings. The registries used by these tools must contain all types to map to the programming language used, including all types referenced in the type descriptions. Therefore, javamaker and cppumaker need the registry that was merged, but the entire office registry as well. OpenOffice.org comes with a complete registry database providing all types used by UNO at runtime. The SDK uses the database (type library) of an existing OpenOffice.org installation.

The following shows the necessary commands to create Java class files and C++ headers from .idl files in a simple setup under Linux. We assume the jars from <OFFICE_PROGRAM_PATH>/classes have been added to your CLASSPATH, the SDK is installed in /home/sdk, and /home/sdk/linux/bin is in the PATH environment variable, so that the UNO tools can be run directly. The project folder is /home/sdk/Thumbs and it contains the above .idl file XImageShrink.idl.

# make project folder the current directory

cd /home/sdk/Thumbs

# compile XImageShrink.idl using idlc

#   usage: idlc [-options] file_1.idl ... file_n.idl

#   -C adds complete type information including services

#   -I includepath tells idlc where to look for include files

#

# idlc writes the resulting urds to the current folder by default

idlc -C -I../idl XImageShrink.idl

# create registry database (.rdb) file from UNO registry data (.urd) using regmerge

#   usage: regmerge mergefile.rdb mergeKey regfile_1.urd ... regfile_n.urd

#   mergeKey entry in the tree-like rdb structure where types from .urd should be recorded, the tree

#   starts with the root / and UCR is the default key for type descriptions

#

# regmerge writes the rdb to the current folder by default

regmerge thumbs.rdb /UCR XImageShrink.urd

# generate Java source files for new types from rdb

#   -B base node to look for types, in this case UCR

#   -T type to generate Java files for

#   -nD do not generate sources for dependent types, they are available in the Java UNO jar files

#

# javamaker creates a directory tree for the output files according to

# the modules the given types were placed in. The tree is created in the current folder by default

javamaker -BUCR -Torg.openoffice.test.XImageShrink -nD <OFFICE_PROGRAM_PATH>/applicat.rdb thumbs.rdb

# generate C++ header files (hpp and hdl) for new types and their dependencies from rdb

#   -B base node to look for types, in this case UCR

#   -T type to generate Java files for

#

# cppumaker creates a directory tree for the output files according to

# the modules the given types were placed in. The tree is created in the current folder by default

cppumaker -BUCR -Torg.openoffice.test.XImageShrink <OFFICE_PROGRAM_PATH>/applicat.rdb thumbs.rdb

# compile Java class for new type

javac -g org/openoffice/test/XImageShrink.java

After issuing these commands you have a registry database thumbs.rdb and a Java class file XImageShrink.class. You can run regview against thumbs.rdb to see what regmerge has accomplished.

regview thumbs.rdb

The result for our interface XImageShrink looks like this:

Registry "file:///home/sdk/Thumbs/thumbs.rdb":

/

 / UCR

   / org

     / openoffice

       / test

         / XImageShrink

           Value: Type = RG_VALUETYPE_BINARY

                  Size = 316

                  Data = minor version: 0

                         major version: 1

                         type: 'interface'

                         uik: { 0x00000000-0x0000-0x0000-0x00000000-0x00000000 }

                         name: 'org/openoffice/test/XImageShrink'

                         super name: 'com/sun/star/uno/XInterface'

                         Doku: ""

                         IDL source file: "/home/sdk/Thumbs/XImageShrink.idl"

                         number of fields: 3

                         field #0:

                           name='SourceDirectory'

                           type='string'

                           access=READWRITE

                           Doku: ""

                           IDL source file: ""

                         field #1:

                           name='DestinationDirectory'

                           type='string'

                           access=READWRITE

                           Doku: ""

                           IDL source file: ""

                         field #2:

                           name='Dimension'

                           type='com/sun/star/awt/Size'

                           access=READWRITE

                           Doku: ""

                           IDL source file: ""

                         number of methods: 0

                         number of references: 0

Source generation can be fully automated with makefiles. For details, see the sections 4.5.9 Writing UNO Components - Simple Component in Java - Running and Debugging Java Components and 4.6.10 Writing UNO Components - C++ Component - Building and Testing C++ Components below. You are now ready to implement your own types and interfaces in a UNO component. The next section discusses the UNO core interfaces to implement in UNO components.

4.3    Component Architecture

UNO components are archive files or dynamic link libraries with the ability to instantiate objects which can integrate themselves into the UNO environment. For this purpose, components must contain certain static methods (Java) or export functions (C++) to be called by a UNO service manager. In the following, these methods are called component operations.

There must be a method to supply single-service factories for each object implemented in the component. Through this method, the service manager can get a single factory for a specific object and ask the factory to create the object contained in the component. Furthermore, there has to be a method which writes registration information about the component, which is used when a component is registered with the service manager. In C++, an additional function is necessary that informs the component loader about the compiler used to build the component.

The component operations are always necessary in components and they are language specific. Later, when Java and C++ are discussed, we will show how to write them.

Overview graphic of an UNO component
Illustration 4.1: A Component implementing three UNO objects

The illustration shows a component which contains three implemented objects. Two of them, srv1 and srv2 implement a single service specification (Service1 and Service2), whereas srv3_4 supports two services at once (Service3 and Service4).

The objects implemented in a component must support a number of core UNO interfaces to be fully usable from all parts of the OpenOffice.org application. These core interfaces are discussed in the next section. The individual functionality of the objects is covered by the additional interfaces they export. Usually these interfaces are enclosed in a service specification.

4.4    Core Interfaces to Implement

It is important to know where the interfaces to implement are located. The interfaces here are located at the object implementations in the component. When writing UNO components, the desired methods have to be implemented into the application and also, the core interfaces used to enable communication with the UNO environment. Some of them are mandatory, but there are others to choose from.

Interface

Required

Should be implemented

Optional

Special Cases

Helper class available for C++ and Java

XInterface

XTypeProvider

XServiceInfo

XWeak

XComponent

XInitialization

XMain

XAggregation

XUnoTunnel

The interfaces listed in the table above have been characterized here briefly. More descriptions of each interface are provided later, as well as if helpers are available and which conditions apply.

com.sun.star.uno.XInterface

The component will not work without it. The base interface XInterface gives access to higher interfaces of the service and allows other objects to tell the service when it is no longer needed, so that it can destroy itself.

// com::sun::star::uno::XInterface

any queryInterface( [in] type aType );

[oneway] void acquire(); // increase reference counter in your service implementation

[oneway] void release(); // decrease reference counter, delete object when counter becomes zero

Usually developers do not call acquire() explicitly, because it is called automatically by the language bindings when a reference to a component is retrieved through UnoRuntime.queryInterface() or Reference<destInterface>(sourceInterface, UNO_QUERY) . The counterpart release() is called automatically when the reference goes out of scope in C++ or when the Java garbage collector throws away the object holding the reference.

com.sun.star.lang.XTypeProvider

This interface is used by scripting languages such as OpenOffice.org Basic to get type information. OpenOffice.org Basic cannot use the component without it.

// com::sun::star::lang::XTypeProvider

sequence<type> getTypes();

sequence<byte> getImplementationId();

com.sun.star.lang.XServiceInfo

This interface is used by other objects to get information about the service implementation.

// com::sun::star::lang::XServiceInfo

string getImplementationName();

boolean supportsService( [in] string ServiceName );

sequence<string> getSupportedServiceNames();

com.sun.star.uno.XWeak

This interface allows clients to keep a weak reference to the object. A weak reference does not prevent the object from being destroyed if another client keeps a hard reference to it, therefore it allows a hard reference to be retrieved again. The technique is used to avoid cyclic references. Even if the interface is not required by you, it could be implemented for a client that may want to establish a weak reference to an instance of your object.

// com.sun.star.uno.XWeak

com::sun::star::uno::XAdapter queryAdapter(); // creates Adapter

com.sun.star.lang.XComponent

This interface is used if cyclic references can occur in the component holding another object and the other object is holding a reference to that component. It can be specified in the service description who shall destroy the object.

// com::sun::star::lang::XComponent

void dispose(); //an object owning your component may order it to delete itself using dispose()

void addEventListener(com::sun::star::lang::XEventListener xListener);      // add dispose listeners

void removeEventListener (com::sun::star::lang::XEventListener aListener);  // remove them

com.sun.star.lang.XInitialization

This interface is used to allow other objects to use createInstanceWithArguments() or createInstanceWithArgumentsAndContext() with the component. It should be implemented and the arguments processed in initialize():

// com::sun::star::lang::XInitialization

void initialize(sequence< any > aArguments) raises (com::sun::star::uno::Exception);

com.sun.star.lang.XMain

This interface is for use with the uno executable to instantiate the component independently from the OpenOffice.org service manager.

// com.sun.star.lang.XMain

long run (sequence< string > aArguments);

com.sun.star.uno.XAggregation

This interfaces makes the implementation cooperate in an aggregation. If implemented, other objects can aggregate to the implementation. Aggregated objects behave as if they were one. If another object aggregates the component, it holds the component and delegates calls to it, so that the component seems to be one with the aggregating object.

// com.sun.star.uno.XAggregation

void setDelegator(com.sun.star.uno.XInterface pDelegator);

any queryAggregation(type aType);

com.sun.star.lang.XUnoTunnel

This interface provides a pointer to the component to another component in the same process. This can be achieved with XUnoTunnel. XUnoTunnel should not be used by new components, because it is to be used for integration of existing implementations, if all else fails.

By now you should be able to decide which interfaces are interesting in your case. Sometimes the decision for or against an interface depends on the necessary effort as well. The following section discusses for each of the above interfaces how you can take advantage of pre-implemented helper classes in Java or C++, and what must happen in a possible implementation, no matter which language is used.

4.4.1    XInterface

All service implementations must implement com.sun.star.uno.XInterface. If a Java component is derived from a Java helper class that comes with the SDK, it supports XInterface automatically. Otherwise, it is sufficient to add XInterface or any other UNO interface to the implements list. The Java UNO runtime takes care of XInterface. In C++, there are helper classes to inherit that already implement XInterface. However, if XInterface is to be implemented manually, consider the code below.

The IDL specification for com.sun.star.uno.XInterface looks like this:

// module com::sun::star::uno

interface XInterface

{

    any queryInterface( [in] type aType );

    [oneway] void acquire();

    [oneway] void release();

};

Requirements for queryInterface()

When queryInterface() is called, the caller asks the implementation if it supports the interface specified by the type argument. The UNOIDL base type stores the name of a type and its com.sun.star.uno.TypeClass. The call must return an interface reference of the requested type if it is available or a void any if it is not. There are certain conditions a queryInterface() implementation must meet:

Constant Behaviour

If queryInterface() on a specific object has once returned a valid interface reference for a given type, it must always return a valid reference for any subsequent queryInterface() call for the same type on this object. A query for XInterface must always return the same reference.

If queryInterface() on a specific object has once returned a void any for a given type, it must always return a void any for the same type.

Symmetry

If queryInterface() for XBar on a reference xFoo returns a reference xBar, then queryInterface() on reference xBar for type XFoo must return xFoo or calls made on the returned reference must be equivalent to calls to xFoo.

Object Identity

In C++, two objects are the same if their XInterface are the same. The queryInterface() for XInterface will have to be called on both. In Java, check for the identity by calling the runtime function com.sun.star.uni.UnoRuntime.areSame().

The reason for this specifications is that a UNO runtime environment may choose to cache queryInterface() calls. The rules are identical to the rules of the function QueryInterface() in MS COM.

Tip graphics marks a hint section in the text

If you want to implement queryInterface() in Java, for example, you want to export less interfaces than you implement, your class must implement the Java interface com.sun.star.uno.IQueryInterface.

Reference Counting

The methods acquire() and release() handle the lifetime of the UNO object. This is discussed in detail in chapter 3.3.7 Professional UNO - UNO Concepts - Lifetime of UNO Objects. Acquire and release must be implemented in a thread-safe fashion. This is demonstrated in C++ in the section about C++ components below.

4.4.2    XTypeProvider

Every UNO object should implement the com.sun.star.lang.XTypeProvider interface.

Some applications need to know which interfaces an UNO object supports, for example, the OpenOffice.org Basic engine or debugging tools, such as the InstanceInspector. The com.sun.star.lang.XTypeProvider interface was introduced to avoid going through all known interfaces calling queryInterface() repetitively. The XTypeProvider interface is implemented by Java and C++ helper classes. If the XTypeProvider must be implemented manually, use the following methods:

// module com::sun::star::lang

interface XTypeProvider: com::sun::star::uno::XInterface

{

    sequence<type> getTypes();

    sequence<byte> getImplementationId();

};

The sections about Java and C++ components below show examples of XTypeProvider implementations.

Provided Types

The com.sun.star.lang.XTypeProvider:getTypes() method must return a list of types for all interfaces that queryInterface() provides. The OpenOffice.org Basic engine depends on this information to establish a list of method signatures that can be used with an object.

ImplementationID

For caching purposes, the getImplementationId() method has been introduced. The method must return a byte array containing an identifier for the implemented set of interfaces in this implementation class. It is important that one ID maps to one set of interfaces, but one set of interfaces can be known under multiple IDs. Every implementation class should generate a static ID.

4.4.3    XServiceInfo

Every service implementation should export the com.sun.star.lang.XServiceInfo interface. XServiceInfo must be implemented manually, because only the programmer knows what services the implementation supports. The sections about Java and C++ components below show examples for XServiceInfo implementations.

This is how the IDL specification for XServiceInfo looks like:

// module com::sun::star::lang

interface XServiceInfo: com::sun::star::uno::XInterface

{

    string getImplementationName();

    boolean supportsService( [in] string ServiceName );

    sequence<string> getSupportedServiceNames();

};

Implementation Name

The method getImplementationName() provides access to the implementation name of a service implementation. The implementation name uniquely identifies one implementation of service specifications in a UNO object. The name can be chosen freely by the implementation alone, because it does not appear in IDL. However, the implementation should adhere to the following naming conventions:

company prefix

dot

"comp"

dot

module name

dot

unique object name in module

implemented service(s)

com.sun.star

.

comp

.

forms

.

ODataBaseForm

com.sun.star.forms.DataBaseForm

org.openoffice

.

comp

.

test

.

OThumbs

org.openoffice.test.ImageShrink
org.openoffice.test.ThumbnailInsert
...

If an object implements one single service, it can use the service name to derive an implementation name. Implementations of several services should use a name that describes the entire object.

If a createInstance() is called at the service manager using an implementation name, an instance of exactly that implementation is received. An implementation name is equivalent to a class name in Java. A Java component simply returns the fully qualified class name in getImplementationName().

Tip graphics marks a hint section in the text

It is good practice to program against the specification and not against the implementation, otherwise, your application could break with future versions. OpenOffice.orgs API implementation is not supposed to be compatible, only the specification is.

Supported Service Names

The methods getSupportedServiceNames() and supportsService() deal with the availability of services in an implemented object. Note that the supported services are the services implemented in one class that supports these services, not the services of all implementations contained in the component file. If the illustration : , XServiceInfo is exported by the implemented objects in a component, not by the component. That means, srv3_4 must support XServiceInfo and return "Service3" and "Service4" as supported service names.

The service name identifies a service as it was specified in IDL. If an object is instantiated at the service manager using the service name, an object that complies to the service specification is returned.

Note graphics marks a special text section

The single service factories returned by components that are used to create instances of an implementation through their interfaces com.sun.star.lang.XSingleComponentFactory or com.sun.star.lang.XSingleServiceFactory must support XServiceInfo. The single factories support this interface to allow UNO to inspect the capabilities of a certain implementation before instantiating it. You can take advantage of this feature through the com.sun.star.container.XContentEnumerationAccess interface of a service manager.

4.4.4    XWeak

A component supporting XWeak offers other objects to hold a reference on itself without preventing it from being destroyed when it is no longer needed. Thus, cyclic references can be avoided easily. The chapter 3.3.7 Professional UNO - UNO Concepts - Lifetime of UNO Objects discusses this in detail. In Java, derive from the Java helper class com.sun.star.lib.uno.helper.WeakBase to support XWeak. If a C++ component is derived from one of the ::cppu::Weak...ImplHelperNN template classes as proposed in the section 4.6 Writing UNO Components - C++ Component, a XWeak support is obtained, virtually for free. For the sake of completeness, this is the XWeak specification:

// module com::sun::star::uno::XWeak

interface XWeak: com::sun::star::uno::XInterface

{

    com::sun::star::uno::XAdapter queryAdapter();

};

4.4.5    XComponent

If the implementation holds a reference to another UNO object internally, there may be a problem of cyclic references that might prevent your component and the other object from being destroyed forever. If it is probable that the other object may hold a reference to your component, implement com.sun.star.lang.XComponent that contains a method dispose(). Chapter 3.3.7 Professional UNO - UNO Concepts - Lifetime of UNO Objects discusses the intricacies of this issue.

Supporting XComponent in a C++ or Java component is simple, because there are helper classes to derive from that implement XComponent. The following code is an example if you must implement XComponent manually.

The interface XComponent specifies these operations:

// module com::sun::star::lang

interface XComponent: com::sun::star::uno::XInterface

{

    void dispose();

    void addEventListener( [in] XEventListener xListener );

    void removeEventListener( [in] XEventListener aListener );

};

XComponent uses the interface com.sun.star.lang.XEventListener:

// module com::sun::star::lang

interface XEventListener: com::sun::star::uno::XInterface

{

    void disposing( [in] com::sun::star::lang::EventObject Source );

};

Disposing of an XComponent

The idea behind XComponent is that the object is instantiated by a third object that makes the third object the owner of first object. The owner is allowed to call dispose(). When the owner calls dispose() at your object, it must do three things:

That way the owner of XComponent objects can dissolve a possible cyclic reference.

4.4.6    XInitialization

The interface com.sun.star.lang.XInitialization is usually implemented manually, because only the programmer knows how to initialize the object with arguments received from the service manager through createInstanceWithArguments() or createInstanceWithArgumentsAndContext(). In Java, XInitialization is used as well, but know that the Java factory helper provides a shortcut that uses arguments without implementing XInitialization directly. The Java factory helper can pass arguments to the class constructor under certain conditions. Refer to the section 4.5.7 Writing UNO Components - Simple Component in Java - Create Instance With Arguments for more information.

The specification for XInitialization looks like this:

// module com::sun::star::lang

interface XInitialization : com::sun::star::uno::XInterface

{

    void initialize(sequence< any > aArguments) raises (com::sun::star::uno::Exception);

};

Specify in the idl service specification which arguments and in which order are expected within the any sequence.

4.4.7    XMain

The implementation of com.sun.star.lang.XMain is used for special cases. Its run() operation is called by the uno executable. The section 4.10 Writing UNO Components - The UNO Executable below discusses the use of XMain and the uno executable in detail.

// module com::sun::star::lang


interface XMain: com::sun::star::uno::XInterface
{
   long run( [in] sequence< string > aArguments );
};

4.4.8    XAggregation

A concept called aggregation is commonly used to plug multiple objects together to form one single object at runtime. The main interface in this context is com.sun.star.uno.XAggregation. After plugging the objects together, the reference count and the queryInterface() method is delegated from multiple slave objects to one master object.

It is a precondition that at the moment of aggregation, the slave object has a reference count of exactly one, which is the reference count of the master. Additionally, it does not work on proxy objects, because in Java, multiple proxy objects of the same interface of the same slave object might exist.

While aggregation allows more code reuse than implementation inheritance, the facts mentioned above, coupled with the implementation of independent objects makes programming prone to errors. Therefore the use of this concept is discourage and not explained here. For further information visit http://udk.openoffice.org/common/man/concept/unointro.html#aggregation .

4.4.9    XUnoTunnel

The com.sun.star.lang.XUnoTunnel interface allows access to the this pointer of an object. This interface is used to cast a UNO interface that is coming back to its implementation class through a UNO method. Using this interface is a result of an unsatisfactory interface design, because it indicates that some functionality only works when non-UNO functions are used. In general, these objects cannot be replaced by a different implementation, because they undermine the general UNO interface concept. This interface can be understood as admittance to an already existing code that cannot be split into UNO components easily. If designing new services, do not use this interface.

interface XUnoTunnel: com::sun::star::uno::XInterface

{

    hyper getSomething( [in] sequence< byte > aIdentifier );

};

The byte sequence contains an identifier that both the caller and implementer must know. The implementer returns the this pointer of the object if the byte sequence is equal to the byte sequence previously stored in a static variable. The byte sequence is usually generated once per process per implementation.

Note graphics marks a special text section

Note that the previously mentioned 'per process' is important because the this pointer of a class you know is useless, if the instance lives in a different process.

4.5    Simple Component in Java

This section shows how to write Java components. The examples in this chapter are in the samples folder that was provided with the programmer's manual.

A Java component is a library of Java classes (a jar) containing objects that implement arbitrary UNO services. For a service implementation in Java, implement the necessary UNO core interfaces and the interfaces needed for your purpose. These could be existing interfaces or interfaces defined by using UNOIDL.

Besides these service implementations, Java components need two methods to instantiate the services they implement in a UNO environment: one to get single factories for each service implementation in the jar, and another one to write registration information into a registry database. These methods are called static component operations in the following:

The method that provides single factories for the service implementations in a component is __getServiceFactory():

public static XSingleServiceFactory __getServiceFactory(String implName,

                                   XMultiServiceFactory multiFactory,

                                   XRegistryKey regKey)

In theory, a client obtains a single factory from a component by calling __getServiceFactory() on the component implementation directly. This is rarely done because in most cases service manager is used to get an instance of the service implementation. The service manager uses __getServiceFactory() at the component to get a factory for the requested service from the component, then asks this factory to create an instance of the one object the factory supports.

To find a requested service implementation, the service manager searches its registry database for the location of the component jar that contains this implementation. For this purpose, the component must have been registered beforehand. UNO components are able to write the necessary information on their own through a function that performs the registration and which can be called by the registration tool regcomp. The function has this signature:

public static boolean __writeRegistryServiceInfo(XRegistryKey regKey)

These two methods work together to make the implementations in a component available to a service manager. The method __writeRegistryServiceInfo() tells the service manager where to find an implementation while __getServiceFactory() enables the service manager to instantiate a service implementation, once found.

The necessary steps to write a component are:

  1. Define service implementation classes.

  2. Implement UNO core interfaces.

  3. Implement your own interfaces.

  4. Provide static component operations to make your component available to a service manager.

4.5.1    Class Definition with Helper Classes

XInterface, XTypeProvider and XWeak

The OpenOffice.org Java UNO environment contains Java helper classes that implement the majority of the core interfaces that are implemented by UNO components. There are two helper classes:

The com.sun.star.lang.XServiceInfo is the only interface that should be implemented, but it is not part of the helpers.

Use the naming conventions described in section 4.4.3 Writing UNO Components - Core Interfaces to Implement - XServiceInfo for the service implementation. Following the rules, a service org.openoffice.test.ImageShrink should be implemented in org.openoffice. comp .test.ImageShrink.

A possible class definition that uses ComponentBase could look like this: (Components/Thumbs/org/openoffice/comp/test/ImageShrink.java)

package org.openoffice.comp.test;

public class ImageShrink extends com.sun.star.lib.uno.helper.ComponentBase

        implements com.sun.star.lang.XServiceInfo,

        org.openoffice.test.XImageShrink,

        com.sun.star.document.XFilter  {

    com.sun.star.uno.XComponentContext xComponentContext = null;

    /** Creates a new instance of ImageShrink */

    public ImageShrink(com.sun.star.uno.XComponentContext XComponentContext xContext) {

        this.xComponentContext = xContext;

    }

    ...

}

XServiceInfo

If the implementation only supports one service, use the following code to implement XServiceInfo: (Components/Thumbs/org/openoffice/comp/test/ImageShrink.java)

    ...

    //XServiceInfo implementation

    // hold the service name in a private static member variable of the class

    protected static final String __serviceName = "org.openoffice.test.ImageShrink";

    public String getImplementationName(  ) {

        return getClass().getName();

    }

    public boolean supportsService(String serviceName) {

        if ( serviceName.equals( __serviceName))        

            return true;

        return false;

    }

    public String[] getSupportedServiceNames(  ) {

        String[] retValue= new String[0];

        retValue[0]= __serviceName;

        return retValue;

    }

 

    ...

An implementation of more than one service in one UNO object is more complex. It has to return all supported service names in getSupportedServiceNames(), furthermore it must check all supported service names in supportsService(). Note that several services packaged in one component file are not discussed here, but objects supporting more than one service. Refer to : for the implementation of srv3_4.

4.5.2    Implementing your own Interfaces

The functionality of a component is accessible only by its interfaces. When writing a component, choose one of the available API interfaces or define an interface. IDL types are used as method arguments to other UNO objects. Java does not support unsigned data types, so their use is discouraged. In the chapter 4.2 Writing UNO Components - Using UNOIDL to Specify new Components, the org.openoffice.test.XImageShrink interface specification was written and an interface class file was created. Its implementation is straightforward, you create a class that implements your interfaces: (Components/Thumbs/org/openoffice/comp/test/ImageShrink.java)

package org.openoffice.comp.test;

public class ImageShrink extends com.sun.star.lib.uno.helper.ComponentBase

        implements com.sun.star.lang.XServiceInfo,

                   org.openoffice.test.XImageShrink,

                   com.sun.star.document.XFilter {

    ...

    String destDir = "";

    String sourceDir = "";

    boolean cancel = false;

    com.sun.star.awt.Size dimension = new com.sun.star.awt.Size();

    // XFilter implementation

    public void cancel() {

        cancel = true;

    }

   

    public boolean filter(com.sun.star.beans.PropertyValue[] propertyValue) {

        // while cancel = false,

        // scale images found in sourceDir according to dimension and

        // write them to destDir, using the image file format given in

        // []propertyValue

        // (implementation omitted)

        cancel = false;

        return true;

    }

    // XIMageShrink implementation    

    public String getDestinationDirectory() {

        return destDir;

    }

   

    public com.sun.star.awt.Size getDimension() {

        return dimension;

    }

   

    public String getSourceDirectory() {

        return sourceDir;

    }

   

    public void setDestinationDirectory(String str) {

        destDir = str;

    }

   

    public void setDimension(com.sun.star.awt.Size size) {

        dimension = size;

    }

   

    public void setSourceDirectory(String str) {

        sourceDir = str;

    }

    ...

}    

For the component to run, the new interface class file must be accessible to the Java Virtual Machine. That is, it has to be in its CLASSPATH. All commonly used interfaces are contained in ridl.jar and unoil.jar that are always in the CLASSPATH because of the OpenOffice.org setup program.

The recommended method is to deliver the interface together with the component in the same jar file, or to have the interface in a separate jar or class file. In both cases, put the corresponding class with the interface into the CLASSPATH. This is achieved by editing the file java(.ini|rc) in <officepath>\user\config or through the options dialog. The java(.ini|rc) contains a SystemClasspath entry that you append the path pointing to the class or jar file. In the Options dialog, expand the OpenOffice.org node in the tree on the left-hand side and choose Security. One the right-hand side, there is a field User Classpath to add the jar or class file containing the interface.

Note graphics marks a special text section

It is also important that the binary type library of the new interfaces are provided together with the component, otherwise the component is not accessible from OpenOffice.org Basic. Basic uses the UNO core reflection service to get type information at runtime. The core reflection is based on the binary type library.

4.5.3    Providing a Single Factory Using Helper Method

The component must be able to create single factories for each service implementation it contains and return them in the static component operation __getServiceFactory(). The OpenOffice.org Java UNO environment provides a Java class com.sun.star.comp.loader.FactoryHelper that creates a default implementation of a single factory through its method getServiceFactory(). The following example could be written: (Components/Thumbs/org/openoffice/comp/test/ImageShrink.java)

package org.openoffice.comp.test;

import com.sun.star.lang.XSingleServiceFactory;

import com.sun.star.lang.XMultiServiceFactory;

import com.sun.star.registry.XRegistryKey;

import com.sun.star.comp.loader.FactoryHelper;

public class ImageShrink ... {

  ...

    // static __getServiceFactory() implementation

    // static member __serviceName was introduced above for XServiceInfo implementation    

    public static XSingleServiceFactory __getServiceFactory(String implName,

            XMultiServiceFactory multiFactory,

            com.sun.star.registry.XRegistryKey regKey) {

               

        com.sun.star.lang.XSingleServiceFactory xSingleServiceFactory = null;

        if (implName.equals( ImageShrink.class.getName()) )

            xSingleServiceFactory = FactoryHelper.getServiceFactory(ImageShrink.class,

                  ImageShrink.__serviceName, multiFactory, regKey);

        return xSingleServiceFactory;

    }

  ...

}

The FactoryHelper is contained in the jurt jar file. The getServiceFactory() method takes as a first argument a Class object. When createInstance() is called on the default factory, it creates an instance of that Class using newInstance() on it and retrieves the implementation name through getName(). The second argument is the service name. The multiFactory and regKey arguments were received in __getServiceFactory() and are passed to the FactoryHelper.

Note graphics marks a special text section

In this case, the implementation name, which the default factory finds through Class.getName() is org.openoffice.comp.test.ImageShrink and the service name is org.openoffice.test.ImageShrink. The implementation name and the service name are used for the separate XServiceInfo implementation within the default factory. Not only do you support the XServiceInfo interface in your service implementation, but the single factory must implement this interface as well.

The default factory created by the FactoryHelper expects a public constructor in the implementation class of the service and calls it when it instantiates the service implementation. The constructor can be a default constructor, or it can take a com.sun.star.uno.XComponentContext or a com.sun.star.lang.XMultiServiceFactory as an argument. Refer to 4.5.7 Writing UNO Components - Simple Component in Java - Create Instance With Arguments for other arguments that are possible.

Java components are housed in jar files. When a component has been registered, the registry contains the name of the jar file, so that the service manager can find it. However, because a jar file can contain several class files, the service manager must be told which one contains the __getServiceFactory() method. That information has to be put into the jar's Manifest file, for example:

RegistrationClassName: org.openoffice.comp.test.ImageShrink

4.5.4    Write Registration Info Using Helper Method

UNO components have to be registered with the registry database of a service manager. In an office installation, this is the file applicat.rdb for all predefined services. A service manager can use this database to find the implementations for a service. For instance, if an instance of your component is created using the following call.

Object imageShrink = xRemoteServiceManager.createInstance("org.openoffice.test.ImageShrink");

Using the given service or implementation name, the service manager looks up the location of the corresponding jar file in the registry and instantiates the component.

Note graphics marks a special text section

If you want to use the service manager of the Java UNO runtime, com.sun.star.comp.servicemanager.ServiceManager (jurt.jar), to instantiate your service implementation, then you would have to create the service manager and add the factory for “org.openoffice.test.ImageShrink” programmatically, because the Java service manager does not use the registry.

Alternatively, you can use com.sun.star.comp.helper.RegistryServiceFactory from juh.jar which is registry-based. Its drawback is that it delegates to a C++ implementation of the service manager through the java-bridge.

During the registration, a component writes the necessary information into the registry. The process to write the information is triggered externally when a client calls the __writeRegistryServiceInfo() method at the component.

public static boolean __writeRegistryServiceInfo(XRegistryKey regKey)

The caller passes an com.sun.star.registry.XRegistryKey interface that is used by the method to write the registry entries. Again, the FactoryHelper class offers a way to implement the method: (Components/Thumbs/org/openoffice/comp/test/ImageShrink.java)

    ...

    // static __writeRegistryServiceInfo implementation

    public static boolean __writeRegistryServiceInfo(XRegistryKey regKey) {

        return FactoryHelper.writeRegistryServiceInfo( ImageShrink.class.getName(),

            __serviceName, regKey);

    }    

The writeRegistryServiceInfo method takes three arguments:

Use tools, such as regcomp or the Java application com.sun.star.tools.uno.RegComp to register a component. These tools take the path to the jar file containing the component as an argument. Since the jar can contain several classes, the class that implements the __writeRegistryServiceInfo() method must be pointed out by means of the manifest. Again, the RegistrationClassName entry determines the correct class. For example:

RegistrationClassName: org.openoffice.comp.test.ImageShrink

The above entry is also necessary to locate the class that provides __getServiceFactory(), therefore the functions __writeRegistryServiceInfo() and __getServiceFactory() have to be in the same class.

4.5.5    Implementing without Helpers

XInterface

As soon as the component implements any UNO interface, com.sun.star.uno.XInterface is included automatically. The Java interface definition generated by javamaker for com.sun.star.uno.XInterface contains a TypeInfo member used by Java UNO internally to store certain IDL type information (Refer to 3.4.1 Professional UNO - UNO Language Bindings - Java Language Binding):

// source file com/sun/star/uno/XInterface.java generated by javamaker

package com.sun.star.uno;

public interface XInterface

{

    // static Member

    public static final com.sun.star.lib.uno.typeinfo.TypeInfo UNOTYPEINFO[] = null;

}

Note that XInterface does not have any methods, in contrast to its IDL description. That means, if implements com.sun.star.uno.XInterface is added to a class definition, there is nothing to implement.

The method queryInterface() is unnecessary in a service implementation, because the Java UNO runtime environment obtains interface references without being helped by the components. Within Java, the method UnoRuntime.queryInterface() is used to obtain interfaces instead of calling com.sun.star.uno.XInterface:queryInterface(), and the Java UNO language binding hands out interfaces for services to other processes on its own as well.

The methods acquire() and release() are used for reference counting and control the lifetime of an object, because the Java garbage collector does this, there is no reference counting in Java components.

XTypeProvider

Helper classes with default com.sun.star.lang.XTypeProvider implementations are still under development for Java. Meanwhile, every Java UNO object implementation can implement the XTypeProvider interface as shown in the following code. In your implementation, adjust getTypes(): (Components/Thumbs/org/openoffice/comp/test/ImageShrink.java)

    ...

    // XTypeProvider implementation

    // maintain a static implementation id for all instances of ImageShrink

    // initialized by the first call to getImplementationId()

    protected static byte[] _implementationId;

    public com.sun.star.uno.Type[] getTypes() {

        com.sun.star.uno.Type[] retValue = new com.sun.star.uno.Type[4];

        // instantiate Type instances for each interface you support and add them to Type[] array

        // this object implements XServiceInfo, XTypeProvider and XImageShrink

        retValue[0]= new com.sun.star.uno.Type( com.sun.star.lang.XServiceInfo.class);

        retValue[1]= new com.sun.star.uno.Type( com.sun.star.lang.XTypeProvider.class);

        retValue[3]= new com.sun.star.uno.Type( com.sun.star.document.XFilter);

        retValue[2]= new com.sun.star.uno.Type( org.openoffice.test.XImageShrink.class);

        // inherited interfaces, like XInterface, are recognized implicitely

        return retValue;

    }

    synchronized public byte[] getImplementationId() {

        if (_implementationId == null) {

            _implementationId= new byte[16];

            int hash = hashCode();  // hashCode of this object

            _implementationId[0] = (byte)(hash & 0xff);

            _implementationId[1] = (byte)((hash >>> 8) & 0xff);

            _implementationId[2] = (byte)((hash >>> 16) & 0xff);

            _implementationId[3] = (byte)((hash >>>24) & 0xff);

        }

        return _implementationId;

    }

    ...

The suggested implementation of the getImplementationId() method is not optimal, it uses the hashCode() of the first instance that initializes the static field. The future UNO helper class will improve this.

XComponent

XComponent is an optional interface that is useful when other objects hold references to the  component. The notification mechanism of XComponent enables listener objects to learn when the component stops to provide its services, so that the objects drop their references to the component. This enables the component to delete itself when its reference count drops to zero. From section 4.4 Writing UNO Components - Core Interfaces to Implement, there must be three things done when dispose() is called at an XComponent:

In Java, the object cannot be deleted, but the garbage collector will do this. It is sufficient to release all references that are currently being held to break the cyclic reference, and to call disposing() on all com.sun.star.lang.XEventListeners.

The registration and removal of listener interfaces is a standard procedure in Java. Some IDEs even create the necessary methods automatically. The following example could be written: (Components/Thumbs/org/openoffice/comp/test/ImageShrink.java)

    ...

    //XComponent implementation

    // hold a Vector of eventListeners in the class

    private transient Vector eventListeners;

    void dispose {

        fireDisposing(new com.sun.star.lang.EventObject(this))

        releaseReferences();

    }

    public synchronized void addEventListener(XEventListener listener) {

   

        if ( eventListeners == 0 )

            eventListeners = new Vector(2);

        if ( !eventListeners.contains(listener) )

            eventListeners.addElement(listener);

    }

    public synchronized void removeEventListener(XEventListener listener) {

        if ( eventListeners != 0 )

            eventListeners.removeElement(listener);

    }

    protected void fireDisposing(com.sun.star.lang.EventObject e) {

        if (eventListeners != null) {

            Vector listeners = eventListeners ;

            int count = listeners.size();

            for (int i = 0; i < count; i++) {

                ((XEventListener) listeners.elementAt(i)).disposing(e);

            }

        }

    }

    protected void releaseReferences() {

        xComponentContext = null;

        // ...

    }

    ...

4.5.6    Storing the Service Manager for Further Use

A component usually runs in the office process. There is no need to create an interprocess channel explicitly. A component does not have to create a service manager, because it is provided to the single factory of an implementation by the service manager during a call to createInstance() or createInstanceWithContext(). The single factory receives an XComponentContext or an XMultiServiceFactory, and passes it to the corresponding constructor of the service implementation. From the component context, the implementation gets the service manager using getServiceManager() at the com.sun.star.uno.XComponentContext interface.

4.5.7    Create Instance with Arguments

A factory can create an instance of components and pass additional arguments. To do that, a client calls the createInstanceWithArguments() function of the com.sun.star.lang.XSingleServiceFactory interface or the createInstanceWithArgumentsAndContext() of the com.sun.star.lang.XSingleComponentFactory interface.

//javamaker generated interface

//XSingleServiceFactory interface

public java.lang.Object createInstanceWithArguments(java.lang.Object[] aArguments)

                            throws com.sun.star.uno.Exception;

//XSingleComponentFactory

public java.lang.Object createInstanceWithArgumentsAndContext(java.lang.Object[] Arguments,

                                com.sun.star.uno.XComponentContext Context)

                            throws com.sun.star.uno.Exception;

Both functions take an array of values as an argument. A component implements the com.sun.star.lang.XInitialization interface to receive the values. A factory passes the array on to the single method initialize() supported by XInitialization.

public void initialize(java.lang.Object[] aArguments) throws com.sun.star.uno.Exception;

Alternatively, a component may also receive these arguments in its constructor. If a factory is written, determine exactly which arguments are provided by the factory when it instantiates the component. When using the FactoryHelper, implement the constructors with the following arguments:

First Argument

Second Argument

Third Argument

com.sun.star.uno.XComponentContext

com.sun.star.registry.XRegistryKey

java.lang.Object[]

com.sun.star.uno.XComponentContext

com.sun.star.registry.XRegistryKey

com.sun.star.uno.XComponentContext

java.lang.Object[]

com.sun.star.uno.XComponentContext

java.lang.Object[]

The FactoryHelper automatically passes the array of arguments it received from the createInstanceWithArguments[AndContext]() call to the appropriate constructor. Therefore, it is not always necessary to implement XInitialization to use arguments.

4.5.8    Possible Structures for Java Components

The implementation of a component depends on the needs of the implementer. The following examples show some possible ways to assemble a component. There can be one implemented object or several implemented objects per component file.

One Implementation per Component File

There are additional options if implementing one service per component file:

Implementation Class with Component Operations

An implementation class contains the static component operations. The following sample implements an interface com.sun.star.test.XSomething in an implementation class JavaComp.TestComponent:

// UNOIDL: interface example specification

module com {  module sun {  module star {  module test {  

 

interface XSomething: com::sun::star::uno::XInterface

{

    string methodOne([in]string val);

};

}; }; }; };

A component that implements only one service supporting XSomething can be assembled in one class as follows:

package JavaComp;

...

public class TestComponent implements XSomething, XTypeProvider, XServiceInfo {

 

    public static final String __serviceName="com.sun.star.test.JavaTestComponent";

    public static XSingleServiceFactory __getServiceFactory(String implName,

                              XMultiServiceFactory multiFactory, XRegistryKey regKey) {

    XSingleServiceFactory xSingleServiceFactory = null;

    if (implName.equals( TestComponent.class.getName()) )

        xSingleServiceFactory = FactoryHelper.getServiceFactory( TestComponent.class,

                                TestComponent.__serviceName, multiFactory, regKey);        

        return xSingleServiceFactory;

    }

   

    public static boolean __writeRegistryServiceInfo(XRegistryKey regKey){

        return FactoryHelper.writeRegistryServiceInfo( TestComponent.class.getName(),

                    TestComponent.__serviceName, regKey);

    }

    // XSomething

    string methodOne(String val) {

        return val;

    }

    //XTypeProvider

    public com.sun.star.uno.Type[] getTypes(  ) {

        ...

    }    

    // XTypeProvider

    public byte[] getImplementationId(  ) {

        ...

    }

    //XServiceInfo

    public String getImplementationName(  ) {

        ...

    }

    // XServiceInfo

    public boolean supportsService( /*IN*/String serviceName ) {

        ...

    }

    //XServiceInfo

    public String[] getSupportedServiceNames(  ) {

        ...

    }

}

The class implements the XSomething interface. The IDL description and documentation provides information about its functionality. The class also contains the functions for factory creation and registration, therefore the manifest entry must read as follows:

RegistrationClassName: JavaComp.TestComponent

Implementation Class with Component Operations and Inner Implementation Class

To implement the component as inner class of the one that provides the service factory through __getServiceFactory(), it must be a static inner class, otherwise the factory provided by the FactoryHelper cannot create the component. An example for an inner implementation class is located in the sample com.sun.star.comp.demo.DemoComponent.java provided with the SDK. The implementation of __getServiceFactory() and __writeRegistryServiceInfo() is omitted here, because they act the same as in the implementation class with component operations above.

package com.sun.star.comp.demo;

public class DemoComponent {

    ...

    // static inner class implements service com.sun.star.demo.DemoComponent

    static public class _Implementation implements XTypeProvider,

                            XServiceInfo, XInitialization, XWindowListener,

                            XActionListener, XTopWindowListener {

        static private final String __serviceName = "com.sun.star.demo.DemoComponent";

        private XMultiServiceFactory _xMultiServiceFactory;

        // Constructor

        public _Implementation(XMultiServiceFactory xMultiServiceFactory) {

        }

    }

    // static method to get a single factory creating the given service from the factory helper

    public static XSingleServiceFactory __getServiceFactory(String implName,

                                            XMultiServiceFactory multiFactory,

                                            XRegistryKey regKey) {

                ...

    }

       

    // static method to write the service information into the given registry key

    public static boolean __writeRegistryServiceInfo(XRegistryKey regKey) {

        ...

    }

}

The manifest entry for this implementation structure again has to point to the class with the static component operations:

RegistrationClassName: com.sun.star.comp.demo.DemoComponent

Multiple Implementations per Component File

To assemble several service implementations in one component file, implement each service in its own class and add a separate class containing the static component operations. The following code sample features two services: TestComponentA and TestComponentB implementing the interfaces XSomethingA and XSomethingB with a separate static class TestServiceProvider containing the component operations.

The following are the UNOIDL specifications for XSomethingA and XSomethingB:

module com {  module sun {  module star {  module test {

interface XSomethingA: com::sun::star::uno::XInterface

{

    string methodOne([in]string value);

};

}; }; }; };  

module com {  module sun {  module star {  module test {

interface XSomethingB: com::sun::star::uno::XInterface

{

    string methodTwo([in]string value);

};

}; }; }; };  

TestComponentA implements XSomethingA: (Components/JavaComponent/TestComponentA.java):

package JavaComp;

public class TestComponentA implements XTypeProvider, XServiceInfo, XSomethingA {

    static final String __serviceName= "JavaTestComponentA";

    static byte[] _implementationId;

       

    public TestComponentA() {

    }

    // XSomethingA

    public String methodOne(String val) {

        return val;

    }

    //XTypeProvider

    public com.sun.star.uno.Type[] getTypes(  ) {

        Type[] retValue= new Type[3];

        retValue[0]= new Type( XServiceInfo.class);

        retValue[1]= new Type( XTypeProvider.class);

        retValue[2]= new Type( XSomethingA.class);

        return retValue;

    }

    //XTypeProvider

    synchronized public byte[] getImplementationId(  ) {

        if (_implementationId == null) {

            _implementationId= new byte[16];

            int hash = hashCode();

            _implementationId[0] = (byte)(hash & 0xff);

            _implementationId[1] = (byte)((hash >>> 8) & 0xff);

            _implementationId[2] = (byte)((hash >>> 16) & 0xff);

            _implementationId[3] = (byte)((hash >>>24) & 0xff);

        }

        return _implementationId;

    }

    //XServiceInfo

    public String getImplementationName(  ) {

        return getClass().getName();

    }

    // XServiceInfo

    public boolean supportsService( /*IN*/String serviceName ) {

        if ( serviceName.equals( __serviceName))        

            return true;

        return false;

    }

    //XServiceInfo

    public String[] getSupportedServiceNames(  ) {

        String[] retValue= new String[0];

        retValue[0]= __serviceName;

        return retValue;

    }

}

TestComponentB implements XSomethingB. Note that it receives the component context and initialization arguments in its constructor. (Components/JavaComponent/TestComponentB.java)

package JavaComp;

public class TestComponentB implements XTypeProvider, XServiceInfo, XSomethingB {

    static final String __serviceName= "JavaTestComponentB";

    static byte[] _implementationId;

    private XComponentContext context;

    private Object[] args;

    public TestComponentB(XComponentContext context, Object[] args) {

        this.context= context;  

        this.args= args;

    }

       

    // XSomethingB

    public String methodTwo(String val) {

        if (args.length > 0 && args[0] instanceof String )

            return (String) args[0];

        return val;

    }

    //XTypeProvider

    public com.sun.star.uno.Type[] getTypes(  ) {

        Type[] retValue= new Type[3];

        retValue[0]= new Type( XServiceInfo.class);

        retValue[1]= new Type( XTypeProvider.class);

        retValue[2]= new Type( XSomethingB.class);

        return retValue;

    }

 

    //XTypeProvider

    synchronized public byte[] getImplementationId(  ) {

        if (_implementationId == null) {

            _implementationId= new byte[16];

            int hash = hashCode();

            _implementationId[0] = (byte)(hash & 0xff);

            _implementationId[1] = (byte)((hash >>> 8) & 0xff);

            _implementationId[2] = (byte)((hash >>> 16) & 0xff);

            _implementationId[3] = (byte)((hash >>>24) & 0xff);

        }

        return _implementationId;

    }

    //XServiceInfo

    public String getImplementationName(  ) {

        return getClass().getName();

    }

    // XServiceInfo

    public boolean supportsService( /*IN*/String serviceName ) {

        if ( serviceName.equals( __serviceName))        

            return true;

        return false;

    }

    //XServiceInfo

    public String[] getSupportedServiceNames(  ) {

        String[] retValue= new String[0];

        retValue[0]= __serviceName;

        return retValue;

    }

}

TestServiceProvider implements __getServiceFactory() and __writeRegistryServiceInfo(): (Components/JavaComponent/TestServiceProvider.java)

package JavaComp;

...

public class TestServiceProvider

{

    public static XSingleServiceFactory __getServiceFactory(String implName,

                                            XMultiServiceFactory multiFactory,

                                            XRegistryKey regKey) {

        XSingleServiceFactory xSingleServiceFactory = null;

        if (implName.equals( TestComponentA.class.getName()) )

            xSingleServiceFactory = FactoryHelper.getServiceFactory( TestComponentA.class,

                                        TestComponentA.__serviceName, multiFactory, regKey);        

        else if (implName.equals(TestComponentB.class.getName()))

            xSingleServiceFactory= FactoryHelper.getServiceFactory( TestComponentB.class,

                                        TestComponentB.__serviceName, multiFactory, regKey);

        return xSingleServiceFactory;

    }

    public static boolean __writeRegistryServiceInfo(XRegistryKey regKey){

        boolean bregA= FactoryHelper.writeRegistryServiceInfo( TestComponentA.class.getName(),

                            TestComponentA.__serviceName, regKey);

        boolean bregB= FactoryHelper.writeRegistryServiceInfo( TestComponentB.class.getName(),

                            TestComponentB.__serviceName, regKey);

        return bregA && bregB;

    }    

}

The corresponding manifest entry must point to the static class with the component operations, in this case JavaComp.TestServiceProvider:

RegistrationClassName: JavaComp.TestServiceProvider

4.5.9    Running and Debugging Java Components

Registration

The service manager with a registry database containing information about the location of the component file and the types used must be provided to test the component with the office. There are several ways to accomplish the registration. The following is a possibility.

A .rdb file is created with all the necessary information and the service manager is told to use it in addition to the standard applicat.rdb. The advantage of proceeding this way is that the applicat.rdb does not become cluttered with the production office installation with test registrations and abandoned type information. Follow the steps below:

Note, it errors are encountered, refer to the troubleshooting section at the end of this chapter.

Register Component File

This step creates a registry file that contains the location of the component file and all the necessary type information. To register, place a few files to the proper locations:

On the command prompt, change to <OfficePath>/program, then run regcomp with the following options. Line breaks were applied to improve readability, but the command must be entered in a single line:

$ regcomp -register -r <your_registry>.rdb
                   -br applicat.rdb

                    -l com.sun.star.loader.Java2

                    -c file:///<OfficePath>/program/classes/<your_component>.jar

For the org.openoffice.test.ImageShrink service whose type description was merged into thumbs.rdb , which is implemented in thumbs.jar, the corresponding command would be:

$ regcomp -register -r thumbs.rdb

                    -br applicat.rdb

                    -l com.sun.star.loader.Java2

                    -c file:///i:/StarOffice6.0/program/classes/thumbs.jar

Instead of regcomp, there is also a Java tool to register components, however, it can only write to the same registry it reads from. It cannot be used to create a separate registry database. For details, see the section 4.9 Writing UNO Components - Deployment Options for Components.

Make Registration available to OpenOffice.org

OpenOffice.org must be told to use the registry. Close all OpenOffice.org parts, including the Quickstarter that runs in the Windows task bar. Edit the file uno(.ini|rc) in <OfficePath>/program as follows:

[Bootstrap]
UNO_TYPES=$SYSBINDIR/applicat.rdb $SYSBINDIR/<your_registry>.rdb
UNO_SERVICES=$SYSBINDIR/applicat.rdb $SYSBINDIR/<your_registry>.rdb

For details about the syntax of uno(.ini|rc) and alternative registration procedures, refer to the section 4.9 Writing UNO Components - Deployment Options for Components. If OpenOffice.org is restarted, the component should be available.

Test the Registration

A short OpenOffice.org Basic program indicates if the program runs went smoothly, by selecting ToolsMacro and entering a new macro name on the left, such as TestImageShrink and click New to create a new procedure. In the procedure, enter the appropriate code of the component. The test routine for ImageShrink would be:

Sub TestImageShrink

    oTestComp = createUnoService("org.openoffice.test.ImageShrink")

    MsgBox oTestComp.dbg_methods

    MsgBox oTestComp.dbg_properties

    MsgBox oTestComp.dbg_supportedInterfaces

end sub

The result should be three dialogs showing the methods, properties and interfaces supported by the implementation. Note that the interface attributes do not appear as get/set methods, but as properties in Basic. If the dialogs do not show what is expected, refer to the section 4.5.9 Writing UNO Components - Simple Component in Java - Testing and Debugging Java Components - Troubleshooting.

Debugging

To increase turnaround cycles and source level debugging, configure the IDE to use GNU makefiles for code generation and prepare OpenOffice.org for Java debugging. If NetBeans are used, the following steps are necessary:

Support for GNU make

A NetBeans extension, available on makefile.netbeans.org, that adds basic support for GNU makefiles. When it is enabled, edit the makefile in the IDE and use the makefile to build. To install and enable this module, select Tools – Setup Wizard and click Next to go to the Module installation page. Find the module Makefiles and change the corresponding entry to True in the Enabled column. Finish using the setup wizard. If the module is not available in the installation, use Tools – Update Center to get the module from www.netbeans.org. A new entry, Makefile Support, appears in the online help when Help – Contents is selected. Makefile Support provides further configuration options. The settings Run a Makefile and Test a Makefile can be found in ToolsOptionsUncategorizedCompiler Types and – Execution Types.

Put the makefile into the project source folder that was mounted when the project was created. To build the project using the makefile, highlight the makefile in the Explorer and press F11.

Documentation for GNU make command-line options and syntax are available at www.gnu.org. The sample Thumbs in the samples folder along with this manual contains a makefile that with a few adjustments is useful for Java components.

Component Debugging

If NetBeans or Forte for Java is used, the Java Virtual Machine (JVM) that is launched by OpenOffice.org can be attached. Configure the JVM used by OpenOffice.org to listen for debugger connections. First close any open OpenOffice.org windows including the Quickstarter, then edit the section [JAVA] of the file java(.ini|rc) in <OfficePath>/user/config by adding:

-Xdebug

-Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n

The last line causes the JVM to listen for a debugger on port 8000. The JVM starts listening as soon as it runs and does not wait until a debugger connects to the JVM. Launch the office and instantiate the Java component, so that the office invokes the JVM in listening mode.

Once a Java component is instantiated, the JVM keeps listening even if the component goes out of scope. Open the appropriate source file in the NetBeans editor and set breakpoints as needed. Choose Debug - Attach, select Java Platform Debugger Architecture (JPDA) as debugger type and SocketAttach (Attaches by socket to other VMs) as the connector. The Host should be localhost and the Port must be 8000. Click OK to connect the Java Debugger to the JVM the office has started previously step.

Once the debugger connects to the running JVM, NetBeans switches to debug mode, the output windows shows a message that a connection on port 8000 is established and threads are visible, as if the debugging was local. If necessary, start your component once again. As soon as the component reaches a breakpoint in the source code, the source editor window opens with the breakpoint highlighted by a green arrow.

The Java Environment in OpenOffice.org

When UNO components written in Java are to be used within the office, it has to be configured appropriately. During OpenOffice.org installation, the Java setup is run. It gives the user the opportunity to choose a Java installation. The setup only offers Java versions which are certain to work with the office. The user can also choose to have an appropriate Java Runtime Environment installed. When the office has been installed, a user can still change the used Java installation by running the jvmsetup program that is located in the program directory of the installation directory. For example:

d:\program files\<office-installation-dir>\program\jvmsetup.exe

When the office starts Java, it uses configuration data that are kept in the java(.ini|rc) file, as well as in dedicated configuration files. The java(.ini|rc) is located in the <officepath>\user\config directory. A client can use that file to pass additional properties to the Java Virtual Machine, which are then available as system properties. For example, to pass the property MyAge, invoke Java like this:

java -DMyAge=30 RunClass

If you want to have that system property accessible by your Java component you can put that property into java(.ini|rc) within the [Java] section. For example:

[Java]
Home=d:\development\jdk1.3.1

VMType=jdk
Version=1.3.1
RuntimeLib=d:\development\jdk1.3.1\jre\bin\hotspot\jvm.dll
SystemClasspath=d:\development\jdk1.3.1\jre\lib\rt.jar; ...
Java=1
JavaScript=1
Applets=1
MyAge=27  

To debug a Java component, it is necessary to start the JVM with additional parameters. The parameters can be put in the java.ini the same way as they would appear on the command-line. For example , add those lines to the [Java] section:

-Xdebug
-Xrunjdwp:transport=dt_socket,server=y,address=8000

More about debugging can be found in the JDK documentation and in the OpenOffice.org Software Development Kit.

Java components are also affected by the following configuration settings. They can be changed in the Tools - Options dialog. In the dialog, expand the OpenOffice.org node on the left-hand side and choose Security. This brings up a new pane on the right-hand side that allows Java specific settings:

Java Setting

Description

Enable

If checked, Java is used with the office. This affects Java components, as well as applets.

Security checks

If checked, the security manager restricts resource access of applets.

Net access

Determines where an applet can connect.

ClassPath

Additional jar files and directories where the JVM should search for classes. Also known as user classpath.

Applets

If checked, applets are executed.

Troubleshooting

If the component encounters problems, review the following checklist to check if the component is configured correctly.

Check Registry Keys

To check if the registry database is correctly set up, run regview against the three keys that make up a registration in the /UCR, /SERVICES and /IMPLEMENTATIONS branch of a registry database. The following examples show how to read the appropriate keys and how a proper configuration should look. In our example, service ImageShrink, and the key /UCR/org/openoffice/test/XImageShrink contain the type information specified in UNOIDL:

# dump XImageShrink type information

$ regview thumbs.rdb /UCR/org/openoffice/test/XImageShrink

Registry "file:///X:/office60eng/program/thumbs.rdb":

/UCR/org/openoffice/test/XImageShrink

 Value: Type = RG_VALUETYPE_BINARY

        Size = 364

        Data = minor version: 0

              major version: 1

              type: 'interface'

              uik: { 0x00000000-0x0000-0x0000-0x00000000-0x00000000 }

              name: 'org/openoffice/test/XImageShrink'

              super name: 'com/sun/star/uno/XInterface'

              Doku: ""

              IDL source file: "X:\SO\sdk\examples\java\Thumbs\org\openoffice\test\XImageShrink.idl"

              number of fields: 3

              field #0:

                name='SourceDirectory'

                type='string'

                access=READWRITE

                 Doku: ""

                IDL source file: ""

              field #1:

                name='DestinationDirectory'

                type='string'

                access=READWRITE

                 Doku: ""

                IDL source file: ""

              field #2:

                name='Dimension'

                type='com/sun/star/awt/Size'

                access=READWRITE

                 Doku: ""

                IDL source file: ""

              number of methods: 0

              number of references: 0

The /SERVICES/org.openoffice.test.ImageShrink key must point to the implementation name org.openoffice. comp .test.ImageShrink that was chosen for this service:

# dump service name registration

$ regview thumbs.rdb /SERVICES/org.openoffice.test.ImageShrink

Registry "file:///X:/office60eng/program/thumbs.rdb":

/SERVICES/org.openoffice.test.ImageShrink

 Value: Type = RG_VALUETYPE_STRINGLIST

        Size = 45

        Len  = 1

        Data = 0 = "org.openoffice.comp.test.ImageShrink"

Finally, the /IMPLEMENTATIONS/org.openoffice.comp.test.ImageShrink key must contain the loader and the location of the component jar:

# dump implementation name registration

$ regview thumbs.rdb /IMPLEMENTATIONS/org.openoffice.comp.test.ImageShrink

Registry "file:///X:/office60eng/program/thumbs.rdb":

/IMPLEMENTATIONS/org.openoffice.comp.test.ImageShrink

 / UNO

   / ACTIVATOR

     Value: Type = RG_VALUETYPE_STRING

            Size = 26

            Data = "com.sun.star.loader.Java2"

   / SERVICES

     / org.openoffice.test.ImageShrink

   / LOCATION

     Value: Type = RG_VALUETYPE_STRING

            Size = 50

            Data = "file:///X:/office60eng/program/classes/thumbs.jar"

If the UCR key is missing, the problem is with regmerge. The most probable cause are missing .urd files. Be careful when writing the makefile. If .urd files are missing when regmerge is launched by the makefile, regmerge continues and creates a barebone .rdb file, sometimes without any type info.

If regview can not find the /SERVICES and /IMPLEMENTATIONS keys or they have the wrong content, the problem occurred when regcomp was run. This can be caused by wrong path names in the regcomp arguments.

Also, a wrong SystemClasspath setup in java(.ini|rc) could be the cause of regcomp error messages about missing classes. Check what the SystemClasspath entry in java(.ini|rc) specifies for the Java UNO runtime jars.

Ensure that regcomp is being run from the current directory when registering Java components. In addition, ensure <OfficePath>/program is the current folder when regcomp is run. Verify that regcomp is in the current folder.

Check the Java VM settings

Whenever the VM service is instantiated by OpenOffice.org, it uses the Java configuration settings in OpenOffice.org. This happens during the registration of Java components, therefore make sure that Java is enabled. Choose Tools-Options in OpenOffice.org, so that the dialog appears. Expand the OpenOffice.org node and select Security. Select the Enable checkbox in the Java section and click OK.

Check the Manifest

Make sure the manifest file contains the correct entry for the registration class name. The file must contain the following line:

RegistrationClassName: <full name of package and class>

The registration class name must be the one that implements the __writeRegistryServiceInfo() and __getServiceFactory() methods. The RegistrationClassName to be entered in the manifest for our example is org.openoffice.comp.test.ImageShrink.

Adjust CLASSPATH for Additional Classes

OpenOffice.org maintains its own system classpath and a user classpath when it starts the Java VM for Java components. The jar file that contains the service implementation is not required in the system or user classpath. If other jar files or classes are depended on and they are not part of the Java UNO runtime jars, they must be in the classpath. To correct the problem, edit the java(.ini|rc) file in <OfficePath>/user/config and add the jars or directories to the SystemClasspath entry or use Tools – Options – OpenOffice.org - Security to add them to the user classpath.

Disable Debug Options

If the debug options (-Xdebug, -Xrunjdwp) are in the java(.ini|rc) file, disable them by putting semicolons at the beginning of the respective lines. The regcomp may hang, because the JVM is waiting for a debugger to be attached.

4.6    C++ Component

In this section, a sample component containing two service implementations with helpers and without helpers implemented are presented. The complete source code and the gnu makefile are in samples/simple_cpp_component.

The first step for the C++ component is to define a language-independent interface, so that the UNO object can communicate with others. The IDL specification for the component defines one interface my_module.XSomething and two services implementing this interface. In addition, the second service called my_module.MyService2 implements the com.sun.star.lang.XInitialization interface, so that MyService2 can be instantiated with arguments passed to it during runtime.

#include <com/sun/star/uno/XInterface.idl>

#include <com/sun/star/lang/XInitialization.idl>

module my_module

{

interface XSomething : com::sun::star::uno::XInterface

{

    string methodOne( [in] string val );

};

service MyService1

{

    interface XSomething;

};

service MyService2

{

    interface XSomething;

    interface com::sun::star::lang::XInitialization;

};

};

This IDL is compiled to produce a binary type library file (.urd file), by executing the following commands. The types are compiled and merged into a registry simple_component.rdb, that will be linked into the OpenOffice.org installation later.

$ idlc -I<SDK>/idl some.idl
$ regmerge simple_component.rdb /UCR some.urd

The cppumaker tool must be used to map IDL to C++:

$ cppumaker -BUCR -Tmy_module.XSomething <SDK>/bin/applicat.rdb simple_component_rdb

For each given type, a pair of header files is generated, a .hdl and a .hpp file. To avoid conflicts, all C++ declarations of the type are in the .hdl and all definitions, such as constructors, are in the .hpp file. The .hpp is the one to include for any type used in C++.

The next step is to implement the core interfaces, and the implementation of the component operations component_getFactory(), component_writeInfo() and component_getImplementationEnvironment()with or without helper methods.

4.6.1    Class Definition with Helper Template Classes

XInterface, XTypeProvider and XWeak

The SDK offers helpers for ease of developing. There are implementation helper template classes that deal with the implementation of com.sun.star.uno.XInterface and com.sun.star.lang.XTypeProvider, as well as com.sun.star.uno.XWeak. These classes let you focus on the interfaces you want to implement.

The implementation of my_module.MyService2 uses the ::cppu::WeakImplHelper3<> helper. The “3” stands for the number of interfaces to implement. The class declaration inherits from this template class which takes the interfaces to implement as template parameters. (Components/CppComponent/service2_impl.cxx)

#include <cppuhelper/implbase3.hxx> // "3" implementing three interfaces

#include <cppuhelper/factory.hxx>

#include <cppuhelper/implementationentry.hxx>

#include <com/sun/star/lang/XServiceInfo.hpp>

#include <com/sun/star/lang/XInitialization.hpp>

#include <com/sun/star/lang/IllegalArgumentException.hpp>

#include <my_module/XSomething.hpp>

using namespace ::rtl; // for OUString

using namespace ::com::sun::star; // for sdk interfaces

using namespace ::com::sun::star::uno; // for basic types

namespace my_sc_impl {

class MyService2Impl : public ::cppu::WeakImplHelper3< ::my_module::XSomething,

                                                       lang::XServiceInfo,

                                                       lang::XInitialization >

{

    ...

};

}

The next section focusses on coding com.sun.star.lang.XServiceInfo, com.sun.star.lang.XInitialization and the sample interface my_module.XSomething.

The cppuhelper shared library provides additional implementation helper classes, for example, supporting com.sun.star.lang.XComponent. Browse the ::cppu namespace in the C++ reference of the SDK or on udk.openoffice.org.

XServiceInfo

An UNO service implementation supports com.sun.star.lang.XServiceInfo providing information about its implementation name and supported services. The implementation name is a unique name referencing the specific implementation. In this case, my_module.my_sc_impl.MyService1 and my_module.my_sc_impl.MyService2 respectively. The implementation name is used later when registering the implementation into the simple_component.rdb registry used for OpenOffice.org. It links a service name entry to one implementation, because there may be more than one implementation. Multiple implementations of the same service may have different characteristics, such as runtime behavior and memory footprint.

Our service instance has to support the com.sun.star.lang.XServiceInfo interface. This interface has three methods, and can be coded for one supported service as follows: (Components/CppComponent/service2_impl.cxx)

// XServiceInfo implementation

OUString MyService2Impl::getImplementationName()

    throw (RuntimeException)

{

    // unique implementation name

    return OUString( RTL_CONSTASCII_USTRINGPARAM("my_module.my_sc_impl.MyService2") );

}

sal_Bool MyService2Impl::supportsService( OUString const & serviceName )

    throw (RuntimeException)

{

    // this object only supports one service, so the test is simple

    return serviceName.equalsAsciiL( RTL_CONSTASCII_STRINGPARAM("my_module.MyService2") );

}

Sequence< OUString > MyService2Impl::getSupportedServiceNames()

    throw (RuntimeException)

{

    return getSupportedServiceNames_MyService2Impl();

}

4.6.2    Implementing your own Interfaces

For the my_module.XSomething interface, add a string to be returned that informs the caller when methodOne() was called successfully . (Components/CppComponent/service2_impl.cxx)

OUString MyService2Impl::methodOne( OUString const & str )

    throw (RuntimeException)

{

    return OUString( RTL_CONSTASCII_USTRINGPARAM(

        "called methodOne() of MyService2 implementation: ") ) + str;

}

4.6.3    Providing a Single Factory Using a Helper Method

C++ component libraries must export an external "C" function called component_getFactory() that supplies a factory object for the given implementation. Use ::cppu::component_getFactoryHelper() to create this function. The declarations for it are included through cppuhelper/implementationentry.hxx.

The component_getFactory() method appears at the end of the following listing. This method assumes that the component includes a static ::cppu::ImplementationEntry array s_component_entries[], which contains a number of function pointers. The listing shows how to write the component, so that the function pointers for all services of a multi-service component are correctly initialized. (Components/CppComponent/service2_impl.cxx)

#include <cppuhelper/implbase3.hxx> // "3" implementing three interfaces

#include <cppuhelper/factory.hxx>

#include <cppuhelper/implementationentry.hxx>

#include <com/sun/star/lang/XServiceInfo.hpp>

#include <com/sun/star/lang/XInitialization.hpp>

#include <com/sun/star/lang/IllegalArgumentException.hpp>

#include <my_module/XSomething.hpp>

using namespace ::rtl; // for OUString

using namespace ::com::sun::star; // for sdk interfaces

using namespace ::com::sun::star::uno; // for basic types

namespace my_sc_impl

{

class MyService2Impl : public ::cppu::WeakImplHelper3<

      ::my_module::XSomething, lang::XServiceInfo, lang::XInitialization >

{

    OUString m_arg;

public:

    // focus on three given interfaces,

    // no need to implement XInterface, XTypeProvider, XWeak

   

    // XInitialization will be called upon createInstanceWithArguments[AndContext]()

    virtual void SAL_CALL initialize( Sequence< Any > const & args )

        throw (Exception);

    // XSomething

    virtual OUString SAL_CALL methodOne( OUString const & str )

        throw (RuntimeException);

    // XServiceInfo

    virtual OUString SAL_CALL getImplementationName()

        throw (RuntimeException);

    virtual sal_Bool SAL_CALL supportsService( OUString const & serviceName )

        throw (RuntimeException);

    virtual Sequence< OUString > SAL_CALL getSupportedServiceNames()

        throw (RuntimeException);

};

// Implementation of XSomething, XServiceInfo and XInitilization omitted here:

...

// component operations from service1_impl.cxx

extern Sequence< OUString > SAL_CALL  getSupportedServiceNames_MyService1Impl();

extern OUString SAL_CALL getImplementationName_MyService1Impl();

extern Reference< XInterface > SAL_CALL create_MyService1Impl(

                                        Reference< XComponentContext > const & xContext )

                                            SAL_THROW( () );

// component operations for MyService2Impl

static Sequence< OUString > getSupportedServiceNames_MyService2Impl()

{

    static Sequence < OUString > *pNames = 0;

    if( ! pNames )

    {

        if( !pNames )

        {

            static Sequence< OUString > seqNames(1);

            seqNames.getArray()[0] = OUString(RTL_CONSTASCII_USTRINGPARAM("my_module.MyService2"));

            pNames = &seqNames;

        }

    }

    return *pNames;

}

static OUString getImplementationName_MyService2Impl()

{

    static OUString *pImplName = 0;

    if( ! pImplName )

    {

        if( ! pImplName )

        {

            static OUString implName(

                RTL_CONSTASCII_USTRINGPARAM("my_module.my_sc_implementation.MyService2") );

            pImplName = &implName;

        }

    }

    return *pImplName;

}

   

Reference< XInterface > SAL_CALL create_MyService2Impl(

    Reference< XComponentContext > const & xContext )

    SAL_THROW( () )

{

    return static_cast< lang::XTypeProvider * >( new MyService2Impl() );

}

/* shared lib exports implemented with helpers */

static struct ::cppu::ImplementationEntry s_component_entries [] =

{

    {

        create_MyService1Impl, getImplementationName_MyService1Impl,

        getSupportedServiceNames_MyService1Impl, ::cppu::createSingleComponentFactory,

        0, 0

    },

    {

        create_MyService2Impl, getImplementationName_MyService2Impl,

        getSupportedServiceNames_MyService2Impl, ::cppu::createSingleComponentFactory,

        0, 0

    },

    { 0, 0, 0, 0, 0, 0 }

};

}

extern "C"

{

void * SAL_CALL component_getFactory(

    sal_Char const * implName, lang::XMultiServiceFactory * xMgr,

    registry::XRegistryKey * xRegistry )

{

    return ::cppu::component_getFactoryHelper(

        implName, xMgr, xRegistry, ::my_sc_impl::s_component_entries );

}

//  getImplementationEnvironment and component_writeInfo are described later, we omit them here

...

}

The static variable s_component_entries defines a null-terminated array of entries concerning the service implementations of the shared library. A service implementation entry consists of function pointers for

The last two values are reserved for future use and therefore can be 0.

4.6.4    Write Registration Info Using Helper Method

Use ::cppu::component_writeInfoHelper() to implement component_writeInfo(): This function is called by regcomp during the registration process. [ScOURCE:Components/simple_cpp_component/service2_impl.cxx]

extern "C" sal_Bool SAL_CALL component_writeInfo(

    lang::XMultiServiceFactory * xMgr, registry::XRegistryKey * xRegistry )

{

    return ::cppu::component_writeInfoHelper(

        xMgr, xRegistry, ::my_sc_impl::s_component_entries );

}

Note that component_writeInfoHelper() uses the same array of ::cppu::ImplementationEntry structs as component_getFactory(),that is, s_component_entries.

4.6.5    Provide Implementation Environment

The function called component_getImplementationEnvironment() tells the shared library component loader which compiler was used to build the library. This information is required if different components have been compiled with different compilers. A specific C++-compiler is called an environment. If different compilers were used, the loader has to bridge interfaces from one compiler environment to another, building the infrastructure of communication between those objects. It is mandatory to have the appropriate C++ bridges installed into the UNO runtime. In most cases, the function mentioned above can be implemented this way: (Components/CppComponent/service2_impl.cxx)

extern "C" void SAL_CALL component_getImplementationEnvironment(

    sal_Char const ** ppEnvTypeName, uno_Environment ** ppEnv )

{

    *ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME;

}

The macro CPPU_CURRENT_LANGUAGE_BINDING_NAME is a C string defined by the compiling environment, if you use the SDK compiling environment. For example, when compiling with the Microsoft Visual C++ compiler, it defines to "msci", but when compiling with the GNU gcc 3, it defines to "gcc3".

4.6.6    Implementing without Helpers

In the following section, possible implementations without helpers are presented. This is useful if more interfaces are to be implemented than planned by the helper templates. The helper templates only allow up to ten interfaces. Also included in this section is how the core interfaces work.

XInterface Implementation

Object lifetime is controlled through the common base interface com.sun.star.uno.XInterface methods acquire() and release(). These are implemented using reference-counting, that is, upon each acquire(), the counter is incremented and upon each release(), it is decreased. On last decrement, the object dies. Programming in a thread-safe manner, the modification of this counter member variable is commonly performed by a pair of sal library functions called osl_incrementInterlockedcount() and osl_decrementInterlockedcount() (include osl/interlck.h). (Components/CppComponent/service1_impl.cxx)

Pay attention to the following important text section

Be aware of symbol conflicts when writing code. It is common practice to wrap code into a separate namespace, such as "my_sc_impl". The problem is that symbols may clash during runtime on Unix when your shared library is loaded.

namespace my_sc_impl

{

class MyService1Impl

    ...

{

    oslInterlockedCount m_refcount;

public:

    inline MyService1Impl() throw ()

        : m_refcount( 0 )

        {}

   

    // XInterface

    virtual Any SAL_CALL queryInterface( Type const & type )

        throw (RuntimeException);

    virtual void SAL_CALL acquire()

        throw ();

    virtual void SAL_CALL release()

        throw ();

    ...

};

void MyService1Impl::acquire()

    throw ()

{

    // thread-safe incrementation of reference count

    ::osl_incrementInterlockedCount( &m_refcount );

}

void MyService1Impl::release()

    throw ()

{

    // thread-safe decrementation of reference count

    if (0 == ::osl_decrementInterlockedCount( &m_refcount ))

    {

        delete this; // shutdown this object

    }

}

In the queryInterface() method, interface pointers have to be provided to the interfaces of the object. That means, cast this to the respective pure virtual C++ class generated by the cppumaker tool for the interfaces. All supported interfaces must be returned, including inherited interfaces like XInterface. (Components/CppComponent/service1_impl.cxx)

Any MyService1Impl::queryInterface( Type const & type )

    throw (RuntimeException)

{

    if (type.equals( ::getCppuType( (Reference< XInterface > const *)0 ) ))

    {

        // return XInterface interface (resolve ambiguity caused by multiple inheritance from

        // XInterface subclasses by casting to lang::XTypeProvider)

        Reference< XInterface > x( static_cast< lang::XTypeProvider * >( this ) );

        return makeAny( x );

    }

    if (type.equals( ::getCppuType( (Reference< lang::XTypeProvider > const *)0 ) ))

    {

        // return XInterface interface

        Reference< XInterface > x( static_cast< lang::XTypeProvider * >( this ) );

        return makeAny( x );

    }

    if (type.equals( ::getCppuType( (Reference< lang::XServiceInfo > const *)0 ) ))

    {

        // return XServiceInfo interface

        Reference< lang::XServiceInfo > x( static_cast< lang::XServiceInfo * >( this ) );

        return makeAny( x );

    }

    if (type.equals( ::getCppuType( (Reference< ::my_module::XSomething > const *)0 ) ))

    {

        // return sample interface

        Reference< ::my_module::XSomething > x( static_cast< ::my_module::XSomething * >( this ) );

        return makeAny( x );

    }

    // querying for unsupported type

    return Any();

}

XTypeProvider Implementation

When implementing the com.sun.star.lang.XTypeProvider interface, two methods have to be coded. The first one, getTypes() provides all implemented types of the implementation, excluding base types, such as com.sun.star.uno.XInterface. The second one, getImplementationId() provides a unique ID for this set of interfaces. A thread-safe implementation of the above mentioned looks like the following example: (Components/CppComponent/service1_impl.cxx)

Sequence< Type > MyService1Impl::getTypes()

    throw (RuntimeException)

{

    Sequence< Type > seq( 3 );

    seq[ 0 ] = ::getCppuType( (Reference< lang::XTypeProvider > const *)0 );

    seq[ 1 ] = ::getCppuType( (Reference< lang::XServiceInfo > const *)0 );

    seq[ 2 ] = ::getCppuType( (Reference< ::my_module::XSomething > const *)0 );

    return seq;

}

Sequence< sal_Int8 > MyService1Impl::getImplementationId()

    throw (RuntimeException)

{

    static Sequence< sal_Int8 > * s_pId = 0;

    if (! s_pId)

    {

        // create unique id

        Sequence< sal_Int8 > id( 16 );

                ::rtl_createUuid( (sal_uInt8 *)id.getArray(), 0, sal_True );

        // guard initialization with some mutex

        ::osl::MutexGuard guard( ::osl::Mutex::getGlobalMutex() );

        if (! s_pId)

        {

            static Sequence< sal_Int8 > s_id( id );

            s_pId = &s_id;

        }

    }

    return *s_pId;

}

Pay attention to the following important text section

Take a look at the thread-safe initialization of the implementation ID. A common pattern is to test a static pointer that is modified by one atom write. Using the same pattern, you can do a static initialization of the types sequence. This has been omitted for simplicity.
In general, do not acquire() mutexes when calling alien code if you do not know what the called code is doing. You never know what mutexes the alien code is acquiring which can lead to deadlocks. This is the reason, why the latter value (uuid) is created before the initialization mutex is acquired. After the mutex is successfully acquired, the value of s_pID is checked again and assigned if it has not been assigned before. This is the design pattern double check lock.

Providing a Single Factory

The function component_getFactory() provides a single object factory for the requested implementation, that is, it provides a factory that creates object instances of one of the service implementations. Using a helper from cppuhelper/factory.hxx, this is implemented quickly in the following code: (Components/CppComponent/service1_impl.cxx)

#include <cppuhelper/factory.hxx>

namespace my_sc_impl

{

...

static Reference< XInterface > SAL_CALL create_MyService1Impl(

    Reference< XComponentContext > const & xContext )

    SAL_THROW( () )

{

    return static_cast< lang::XTypeProvider * >( new MyService1Impl() );

}

static Reference< XInterface > SAL_CALL create_MyService2Impl(

    Reference< XComponentContext > const & xContext )

    SAL_THROW( () )

{

    return static_cast< lang::XTypeProvider * >( new MyService2Impl() );

}

}

extern "C" void * SAL_CALL component_getFactory(

    sal_Char const * implName, lang::XMultiServiceFactory * xMgr, void * )

{

    Reference< lang::XSingleComponentFactory > xFactory;

    if (0 == ::rtl_str_compare( implName, "my_module.my_sc_impl.MyService1" ))

    {

        // create component factory for MyService1 implementation

        OUString serviceName( RTL_CONSTASCII_USTRINGPARAM("my_module.MyService1") );

        xFactory = ::cppu::createSingleComponentFactory(

            ::my_sc_impl::create_MyService1Impl,

            OUString( RTL_CONSTASCII_USTRINGPARAM("my_module.my_sc_impl.MyService1") ),

            Sequence< OUString >( &serviceName, 1 ) );

    }

    else if (0 == ::rtl_str_compare( implName, "my_module.my_sc_impl.MyService2" ))

    {

        // create component factory for MyService12 implementation

        OUString serviceName( RTL_CONSTASCII_USTRINGPARAM("my_module.MyService2") );

        xFactory = ::cppu::createSingleComponentFactory(

            ::my_sc_impl::create_MyService2Impl,

            OUString( RTL_CONSTASCII_USTRINGPARAM("my_module.my_sc_impl.MyService2") ),

            Sequence< OUString >( &serviceName, 1 ) );

    }

    if (xFactory.is())

        xFactory->acquire();

    return xFactory.get(); // return acquired interface pointer or null

}

In the example above, note the function ::my_sc_impl::create_MyService1Impl() that is called by the factory object when it needs to instantiate the class. A component context com.sun.star.uno.XComponentContext is provided to the function, which may be passed to the constructor of MyService1Impl.

Write Registration Info

The function component_writeInfo() is called by the shared library component loader upon registering the component into a registry database file (.rdb). The component writes information about objects it can instantiate into the registry when it is called by regcomp. (Components/CppComponent/service1_impl.cxx)

extern "C" sal_Bool SAL_CALL component_writeInfo(

    lang::XMultiServiceFactory * xMgr, registry::XRegistryKey * xRegistry )

{

    if (xRegistry)

    {

        try

        {

            // implementation of MyService1A

            Reference< registry::XRegistryKey > xKey(

                xRegistry->createKey( OUString( RTL_CONSTASCII_USTRINGPARAM(

                    "my_module.my_sc_impl.MyService1/UNO/SERVICES") ) ) );

            // subkeys denote implemented services of implementation

            xKey->createKey( OUString( RTL_CONSTASCII_USTRINGPARAM(

                "my_module.MyService1") ) );

            // implementation of MyService1B

            xKey = xRegistry->createKey( OUString( RTL_CONSTASCII_USTRINGPARAM(

                "my_module.my_sc_impl.MyService2/UNO/SERVICES") ) );

            // subkeys denote implemented services of implementation

            xKey->createKey( OUString( RTL_CONSTASCII_USTRINGPARAM(

                "my_module.MyService2") ) );

            return sal_True; // success

        }

        catch (registry::InvalidRegistryException &)

        {

            // function fails if exception caught

        }

    }

    return sal_False;

}

4.6.7    Storing the Service Manager for Further Use

The single factories expect a static create_< ImplementationClass> () function. For instance, create_MyService1Impl()takes a reference to the component context and instantiates the implementation class using new ImplementationClass(). A constructor can be written for <ImplementationClass> that expects a reference to an com.sun.star.uno.XComponentContext and stores the reference in the instance for further use.

static Reference< XInterface > SAL_CALL create_MyService2Impl(

    Reference< XComponentContext > const & xContext )

    SAL_THROW( () )

{

    // passing the component context to the constructor of MyService2Impl

    return static_cast< lang::XTypeProvider * >( new MyService2Impl( xContext ) );

}

4.6.8    Create Instance with Arguments

If the service should be raised passing arguments through com.sun.star.lang.XMultiComponentFactory:createInstanceWithArgumentsAndContext() and com.sun.star.lang.XMultiServiceFactory:createInstanceWithArguments(), it has to implement the interface com.sun.star.lang.XInitialization. The second service my_module.MyService2 implements it, expecting a single string as an argument. (Components/CppComponent/service2_impl.cxx)

// XInitialization implementation

void MyService2Impl::initialize( Sequence< Any > const & args )

    throw (Exception)

{

    if (1 != args.getLength())

    {

        throw lang::IllegalArgumentException(

            OUString( RTL_CONSTASCII_USTRINGPARAM("give a string instanciating this component!") ),

            (::cppu::OWeakObject *)this, // resolve to XInterface reference

            0 ); // argument pos

    }

    if (! (args[ 0 ] >>= m_arg))

    {

        throw lang::IllegalArgumentException(

            OUString( RTL_CONSTASCII_USTRINGPARAM("no string given as argument!") ),

            (::cppu::OWeakObject *)this, // resolve to XInterface reference

            0 ); // argument pos

    }

}

4.6.9    Multiple Components in One Dynamic Link Library

The construction of C++ components allows putting as many service implementations into a component file as desired. Ensure that the component operations are implemented in such a way that component_writeInfo() and component_getFactory() handle all services correctly. Refer to the sample component simple_component to see an example on how to implement two services in one link library.

4.6.10    Building and Testing C++ Components

Build Process

For details about building component code, see the gnu makefile. It uses a number of platform dependent variables used in the SDK that are included from <SDK>/settings/settings.mk. For simplicity, details are omitted here, and the build process is just sketched in eight steps:

  1. The UNOIDL compiler compiles the .idl file some.idl into an urd file.

  2. The resulting binary .urd files are merged into a new simple_component.rdb.

  3. The tool xml2cmp parses the xml component description simple_component.xml for types needed for compiling. This file describes the service implementation(s) for deployment, such as the purpose of the implementation(s) and used types. Visit http://udk.openoffice.org/common/man/module_description.html for details about the syntax of these XML files.

  4. The types parsed in step 3 are passed to cppumaker, which generates the appropriate header pairs into the output include directory using simple_component.rdb and the OpenOffice.org type library applicat.rdb that is stored in the program directory of your OpenOffice.org installation.

Tip graphics marks a hint section in the text

For your own component you can simplify step 3 and 4, and pass the types used by your component to cppumaker using the -T option.

  1. The source files service1_impl.cxx and service2_impl.cxx are compiled.

  2. The shared library is linked out of object files, linking dynamically to the UNO base libraries sal, cppu and cppuhelper. The shared library's name is libsimple_component.so on Unix and simple_component.dll on Windows.

Pay attention to the following important text section

In general, the shared library component should limit its exports to only the above mentioned functions (prefixed with component_) to avoid symbol clashes on Unix. In addition, for the gnu gcc3 C++ compiler, it is necessary to export the RTTI symbols of exceptions, too.

  1. The shared library component is registered into simple_component.rdb. This can also be done manually running

$ regcomp -register -r simple_component.rdb -c simple_component.dll

Test Registration and Use

The component's registry simple_component.rdb has entries for the registered service implementations. If the library is registered successfully, run:

$ regview simple_component.rdb

The result should look similar to the following:

/

 / UCR

   / my_module

     / XSomething

       ... interface information ...

 / IMPLEMENTATIONS

   / my_module.my_sc_impl.MyService2

     / UNO

       / ACTIVATOR

         Value: Type = RG_VALUETYPE_STRING

                Size = 34

                Data = "com.sun.star.loader.SharedLibrary"

       / SERVICES

         / my_module.MyService2

       / LOCATION

         Value: Type = RG_VALUETYPE_STRING

                Size = 21

                Data = "simple_component.dll"

   / my_module.my_sc_impl.MyService1

     / UNO

       / ACTIVATOR

         Value: Type = RG_VALUETYPE_STRING

                Size = 34

                Data = "com.sun.star.loader.SharedLibrary"

       / SERVICES

         / my_module.MyService1

       / LOCATION

         Value: Type = RG_VALUETYPE_STRING

                Size = 21

                Data = "simple_component.dll"

 / SERVICES

   / my_module.MyService1

     Value: Type = RG_VALUETYPE_STRINGLIST

            Size = 40

            Len  = 1

            Data = 0 = "my_module.my_sc_impl.MyService1"

   / my_module.MyService2

     Value: Type = RG_VALUETYPE_STRINGLIST

            Size = 40

            Len  = 1

            Data = 0 = "my_module.my_sc_impl.MyService2"

OpenOffice.org recognizes registry files being inserted into the unorc file (on Unix, uno.ini on Windows) in the program directory of your OpenOffice.org installation. Extend the types and services in that file by simple_component.rdb. The given file has to be an absolute file URL, but if the rdb is copied to the OpenOffice.org program directory, a $SYSBINDIR macro can be used, as shown in the following unorc file:

[Bootstrap]

UNO_TYPES=$SYSBINDIR/applicat.rdb $SYSBINDIR/simple_component.rdb
UNO_SERVICES=$SYSBINDIR/applicat.rdb $SYSBINDIR/simple_component.rdb

Second, when running OpenOffice.org, extend the PATH (Windows) or LD_LIBRARY_PATH (Unix), including the output path of the build, so that the loader finds the component. If the shared library is copied to the program directory or a link is created inside the program directory (Unix only), do not extend the path.

Launching the test component inside a OpenOffice.org Basic script is simple to do, as shown in the following code:

Sub Main

    REM calling service1 impl

    mgr = getProcessServiceManager()

    o = mgr.createInstance("my_module.MyService1")

    MsgBox o.methodOne("foo")

    MsgBox o.dbg_supportedInterfaces

    REM calling service2 impl

    dim args( 0 )

    args( 0 ) = "foo"

    o = mgr.createInstanceWithArguments("my_module.MyService2", args())

    MsgBox o.methodOne("bar")

    MsgBox o.dbg_supportedInterfaces

End Sub

This procedure instantiates the service implementations and performs calls on their interfaces. The return value of the methodOne() call is brought up in message boxes. The Basic object property dbg_supportedInterfaces retrieves its information through the com.sun.star.lang.XTypeProvider interfaces of the objects.

4.7    Integrating Components into OpenOffice.org

If a component needs to be called from the OpenOffice.org user interface, it must be able to take part in the communication between the UI layer and the application objects. OpenOffice.org uses command URLs for this purpose. When a user chooses an item in the user interface, a command URL is dispatched to the application framework and processed in a chain of responsibility until an object accepts the command and executes it, thus consuming the command URL. This mechanism is known as the dispatch framework, it is covered in detail in chapter 6.1.6 Office Development - OpenOffice.org Application Environment - Using the Dispatch Framework.

From version 1.1, OpenOffice.org provides user interface support for custom components by two basic mechanisms:

The left side of shows the two possibilities for processing command URLs: either custom protocol handlers or the specialized job protocol. On the right, you see the job execution environment, which is used by the job protocol, but can also be used without command URLs from any source code.

Overview graphics of processing command URLs in the the context of a job execution environment
Illustration 4.2: Processing command URLs and the job execution environment

This section describes how to use these mechanisms. It discusses protocol handlers and jobs, then  describes how to customize the OpenOffice.org user interface for components.

4.7.1    Protocol Handler

The dispatch framework binds user interface controls, such as menu or toolbar items, to the functionality of OpenOffice.org. Every function that is reachable in the user interface is described by a command URL and corresponding parameters.

The protocol handler mechanism is an API that enables programmers to add arbitrary URL schemas to the existing set of command URLs by writing additional protocol handlers for them. Such a protocol handler must be implemented as a UNO component and registered in the OpenOffice.org configuration for the new URL schema.

Overview

To issue a command URL, the first step is to locate a dispatch object that is responsible for the URL. Start with the frame that contains the document for which the command is meant. Its interface method com.sun.star.frame.XDispatchProvider:queryDispatch()is called with a URL and special search parameters to locate the correct target. This request is passed through the following instances:

disabling commands

Checks if command is on the list of disabled commands, described in 4.7.4 Writing UNO Components - Integrating Components into OpenOffice.org - Disable Commands

interception

Intercepts command and re-routes it, described in 6.1.6 Office Development - OpenOffice.org Application Environment - Using the Dispatch Framework - Dispatch Interception

targeting

Determines target frame for command, described in 6.1.5 Office Development - OpenOffice.org Application Environment - Handling Documents - Loading Documents - Target Frame

controller

Lets the controller of the frame try to handle the command, described in 6.1.6 Office Development - OpenOffice.org Application Environment - Using the Dispatch Framework - Processing Chain

protocol handler

Determines if there is a custom handler for the command, described in this section

interpret as loadable content

Loads content from file, described in 6.1.5 Office Development - OpenOffice.org Application Environment - Handling Documents - Loading Documents - URL Parameter. Generally contents are loaded into a frame by a com.sun.star.frame.FrameLoader , but if a content (e.g. a sound) needs no frame, a com.sun.star.frame.ContentHandler service is used, which needs no target frame for its operation.

The list shows that the protocol handler will only be used if the URL has not been called before. Because targeting has already been done, it is clear that the command will run in the located target frame environment, which is usually "_self".

Note graphics marks a special text section

The target "_blank" cannot be used for a protocol handler. Since "_blank" leads to the creation of a new frame for a component, there would be no component yet for the protocol handler to work with.

A protocol handler decides by itself if it returns a valid dispatch object, that is, it is asked to agree with the given request by the dispatch framework. If a dispatch object is returned, the requester can use it to dispatch the URL by calling its dispatch() method.

Implementation

A protocol handler implementation must follow the service definition com.sun.star.frame.ProtocolHandler. At least the interface com.sun.star.frame.XDispatchProvider must be supported.

UML diagram showing the com.sun.star.frame.ProtocolHandler service
Illustration 4.3: Protocol handler

The interface XDispatchProvider supports two methods:

XDispatch queryDispatch(  [in] ::com::sun::star::util::URL URL,

                          [in] string  TargetFrameName,

                          [in] long SearchFlags )

sequence< XDispatch > queryDispatches(  [in] sequence< DispatchDescriptor >  Requests )

 

The protocol handler is asked for its agreement to execute a given URL by a call to the interface method com.sun.star.frame.XDispatchProvider:queryDispatch(). The incoming URL should be parsed and validated. If the URL is valid and the protocol handler is able to handle it, it should return a dispatch object, thus indicating that it accepts the request.

The dispatch object must support the interface com.sun.star.frame.XDispatch with the methods

[oneway] void dispatch(  [in] ::com::sun::star::util::URL URL,

                         [in] sequence< ::com::sun::star::beans::PropertyValue >  Arguments )

addStatusListener [oneway] void addStatusListener(  [in] XStatusListener Control,

                                                    [in] ::com::sun::star::util::URL  URL )

removeStatusListener [oneway] void removeStatusListener(  [in] XStatusListener Control,

                                                          [in] ::com::sun::star::util::URL  URL )

Optionally, the dispatch object can support the interface com.sun.star.frame.XNotifyingDispatch, which derives from XDispatch and introduces a new method dispatchWithNotification(). This interface is preferred if it is present.

[oneway] void dispatchWithNotification(

        [in] com::sun::star::util::URL URL,

        [in] sequence<com::sun::star::beans::PropertyValue> Arguments,

        [in] com::sun::star::frame::XDispatchResultListener Listener);

A basic protocol handler is free to implement XDispatch itself, so it can simply return itself in the queryDispatch() implementation. But it is advisable to return specialized helper dispatch objects instead of the protocol handler instance. This helps to decrease the complexity of status updates. It is easier to notify status listeners for a single-use dispatch object instead of multi-use dispatch objects, which have to distinguish the URLs given in addStatusListener() all the time.

Tip graphics marks a hint section in the text

To supply the UI with status information for a command, it is required to call back a com.sun.star.frame.XStatusListener during its registration immediately, for example:

public void addStatusListener(XStatusListener xControl, URL aURL) {
   FeatureStateEvent aState = new FeatureStateEvent();
   aState.FeatureURL = aURL;
   aState.IsEnabled  = true;
   aState.State      = Boolean.TRUE;
   xControl.statusChanged(aState);
   m_lListenerContainer.add(xControl);
}

A protocol handler can support the interface com.sun.star.lang.XInitialization if it wants to be initialized with a com.sun.star.frame.Frame environment to work with. XInitialization contains one method:

void initialize(  [in] sequence< any > aArguments )

A protocol handler is generally used in a well known com.sun.star.frame.Frame context, therefore the dispatch framework always passes this frame context through initialize() as the first argument, if XInitialization is present. Its com.sun.star.frame.XFrame interface provides access to the controller, from which you can get the document model and have a good starting point to work with the document.

shows how to get to the controller and the document model from an XFrame interface. The chapter 6.1.3 Office Development - OpenOffice.org Application Environment - Using the Component Framework describes the usage of frames, controllers and models in more detail.

UML diagram showing the frame-controller-model organisation
Illustration 4.4: Frame-controller-model organization

Note graphics marks a special text section

A protocol handler can be implemented as a singleton, but this poses multithreading difficulties. In a multithreaded environment it is most unlikely that the initial frame context matches every following dispatch request. So you have to be prepared for calls to initialize() by multiple threads for multiple frames. A dispatch object can also be used more then once, but must be bound to the target frame that was specified in the original queryDispatch()call. A change of the frame context can cause trouble if the protocol handler returns itself as a dispatch object. A protocol handler singleton must return new dispatch objects for every request, which has to be initialized with the current context of the protocol handler, and you have to synchronize between initialize() and queryDispatch(). The protocol handler would have to serve as a kind of factory for specialized dispatch objects.
You can avoid these problems, if you write your protocol handler as a multi-instance service.

The opportunity to deny a queryDispatch() call allows you to register a protocol handler for a URL schema using wildcards, and to accept only a subset of all possible URLs. That way the handler object can validate incoming URLs and reject them if they appear to be invalid. However, this feature should not be used to register different protocol handlers for the same URL schema and accept different subsets by different handler objects, because it would be very difficult to avoid ambiguities.

Since a protocol handler is a UNO component, it must contain the component operations needed by a UNO service manager. These operations are certain static methods in Java or export functions in C++. It also has to implement the core interfaces used to enable communication with UNO and the application environment. For more information on the component operations and core interfaces, please see 4.3 Writing UNO Components - Component Architecture and 4.4 Writing UNO Components - Core Interfaces to Implement.

Java Protocol Handler - vnd.sun.star.framework.ExampleHandler

The following example shows a simple protocol handler implementation in Java. For simplicity, the component operations are omitted.

// imports

#import com.sun.star.beans.*;

#import com.sun.star.frame.*;

#import com.sun.star.uno.*;

#import com.sun.star.util.*;

// definition

public class ExampleHandler implements com.sun.star.frame.XDispatchProvider,

        com.sun.star.lang.XInitialization {

    // member

    /** points to the frame context in which this handler runs, is set in initialize()*/

    private com.sun.star.frame.XFrame m_xContext;

    // Dispatch object as inner class

    class OwnDispatch implements com.sun.star.frame.XDispatch {

        /** the target frame, in which context this dispatch must work */

        private com.sun.star.frame.XFrame m_xContext;

        /** describe the function of this dispatch.

         *  Because a URL can contain e.g. optional arguments

         *  this URL means the main part of such URL sets only. */

        private com.sun.star.util.URL m_aMainURL;

        /** contains all interested status listener for this dispatch */

        private java.lang.HashMap m_lListener;

        /** take over all neccessary parameters from outside. */

        public OwnDispatch(com.sun.star.frame.XFrame xContext, com.sun.star.util.URL aMainURL) {

            m_xContext = xContext;

            m_aMainURL = aMainURL;

        }

        /** execute the functionality, which is described by this URL.

         *

         *  @param  aURL

         *          this URL can describe the main function, we already know;

         *          but it can specify a sub function too! But queryDispatch()

         *          and dispatch() are used in a generic way ...

         *          m_aMainURL and aURL will be the same.

         *

         *  @param  lArgs

         *          optional arguments for this request

         */

        public void dispatch(com.sun.star.util.URL aURL, com.sun.star.beans.PropertyValue lArgs)

            throws com.sun.star.uno.RuntimeException {

            // ... do function

            // ... inform listener if neccessary

        }

        /** register a new listener and bind it toe given URL.

         *

         *  Note: Because the listener does not know the current state

         *  and may nobody change it next time, it is neccessary to inform it

         *  immediatly about this current state. So the listener is up to date.

         */

        public void addStatusListener(com.sun.star.frame.XStatusListener xListener,

                com.sun.star.util.URL aURL) throws com.sun.star.uno.RuntimeException {

            // ... register listener for given URL

            // ... inform it immediatly about current state!

            xListener.statusChanged(...);

        }

        /** deregister a listener for this URL. */

        public void removeStatusListener(com.sun.star.frame.XStatusListener xListener,

                com.sun.star.util.URLaURL) throws com.sun.star.uno.RuntimeException {

            // ... deregister listener for given URL

        }

    }

    /** set the target frame reference as context for all following dispatches. */

    public void initialize(com.sun.star.uno.Any[] lContext) {

        m_xContext = (com.sun.star.frame.XFrame)com.sun.star.uno.AnyConverter.toObject(lContext[0]);

    }

    /** should return a valid dispatch object for the given URL.

     *

     *  In case the URL is not valid an empty reference can be returned.

     *  The parameter sTarget and nFlags can be ignored. The will be "_self" and 0

     *  everytime.

     */

    public com.sun.star.frame.XDispatch queryDispatch(com.sun.star.util.URL aURL,

            java.lang.String sTarget, int nFlags ) throws com.sun.star.uno.RuntimeException {

        // check if given URL is valid for this protocol handler

        if (!aURL.Main.startsWith("myProtocol_1://") && !aURL.Main.startsWith("myProtocol_2://"))

            return null;

        // and return a specialized dispatch object

        // Of course "return this" would be possible too ...

        return (com.sun.star.frame.XDispatch)(new OwnDispatch(m_xContext, aURL));

    }

    /** optimized API call for remote.

     *

     *  It should be forwarded to queryDispatch() for every request item of the

     *  given DispatchDescriptor list.

     *

     *  But note: it is not allowed to pack the return list of dispatch objects.

     *  Every request in source list must match to a reference (null or valid) in

     *  the destination list!

     */

    public com.sun.star.frame.XDispatch[] queryDispatches(

            com.sun.star.frame.DispatchDescriptor[] lRequests) throws com.sun.star.uno.RuntimeException {

        int c = lRequests.length;

        com.sun.star.frame.XDispatch[] lDispatches = new com.sun.star.frame.XDispatch[c];

        for (int i=0; i<c; ++i)

            lDispatches[i] = queryDispatch(lRequests[i].FeatureURL,

                lRequests[i].FrameName, lRequests[i].SearchFlags);

        return lDispatches;

    }

}

C++ Protocol Handler - org.openoffice.Office.addon.example

The next example shows a protocol handler in C++. The section 4.7.3 Writing UNO Components - Integrating Components into OpenOffice.org - User Interface Add-Ons below will integrate this example handler into the graphical user interface of OpenOffice.org.

The following code shows the UNO component operations that must be implemented in a C++ protocol handler example. The three C functions return vital information to the UNO environment:

#include <stdio.h>

#ifndef _RTL_USTRING_HXX_

#include <rtl/ustring.hxx>

#endif

#ifndef _CPPUHELPER_QUERYINTERFACE_HXX_

#include <cppuhelper/queryinterface.hxx> // helper for queryInterface() impl

#endif

#ifndef _CPPUHELPER_FACTORY_HXX_

#include <cppuhelper/factory.hxx> // helper for component factory

#endif

// generated c++ interfaces

#ifndef _COM_SUN_STAR_LANG_XSINGLESERVICEFACTORY_HPP_

#include <com/sun/star/lang/XSingleServiceFactory.hpp>

#endif

#ifndef _COM_SUN_STAR_LANG_XMULTISERVICEFACTORY_HPP_

#include <com/sun/star/lang/XMultiServiceFactory.hpp>

#endif

#ifndef _COM_SUN_STAR_LANG_XSERVICEINFO_HPP_

#include <com/sun/star/lang/XServiceInfo.hpp>

#endif

#ifndef _COM_SUN_STAR_REGISTRY_XREGISTRYKEY_HPP_

#include <com/sun/star/registry/XRegistryKey.hpp>

#endif

// include our specific addon header to get access to functions and definitions

#include <addon.hxx>

 

using namespace ::rtl;

using namespace ::osl;

using namespace ::cppu;

using namespace ::com::sun::star::uno;

using namespace ::com::sun::star::lang;

using namespace ::com::sun::star::registry;

//##################################################################################################

//#### EXPORTED ####################################################################################

//##################################################################################################

/**

 * Gives the environment this component belongs to.

 */

extern "C" void SAL_CALL component_getImplementationEnvironment(const sal_Char ** ppEnvTypeName, uno_Environment ** ppEnv)

{

        *ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME;

}

/**

 * This function creates an implementation section in the registry and another subkey

 *

 * for each supported service.

 * @param pServiceManager   the service manager

 * @param pRegistryKey      the registry key

 */

extern "C" sal_Bool SAL_CALL component_writeInfo(void * pServiceManager, void * pRegistryKey) {

    sal_Bool result = sal_False;

    if (pRegistryKey) {

        try {

            Reference< XRegistryKey > xNewKey(

                reinterpret_cast< XRegistryKey * >( pRegistryKey )->createKey(

                    OUString( RTL_CONSTASCII_USTRINGPARAM("/" IMPLEMENTATION_NAME "/UNO/SERVICES")) ) );

                       

            const Sequence< OUString > & rSNL = Addon_getSupportedServiceNames();

            const OUString * pArray = rSNL.getConstArray();

            for ( sal_Int32 nPos = rSNL.getLength(); nPos--; )

               xNewKey->createKey( pArray[nPos] );

                       

            return sal_True;

        }

        catch (InvalidRegistryException &) {

           // we should not ignore exceptions

        }

    }

    return result;

}

/**

 * This function is called to get service factories for an implementation.

 *

 * @param pImplName       name of implementation

 * @param pServiceManager a service manager, need for component creation

 * @param pRegistryKey    the registry key for this component, need for persistent data

 * @return a component factory

 */

extern "C" void * SAL_CALL component_getFactory(const sal_Char * pImplName,

        void * pServiceManager, void * pRegistryKey) {

    void * pRet = 0;

       

    if (rtl_str_compare( pImplName, IMPLEMENTATION_NAME ) == 0) {

        Reference< XSingleServiceFactory > xFactory(createSingleFactory(

            reinterpret_cast< XMultiServiceFactory * >(pServiceManager),

            OUString(RTL_CONSTASCII_USTRINGPARAM(IMPLEMENTATION_NAME)),

            Addon_createInstance,

            Addon_getSupportedServiceNames()));

        if (xFactory.is()) {

            xFactory->acquire();

            pRet = xFactory.get();

        }

    }

    return pRet;

}

//##################################################################################################
//#### Helper functions for the implementation of UNO component interfaces #########################
//##################################################################################################

::rtl::OUString Addon_getImplementationName()

throw (RuntimeException) {

    return ::rtl::OUString ( RTL_CONSTASCII_USTRINGPARAM ( IMPLEMENTATION_NAME ) );

}

sal_Bool SAL_CALL Addon_supportsService( const ::rtl::OUString& ServiceName )

throw (RuntimeException)

{

    return ServiceName.equalsAsciiL( RTL_CONSTASCII_STRINGPARAM ( SERVICE_NAME ) );

}

Sequence< ::rtl::OUString > SAL_CALL Addon_getSupportedServiceNames()

throw (RuntimeException)

{

        Sequence < ::rtl::OUString > aRet(1);

    ::rtl::OUString* pArray = aRet.getArray();

    pArray[0] =  ::rtl::OUString ( RTL_CONSTASCII_USTRINGPARAM ( SERVICE_NAME ) );

    return aRet;

}

Reference< XInterface > SAL_CALL Addon_createInstance( const Reference< XMultiServiceFactory > & rSMgr)

        throw( Exception )

{

        return (cppu::OWeakObject*) new Addon( rSMgr );

}

The C++ protocol handler in the example has the implementation name org.openoffice.Office.addon.example. It supports the URL protocol schema org.openoffice.Office.addon.example: and provides three different URL commands: Function1 , Function2 and Help.

The protocol handler implements the IDL:com.sun.star.frame.XDispatch] interface, so it can return a reference to itself when it is queried for a dispatch object that matches the given URL.

The implementation of the dispatch() method below shows how the supported commands are routed inside the protocol handler. Based on the path part of the URL, a simple message box displays which function has been called. The message box is implemented using the UNO toolkit and uses the container windows of the given frame as parent window.

#ifndef _Addon_HXX

#include <addon.hxx>

#endif

#ifndef _OSL_DIAGNOSE_H_

#include <osl/diagnose.h>

#endif

#ifndef _RTL_USTRING_HXX_

#include <rtl/ustring.hxx>

#endif

#ifndef _COM_SUN_STAR_LANG_XMULTISERVICEFACTORY_HPP_

#include <com/sun/star/lang/XMultiServiceFactory.hpp>

#endif

#ifndef _COM_SUN_STAR_BEANS_PROPERTYVALUE_HPP_

#include <com/sun/star/beans/PropertyValue.hpp>

#endif

#ifndef _COM_SUN_STAR_FRAME_XFRAME_HPP_

#include <com/sun/star/frame/XFrame.hpp>

#endif

#ifndef _COM_SUN_STAR_FRAME_XCONTROLLER_HPP_

#include <com/sun/star/frame/XController.hpp>

#endif

#ifndef _COM_SUN_STAR_AWT_XTOOLKIT_HPP_

#include <com/sun/star/awt/XToolkit.hpp>

#endif

#ifndef _COM_SUN_STAR_AWT_XWINDOWPEER_HPP_

#include <com/sun/star/awt/XWindowPeer.hpp>

#endif

#ifndef _COM_SUN_STAR_AWT_WINDOWATTRIBUTE_HPP_

#include <com/sun/star/awt/WindowAttribute.hpp>

#endif

#ifndef _COM_SUN_STAR_AWT_XMESSAGEBOX_HPP_

#include <com/sun/star/awt/XMessageBox.hpp>

#endif

using rtl::OUString;

using namespace com::sun::star::uno;

using namespace com::sun::star::frame;

using namespace com::sun::star::awt;

using com::sun::star::lang::XMultiServiceFactory;

using com::sun::star::beans::PropertyValue;

using com::sun::star::util::URL;

// This is the service name an Add-On has to implement

#define SERVICE_NAME "com.sun.star.frame.ProtocolHandler"

/**

  * Show a message box with the UNO based toolkit

  */
static void ShowMessageBox(const Reference< XToolkit >& rToolkit, const Reference< XFrame >& rFrame, const OUString& aTitle, const OUString& aMsgText)

{

    if ( rFrame.is() && rToolkit.is() )

    {

        // describe window properties.
       WindowDescriptor                aDescriptor;
       aDescriptor.Type              = WindowClass_MODALTOP                            ;
       aDescriptor.WindowServiceName = OUString( RTL_CONSTASCII_USTRINGPARAM( "infobox" ));
       aDescriptor.ParentIndex       = -1                                              ;
       aDescriptor.Parent            = Reference< XWindowPeer >( rFrame->getContainerWindow(),

                                                                  UNO_QUERY )  ;
       aDescriptor.Bounds            = Rectangle(0,0,300,200)                ;
       aDescriptor.WindowAttributes  = WindowAttribute::BORDER               |
                                       WindowAttribute::MOVEABLE             |
                                       WindowAttribute::CLOSEABLE;

        Reference< XWindowPeer > xPeer = rToolkit->createWindow( aDescriptor );
       if ( xPeer.is() )
       {
           Reference< XMessageBox > xMsgBox( xPeer, UNO_QUERY );
           if ( xMsgBox.is() )
           {
               xMsgBox->setCaptionText( aTitle );
               xMsgBox->setMessageText( aMsgText );
               xMsgBox->execute();
           }
       }
   }

}

//##################################################################################################
//#### Implementation of the ProtocolHandler and Dispatch Interfaces             ###################
//##################################################################################################

// XInitialization

/**

  * Called by the Office framework.

  * We store the context information

  * given, like the frame we are bound to, into our members.

  */
void SAL_CALL Addon::initialize( const Sequence< Any >& aArguments ) throw ( Exception, RuntimeException)

{

    Reference < XFrame > xFrame;

    if ( aArguments.getLength() )

    {

        aArguments[0] >>= xFrame;

        mxFrame = xFrame;

    }

   

    // Create the toolkit to have access to it later

    mxToolkit = Reference< XToolkit >( mxMSF->createInstance(

                                        OUString( RTL_CONSTASCII_USTRINGPARAM(

                                            "com.sun.star.awt.Toolkit" ))), UNO_QUERY );

}

// XDispatchProvider

/**

  * Called by the Office framework.

  * We are ask to query the given URL and return a dispatch object if the URL

  * contains an Add-On command.

  */
Reference< XDispatch > SAL_CALL Addon::queryDispatch( const URL& aURL, const ::rtl::OUString& sTargetFrameName, sal_Int32 nSearchFlags )

                                throw( RuntimeException )

{

    Reference < XDispatch > xRet;

    if ( aURL.Protocol.compareToAscii("org.openoffice.Office.addon.example:") == 0 )

    {

        if ( aURL.Path.compareToAscii( "Function1" ) == 0 )

            xRet = this;

        else if ( aURL.Path.compareToAscii( "Function2" ) == 0 )

            xRet = this;

        else if ( aURL.Path.compareToAscii( "Help" ) == 0 )

            xRet = this;

    }

    return xRet;

}

/**

  * Called by the Office framework.

  * We are ask to query the given sequence of URLs and return dispatch objects if the URLs

  * contain Add-On commands.

  */
Sequence < Reference< XDispatch > > SAL_CALL Addon::queryDispatches(

        const Sequence < DispatchDescriptor >& seqDescripts )

        throw( RuntimeException )

{

    sal_Int32 nCount = seqDescripts.getLength();

    Sequence < Reference < XDispatch > > lDispatcher( nCount );

    for( sal_Int32 i=0; i<nCount; ++i )

        lDispatcher[i] = queryDispatch( seqDescripts[i].FeatureURL, seqDescripts[i].FrameName, seqDescripts[i].SearchFlags );

    return lDispatcher;

}

// XDispatch

/**

  * Called by the Office framework.

  * We are ask to execute the given Add-On command URL.

  */

void SAL_CALL Addon::dispatch( const URL& aURL, const Sequence < PropertyValue >& lArgs ) throw (RuntimeException)

{

    if ( aURL.Protocol.compareToAscii("org.openoffice.Office.addon.example:") == 0 )

    {

        if ( aURL.Path.compareToAscii( "Function1" ) == 0 )

        {

            ShowMessageBox( mxToolkit, mxFrame,

                            OUString( RTL_CONSTASCII_USTRINGPARAM( "SDK Add-On example" )),

                            OUString( RTL_CONSTASCII_USTRINGPARAM( "Function 1 activated" )) );

        }

        else if ( aURL.Path.compareToAscii( "Function2" ) == 0 )

        {

            ShowMessageBox( mxToolkit, mxFrame,

                            OUString( RTL_CONSTASCII_USTRINGPARAM( "SDK Add-On example" )),

                            OUString( RTL_CONSTASCII_USTRINGPARAM( "Function 2 activated" )) );

        }

        else if ( aURL.Path.compareToAscii( "Help" ) == 0 )

        {

            // Show info box

            ShowMessageBox( mxToolkit, mxFrame,

                            OUString( RTL_CONSTASCII_USTRINGPARAM( "About SDK Add-On example" )),

                            OUString( RTL_CONSTASCII_USTRINGPARAM( "This is the SDK Add-On example")));

        }

    }

}

/**

  * Called by the Office framework.

  * We are asked to store a status listener for the given URL.

  */

void SAL_CALL Addon::addStatusListener( const Reference< XStatusListener >& xControl, const URL& aURL )         throw (RuntimeException)

{

}

/**

  * Called by the Office framework.

  * We are asked to remove a status listener for the given URL.

  */

void SAL_CALL Addon::removeStatusListener( const Reference< XStatusListener >& xControl,

        const URL& aURL )

        throw (RuntimeException)

{

}

//##################################################################################################
//#### Implementation of the recommended/mandatory interfaces of a UNO component ###################
//##################################################################################################

// XServiceInfo

::rtl::OUString SAL_CALL Addon::getImplementationName(  )

        throw (RuntimeException)

{

        return Addon_getImplementationName();

}

sal_Bool SAL_CALL Addon::supportsService( const ::rtl::OUString& rServiceName )

        throw (RuntimeException)

{

    return Addon_supportsService( rServiceName );

}

Sequence< ::rtl::OUString > SAL_CALL Addon::getSupportedServiceNames(  )

        throw (RuntimeException)

{

    return Addon_getSupportedServiceNames();

}

Configuration

A protocol handler needs configuration entries, which provide the framework with the necessary information to find the handler. The schema of the configuration branch org.openoffice.Office.ProtocolHandler defines how to bind handler instances to their URL schemas:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE oor:component-schema SYSTEM "../../../../component-schema.dtd">

<oor:component-schema xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" oor:name="ProtocolHandler" oor:package="org.openoffice.Office" xml:lang="en-US">

        <templates>

                <group oor:name="Handler">

                        <prop oor:name="Protocols" oor:type="oor:string-list"/>

                </group>

        </templates>

                <component>

                        <set oor:name="HandlerSet" oor:node-type="Handler"/>

                </component>

</oor:component-schema>

Each set node entry specifies one protocol handler, using its UNO implementation name. The only property it has is the Protocols item. Its type must be [string-list] and it contains a list of URL schemas bound to the handler. Wildcards are allowed, otherwise the entire string must match the dispatched URL.

Configuration for vnd.sun.star.framework.ExampleHandler

The following example ProtocolHandler.xcu contains the protocol handler configuration for the example's Java protocol handler:

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:name="ProtocolHandler" oor:package="org.openoffice.Office" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

        <node oor:name="HandlerSet">

                <node oor:name="vnd.sun.star.framework.ExampleHandler" oor:op="replace">

                        <prop oor:name="Protocols">

                                <value>myProtocol_1://* myProtocol_2://*</value>

                        </prop>

                </node>

        </node>

</oor:component-data>

The example adds two new URL protocols using wildcards:

myProtocol_1://*

myProtocol_2://*

Both protocols are bound to the handler implementation vnd.sun.star.framework.ExampleHandler. Note that this must be the implementation name of the handler, not the name of the service com.sun.star.frame.ProtocolHandler it implements. Because all implementations of the service com.sun.star.frame.ProtocolHandler share the same UNO service name, you cannot use this name in the configuration files.

To prevent ambiguous implementation names, the following naming schema for implementation names is frequently used:

vnd.<namespace_of_company>.<namespace_of_implementation>.<class_name>

e.g. vnd.sun.star.framework.ExampleHandler
<namespace_of_company>                = sun.star
<namespace_of_implementation>        = framework
<class_name>                                = ExampleHandler

An alternative would be the naming convention proposed in 4.4.3 Writing UNO Components - Core Interfaces to Implement - XServiceInfo:

<namespace_of_creator>.comp.<namespace_of_implementation>.<class_name>

e.g. org.openoffice.comp.framework.OProtocolHandler

All of these conventions are proposals; what matters is:

Configuration for org.openoffice.Office.addon.example

The following ProtocolHandler.xcu file configures the example's C++ protocol handler with the implementation name org.openoffice.Office.addon.example in the configuration branch org.openoffice.Office.ProtocolHandler following the same schema.

<?xml version="1.0" encoding="UTF-8"?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="ProtocolHandler" oor:package="org.openoffice.Office">
<node oor:name="HandlerSet">
 <node oor:name="org.openoffice.Office.addon.example" oor:op="replace">
  <prop oor:name="Protocols" oor:type="oor:string-list">
   <value>org.openoffice.Office.addon.example:*</value>
  </prop>
 </node>
</node>
</oor:component-data>

The configuration adds one new URL protocol using wildcards:

org.openoffice.Office.addon.example:*

Based on this URL protocol, the C++ protocol handler can route, for example, a dispatched URL

org.openoffice.Office.addon.example:Function1

to the corresponding target routine. See the implementation of the dispatch() method in the XDispatch interface of the C++ source fragment above.

Installation

When the office finds a protocol handler implementation for a URL in the configuration files, it asks the global service manager to instantiate that implementation. All components must be registered with the service manager before they can be instantiated. How this is done is described in section 4.9.1 Writing UNO Components - Deployment Options for Components - UNO Package Installation.

The easiest method to configure and register a new protocol handler in a single step is to use the package installation tool pkchkg . A suitable package file for the example protocol handler could contain the following directory structure:

ExampleHandler.zip:

    ProtocolHandler.xcu

    windows.plt/

        examplehandler.dll

    solaris_sparc.plt/

        libexamplehandler.so

    linux_x86.plt/

        libexamplehandler.so

The .xcu file goes into the root of the package, the shared libraries for the various platforms go to their respective .plt directories.

The package installation is as simple as changing to the <OfficePath>/program directory with a command-line shell and running

$ pkgchk /foo/bar/ExampleHandler.zip

For an explanation of the package structure and more deployment options please refer to 4.9 Writing UNO Components - Deployment Options for Components.

4.7.2    Jobs

Overview

A job in OpenOffice.org is a UNO component that can be executed by the job execution environment upon an event. It can read and write its own set of configuration data in the configuration branch org.openoffice.Office.Jobs, and it can be activated and deactivated from a certain point in time using special time stamps. It may be started with or without an environment, and it is protected against termination and lifetime issues.

The event that starts a job can be triggered by:

If you call trigger() at the job executor or employ the global event broadcaster, the office needs a valid set of configuration data for every job you want to run. The third approach, to use a vnd.star.sun.job: command URL, works with or without prior configuration.

shows an example job that counts how many times it has been triggered by an event and deactivates itself when it has been executed twice. It uses its own job-specific configuration layer to store the number of times it has been invoked. This value is passed to each newly created job instance as an initialization argument, and can be checked and written back to the configuration. When the counter exceeds two, the job uses the special deactivation feature of the job execution environment. Each job can have a user time stamp and and administrator time stamp to control activation and deactivation. When a job is deactivated, the execution environment updates the user time stamp value, so that subsequent events do not start this job again. It can be enabled by a newer time stamp value in the administration layer.

Sequence diagram showing  a job execution
Illustration 4.5: Flow diagram of an example job

Execution Environment

Jobs are executed in a job execution environment, which handles a number of tasks and problems that can occur when jobs are executed. In particular,

For this purpose, the job execution environment creates special wrapper objects for jobs. This wrapper object implements mechanisms to support lifetime control. The wrapper vetoes termination of the com.sun.star.frame.Desktop and the closing of frames that contain document models as long as there are dependent active jobs. It might also register as a com.sun.star.util.XCloseListener at a com.sun.star.frame.Frame or com.sun.star.document.OfficeDocument to handle the close communication on behalf of the job. It also listens for asynchronous job instances, and it is responsible for updates to the configuration data after a job has finished (see 4.7.2 Writing UNO Components - Integrating Components into OpenOffice.org - Jobs - Returning Results).

A central problem of external components in OpenOffice.org is their lifetime control. Every external component must deal with the possibility that the environment will terminate. It is not efficient to implement lifetime strategies in every job, so the job execution environment takes care of this problem. That way, a job can execute, while difficult situations are handled by the execution environment.

Another advantage of this approach is that it ensures future compatibility. If the mechanism changes in the future, termination is detected and prevented, and it is unnecessary to adapt every existing job implementation.

Implementation

A job must implement the service com.sun.star.task.Job if it needs to block the thread in which it is executed or com.sun.star.task.AsyncJob if the current state of the office is unimportant for the job. The service that a job implementation supports is detected at runtime. If both are available, the synchronous service com.sun.star.task.Job is preferred by the job execution environment.

UML diagram showing the com.sun.star.task.Job and com.sun.star.task.AsyncJob services
Illustration 4.6: Job framework

A synchronous job must not make assumptions about the environment, neither that it is the only job that runs currently nor that another object waits for its results. Only the thread context of a synchronous job is blocked until the job finishes its work.

An asynchronous job is not allowed to use threads internally, because OpenOffice.org needs to control thread creation. How asynchronous jobs are executed is an implementation detail of the global job execution environment.

Jobs that need a user interface must proceed with care, so that they do not interfere with the message loop of OpenOffice.org. The following rules apply:

The optional interfaces com.sun.star.lang.XComponent or com.sun.star.util.XCloseable should be supported so that jobs can be disposed of in a controlled manner. When these interfaces are present, the execution environment can call dispose() or close() rather than waiting for a job to finish. Otherwise OpenOffice.org must wait until the job is done. Invisible jobs can be especially problematic, because they cannot be recognized as the reason why OpenOffice.org refuses to exit.

Initialization

A job is initialized by a call to its main interface method, which starts the job. For synchronous jobs, the execution environment calls com.sun.star.task.XJob:execute(), whereas asynchronous jobs are run through com.sun.star.task.XAsyncJob:executeAsync().

Both methods take one parameter Arguments, which is a sequence of com.sun.star.beans.NamedValue structs. This sequence describes the job context.

It contains the environment where the job is running, which tells if the job was called by the job executor, the dispatch framework or the global event broadcaster service, and possibly provides a frame or a document model for the job to work with.

Tip graphics marks a hint section in the text

Section 4.7.1 Writing UNO Components - Integrating Components into OpenOffice.org - Protocol Handler - Implementation shows how to use a frame to get its associated document model.

The Arguments parameter also yields configuration data, if the job has been configured in the configuration branch org.openoffice.Office.Jobs. This data is separated into basic configuration and additional arguments stored in the configuration. The job configuration is described in section 4.7.2 Writing UNO Components - Integrating Components into OpenOffice.org - Jobs - Configuration.

Finally, Arguments can contain dynamic parameters given to the job at runtime. For instance, if a job has been called by the dispatch framework, and the dispatched command URL used parameters, these parameters can be passed on to the job through the execution arguments.

The following table shows the exact specification for the execution Arguments:

Elements of the Execution Arguments Sequence

Environment

sequence< com.sun.star.beans.NamedValue >. Contains environment data. The following named values are defined:

EnvType

string. Determines in which environment a job is executed. Defined Values:
"EXECUTOR": job has been executed by a call to trigger() at the job executor
"DISPATCH": job is dispatched as vnd.sun.star.job: URL
"DOCUMENTEVENT": job has been executed by the global event broadcaster mechanism

EventName

[optional] string. Only exists, if EnvType is "EXECUTOR" or "DOCUMENTEVENT". Contains the name of the event for which this job was registered in configuration. During runtime, this information can be used to handle different function sets by the same component implementation.

Frame

[optional] com.sun.star.frame.XFrame. Only exists, if EnvType is "DISPATCH". Contains the frame context of this job. Furthermore, the sub list DynamicData can contain the optional argument list of the corresponding com.sun.star.frame.XDispatch:dispatch() request.

Model

[optional] com.sun.star.frame.XModel. Only exists, if EnvType is "DOCUMENTEVENT". Contains the document model that can be used by the job.

Config

[optional] [sequence< com.sun.star.beans.NamedValue >]. Contains the generic set of job configuration properties as described in 4.7.2 Writing UNO Components - Integrating Components into OpenOffice.org - Jobs - Configuration but not the job specific data set. That is, this sub list only includes the properties Alias and Service, not the property Arguments. The property Arguments is reflected in the element JobConfig (see next element below)
Note: this sub list only exists if the job is configured with this data.

Alias

string. This property is declared as the name of the corresponding set node in the configuration set Jobs. It must be a unique name, which represents the structured information of a job.

Service

string. Represents the UNO implementation name of the job component.

JobConfig

[optional] [sequence< com.sun.star.beans.NamedValue >]
This sub list contains the job-specific set of configuration data as specified in the Arguments property of the job configuration. Its items depend on the job implementation. Note: this sub list only exists if the job is configured with this data.

DynamicData

[optional] [sequence< com.sun.star.beans.NamedValue >]. Contains optional parameters of the call that started the execution of this job. In particular, it can include the parameters of a com.sun.star.frame.XDispatch:dispatch() request, if Environment-EnvType is "DISPATCH"

The following example shows how a job can analyze the given arguments and how the environment in which the job is executed can be detected:

public synchronized java.lang.Object execute(com.sun.star.beans.NamedValue[] lArgs)

        throws com.sun.star.lang.IllegalArgumentException, com.sun.star.uno.Exception {

    // extract all possible sub list of given argument list

    com.sun.star.beans.NamedValue[] lGenericConfig = null;

    com.sun.star.beans.NamedValue[] lJobConfig     = null;

    com.sun.star.beans.NamedValue[] lEnvironment   = null;

    com.sun.star.beans.NamedValue[] lDispatchArgs  = null;

    int c = lArgs.length;

    for (int i=0; i<c; ++i) {

        if (lArgs[i].Name.equals("Config"))

            lGenericConfig = (com.sun.star.beans.NamedValue[])

                com.sun.star.uno.AnyConverter.toArray(lArgs[i].Value);

        else

            if (lArgs[i].Name.equals("JobConfig"))

                lJobConfig = (com.sun.star.beans.NamedValue[])

                    com.sun.star.uno.AnyConverter.toArray(lArgs[i].Value);

            else

                if (lArgs[i].Name.equals("Environment"))

                    lEnvironment = (com.sun.star.beans.NamedValue[])

                        com.sun.star.uno.AnyConverter.toArray(lArgs[i].Value);

                else

                    if (lArgs[i].Name.equals("DynamicData"))

                        lDispatchArgs = (com.sun.star.beans.NamedValue[])

                            com.sun.star.uno.AnyConverter.toArray(lArgs[i].Value);

                    else

                        // It is not realy an error – because unknown items can be ignored ...

                        throw new com.sun.star.lang.IllegalArgumentException("unknown sub list detected");

    }

    // Analyze the environment info. This sub list is the only guarenteed one!

    if (lEnvironment==null)

        throw new com.sun.star.lang.IllegalArgumentException("no environment");

    java.lang.String          sEnvType   = null;

    java.lang.String          sEventName = null;

    com.sun.star.frame.XFrame xFrame     = null;
   com.sun.star.frame.XModel xModel     = null;

    c = lEnvironment.length;

    for (int i=0; i<c; ++i) {

        if (lEnvironment[i].Name.equals("EnvType"))

            sEnvType = com.sun.star.uno.AnyConverter.toString(lEnvironment[i].Value);

        else

            if (lEnvironment[i].Name.equals("EventName"))

                sEventName = com.sun.star.uno.AnyConverter.toString(lEnvironment[i].Value);

            else

                if (lEnvironment[i].Name.equals("Frame"))

                    xFrame = (com.sun.star.frame.XFrame)com.sun.star.uno.AnyConverter.toObject(

                       new com.sun.star.uno.Type(com.sun.star.frame.XFrame.class), lEnvironment[i].Value);
               else

                    if (lEnvironment[i].Name.equals("Model"))

                        xModel = (com.sun.star.frame.XModel)com.sun.star.uno.AnyConverter.toObject(

                            new com.sun.star.uno.Type(com.sun.star.frame.XModel.class),

                            lEnvironment[i].Value);
   }

    // Further the environment property "EnvType" is required as minimum.

    if (

        (sEnvType==null) ||

        (

         (!sEnvType.equals("EXECUTOR"     )) &&

         (!sEnvType.equals("DISPATCH"     )) &&

         (!sEnvType.equals("DOCUMENTEVENT"))

        )

       )

    {

        throw new com.sun.star.lang.IllegalArgumentException("no valid value for EnvType");

    }

    // Analyze the set of shared config data.

    java.lang.String sAlias = null;

    if (lGenericConfig!=null) {

        c = lGenericConfig.length;

        for (int i=0; i<c; ++i) {

            if (lGenericConfig[i].Name.equals("Alias"))

                sAlias = com.sun.star.uno.AnyConverter.toString(lGenericConfig[i].Value);

        }

    }

}

Returning Results

Once a synchronous job has finished its work, it returns its result using the any return value of the com.sun.star.task.XJob:execute() method. An asynchronous jobs send back the result through the callback method jobFinished() to its com.sun.star.task.XJobListener. The returned any parameter must contain a sequence< com.sun.star.beans.NamedValue > with the following elements:

Elements of the Job Return Value

Deactivate

boolean. Asks the job executor to disable a job from further execution. Note that this feature is only available if the next event is triggered by the job executor or the event broadcaster. If it comes, for example, from the dispatch framework using an URL with an  <alias> argument, the deactivation will be ignored.
This value should be used carefully if the Environment-EnvType  is "DISPATCH", because users will be irritated if clicking a UI element, such as an Add-On menu entry, has no effect.

SaveArguments

sequence< com.sun.star.beans.NamedValue >. Must contain a list of job specific data, which are written directly to the Arguments list into the job configuration. Note: Merging is not supported. The list must be complete and replaces all values in the configuration. The necessary data can be copied and adjusted from the JobConfig element of the execution arguments.

SendDispatchResult

com.sun.star.frame.DispatchResultEvent. If a job is designed to be usable in the dispatch framework, this contains a struct, which is send to all interested dispatch result listeners.

Tip: This value should be omitted if Environment-EnvType is not "DISPATCH".

Configuration

Although jobs that are called through a vnd.sun.star.jobs: URL by their implementation name do not require it, a job usually has configuration data. The configuration package org.openoffice.Office.Jobs contains all necessary information:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE oor:component-schema SYSTEM "../../../../component-schema.dtd">

<oor:component-schema xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" oor:name="Jobs" oor:package="org.openoffice.Office" xml:lang="en-US">

  <templates>

    <group oor:name="Job">

      <prop oor:name="Service" oor:type="xs:string"/>

      <group oor:name="Arguments" oor:extensible="true"/>

    </group>

    <group oor:name="TimeStamp">

      <prop oor:name="AdminTime" oor:type="xs:string"/>

      <prop oor:name="UserTime" oor:type="xs:string"/>

    </group>

    <group oor:name="Event">

      <set oor:name="JobList" oor:node-type="TimeStamp"/>

    </group>

  </templates>

  <component>

    <set oor:name="Jobs" oor:node-type="Job"/>

    <set oor:name="Events" oor:node-type="Event"/>

  </component>

</oor:component-schema>

The Job template contains all properties that describe a job component. Instances of this template are located inside the configuration set Jobs.

Properties of the Job template

Alias

string. This property is declared as the name of the corresponding set node inside the configuration set Jobs. It must be a unique name, which represents the structured information of a job. In the example .xcu file below its value is "SyncJob". In the job execution arguments this property is passed as Config - Alias

Service

string. Represents the UNO implementation name of the job component. In the job execution arguments this property is passed as Config - Service

Arguments

set of any entries. This list can be filled with any values and represents the private set of configuration data for this job. In the job execution arguments this property is passed as JobConfig

The job property Alias was created to provide you with more flexibility for a developing components. You can use the same UNO implementation, but register it with different Aliases. At runtime the job instance will be initialized with its own configuration data and can detect which representation is used.

Pay attention to the following important text section

You cannot use the generic UNO service names com.sun.star.task.Job or com.sun.star.task.AsyncJob for the Service job property, because the job executor cannot identify the correct job implementation. To avoid ambiguities, it is necessary to use the UNO implementation name of the component.

Every job instance can be bound to multiple events. An event indicates a special office state, which can be detected at runtime (for example, OnFirstVisibleTask ), and which can be triggered by a call to the job executor when the first document window is displayed.

Properties of the Event template

EventName

string. This property is declared as the name of the corresponding set node inside the configuration set Events. It must be a unique name, which describes a functional state. In the example .xcu file below its value is "onFirstVisibleTask".

Section 4.7.2 Writing UNO Components - Integrating Components into OpenOffice.org - Jobs - List of Supported Events summarizes the events currently triggered by the office. In addition, developers can use arbitrary event strings with the vnd.sun.star.jobs: URL or in calls to trigger() at the com.sun.star.task.JobExecutor service.

JobList

set of TimeStamp entries. This set contains a list of all Alias names of jobs that are bound to this event. Every job registration can be combined with time stamp values. Please refer to the description of the template TimeStamp below for details

As an optional feature, every job registration that is bound to an event can be enabled or disabled by two time stamp values. In a shared installation of OpenOffice.org, an administrator can use the AdminTime value to reactivate jobs for every newly started user office instance; regardless of earlier executions of these jobs. That can be useful, for example, for updating user installations if new functions have been added to the shared installation.

Properties of the TimeStamp template

AdminTime

string. This value must be formatted according to the ISO 8601. It contains the time stamp, which can only be adjusted by an administrator, to reactivate this job.

UserTime

string. This value must be formatted according to the ISO 8601. It contains the time, when this job was finished successfully last time upon the configured event.

Using this time stamp feature can sometimes be complicated. For example, assume that there is a job that uses the pkgchk mechanism of OpenOffice.org for installation. The job is enabled for a registered event by default, but after the first execution it is disabled. By default, both values (AdminTime and UserTime) do not exist for a configured event. A Jobs.xcu fragment, as part of the package file, must also not contain the AdminTime and UserTime entries. Because both values are not there, no check can be made and the job is enabled. A job can be deactivated by the global job executor once it has finished its work successfully (depending on the Deactivate return value). In that case, the UserTime entry is generated and set to the current time. An administrator can set a newer and valid AdminTime value in order to reactivate the job again, or the user can remove his UserTime entry manually from the configuration file of the user installation.

The following Jobs.xcu file shows an example job configuration:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE oor:component-data SYSTEM "../../../../component-update.dtd">

<oor:component-data oor:name="Jobs" oor:package="org.openoffice.Office" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <node oor:name="Jobs">

    <node oor:name="SyncJob" oor:op="replace">

      <prop oor:name="Service">

        <value>com.sun.star.comp.framework.java.services.SyncJob</value>

      </prop>

      <node oor:name="Arguments">

        <prop oor:name=”arg_1” oor:type=”xs:string” oor:op="replace">

          <value>val_1</value>

        </prop>

      </node>

    </node>

  </node>

  <node oor:name="Events">

    <node oor:name="onFirstVisibleTask" oor:op="replace">

      <node oor:name="JobList">

        <node oor:name="SyncJob" oor:op="replace"/>

      </node>

    </node>

  </node>

</oor:component-data>

This example job has the following characteristics:

Pay attention to the following important text section

A job is not executed when it has deactivated itself and is called afterwards by a vnd.sun.star.jobs:event=... command URL. This can be confusing to users, especially with add-ons, since it would seem that the customized UI items do not function.

Installation

The easiest way to register an external job component is to use the already mentioned pkgchk mechanism of OpenOffice.org, described in section 4.9.1 Writing UNO Components - Deployment Options for Components - UNO Package Installation. A package file for the example job of this chapter can have the following directory structure:

SyncJob.zip:

    Jobs.xcu

    windows.plt/

        SyncJob.jar

Using the vnd.sun.star.jobs: URL Schema

This section describes the necessary steps to execute a job by issuing a command URL at the dispatch framework. Based upon the protocol handler mechanism, a specialized URL schema has been implemented in OpenOffice.org. It is registered for the URL schema "vnd.sun.star.jobs:*" which uses the following syntax:

vnd.sun.star.jobs:{[event=<name>]}{,[alias=<name>]}{,[service=<name>]}

Elements of a vnd.sun.star.jobs: URL

event=<name>

string. Contains an event string, which can also be used as parameter of the interface method com.sun.star.task.XJobExecutor:trigger(). It corresponds to the node name of the set Events in the configuration package org.openoffice.Office.Jobs. Using the event parameter of a vnd.sun.star.jobs: URL will start all jobs that are registered for this event in the configuration.
Note: Disabled jobs, that is jobs with a user time stamp that is newer than the administrator time stamp, are not triggered by event URLs.

alias=<name>

string. Contains an alias name of a configured job. This name is not used by the job execution API. It is a node name of the set Jobs in the configuration package org.openoffice.Office.Jobs . Using the alias part of a vnd.sun.star.jobs: URL only starts the requested job.

service=<name>

string. Contains the UNO implementation name of a configured or unconfigured com.sun.star.task.Job or com.sun.star.task.AsyncJob service. It is not necessary that such jobs are registered in the configuration, provided that they work without configuration data or implements necessary configuration on their own.

It is possible to combine elements so as to start several jobs at once with a single URL. For instance, you could dispatch a URL vnd.sun.star.jobs:event=e1,alias=a1,event=e2 ,.... However, URLs that start several jobs at once should be used carefully, since there is no check for double or concurrent requests. If a service is designed asynchronously, it will be run concurrently with another, synchronous job. If both services work at the same area, there might be race conditions and they must synchronize their work. The generic job execution mechanism does not provide this functionality.

The following configuration file for the configuration package org.openoffice.Office.Jobs shows two jobs, which are registered for different events:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE oor:component-data SYSTEM "../../../../component-update.dtd">

<oor:component-data oor:name="Jobs" oor:package="org.openoffice.Office" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <node oor:name="Jobs">

    <node oor:name="Job_1" oor:op="replace">

      <prop oor:name="Service">

        <value>vnd.sun.star.jobs.Job_1</value>

      </prop>

      <node oor:name="Arguments">

        <prop oor:name=”arg_1” oor:type=”xs:string” oor:op="replace">

          <value>val_1</value>

        </prop>

      </node>

    </node>

    <node oor:name="Job_2" oor:op="replace">

      <prop oor:name="Service">

        <value>vnd.sun.star.jobs.Job_2</value>

      </prop>

      <node oor:name="Arguments"/>

    </node>

  </node>

  <node oor:name="Events">

    <node oor:name="onFirstVisibleTask" oor:op="replace">

      <node oor:name="JobList">

        <node oor:name="Job_1" oor:op="replace">

          <prop oor:name="AdminTime">

            <value>01.01.2003/00:00:00</value>

          </prop>

          <prop oor:name="UserTime">

            <value>01.01.2003/00:00:01</value>

          </prop>

        </node>

        <node oor:name="Job_2" oor:op="replace"/>

      </node>

    </node>

  </node>

</oor:component-data>

The first job can be described by the following properties:

Properties of “Job_1”

alias

Job_1

UNO implementation name

vnd.sun.star.jobs.Job_1

activation state

Disabled for job execution (because its AdminTime is older than its UserTime)

own configuration

contains one string item arg1 with the value "val1"

event registration

job is registered for the event string "onFirstVisibleTask"

The second job can be described by these properties:

Properties of “Job_2”

alias

Job_2

UNO implementation name

vnd.sun.star.jobs.Job_2

activation state

Enabled for job execution (because it uses default values for AdminTime and UserTime)

own configuration

no own configuration items registered

event registration

job is registered for the event string "onFirstVisibleTask"

The following demonstrates use cases for all possible vnd.sun.star.job: URLs. Not all possible scenarios are shown here. The job dispatch can be used in different ways and the combination of jobs can produce different results:

vnd.sun.star.jobs:event=onFirstVisibleTask

This URL starts  Job_2 only, Job_1 is marked DISABLED, since its AdminTime stamp is older than its UserTime stamp.

The job is initialized with environment information through the Environment sub list, as shown in section 4.7.2 Writing UNO Components - Integrating Components into OpenOffice.org - Jobs - Initialization. Optional dispatch arguments are passed in DynamicData, and generic configuration data, including the event string, is received in Config. However, it is not initialized with configuration data of its own in JobConfig because Job_2 is not configured with such information. On the other hand, Job_2 may return data after finishing its work, which will be written back to the configuration.

Furthermore, the job instance can expect that the Frame property from the Environment sub list points to the frame in which the dispatch request is to be executed.

vnd.sun.star.jobs:alias=Job_1

This starts Job_1 only. It is initialized with an environment, and optionally initialized with dispatch arguments, generic configuration data, and configuration data of its own. However, the event name is not set here because this job was triggered directly, not using an event name.

vnd.sun.star.jobs:service=vnd.sun.star.jobs.Job_3

A vnd.sun.star.jobs.Job_3 is not registered in the job configuration package. However, if this  implementation was registered with the global service manager, and if it provided the  com.sun.star.task.XJob or com.sun.star.task.XAsyncJob interfaces, it would be executed by this URL. If both interfaces are present, the synchronous version is preferred.

The given UNO implementation name vnd.sun.star.jobs.Job_3 is used directly for creation at the UNO service manager. In addition, this job instance is only initialized with an environment and possibly with optional dispatch arguments—there is no configuration data for the job to use.

List of supported Events

Supported events triggered by code

onFirstRunInitialization

Called on startup once after OpenOffice.org is installed. Should be used for post-setup operations.

onFirstVisibleTask

Called after a document window has been shown for the first time after launching the application. Note: The quickstarter influences this behavior. With the quickstarter, closing the last document does not close the application. Opening a new document in this situation does not trigger this event.

onDocumentOpened

Indicates that a new document was opened. It does not matter if a new or an existing document was opened. Thus it represents the combined OnNew and OnLoad events of the global event broadcaster.

Supported events triggered by the global event broadcaster

OnStartApp

Application has been started

OnCloseApp

Application is going to be closed

OnNew

New Document was created

OnLoad

Document has been loaded

OnSaveAs

Document is going to be saved under a new name

OnSaveAsDone

Document was saved under a new name

OnSave

Document is going to be saved

OnSaveDone

Document was saved

OnPrepareUnload

Document is going to be removed

OnUnload

Document has been removed

OnFocus

Document was activated

OnUnfocus

Document was deactivated

OnPrint

Document will be printed

OnModifyChange

Modified state of the document has changed

Pay attention to the following important text section

Event names are case sensitive.

4.7.3    Add-Ons

A OpenOffice.org add-on is an external UNO component providing one or more functions through the user interface of OpenOffice.org. A typical add-on is available as a UNO package for easier deployment with the pkgchk tool. In addition to an ordinary UNO package an add-on package contains configuration files which specify the user interface, registration for a protocol schema and first-time instantiation.

The package installation tool pkgchk merges the configuration files with the menu and toolbar items for an add-on directly into the OpenOffice.org configuration files.

Overview

OpenOffice.org supports the integration of add-ons into the following areas of the GUI.

Menu items for add-ons can be added to an Add-Ons submenu of the Tools menu and a corresponding add-ons popup toolbar icon:

Screenshot showing  example entries in the addon menu or toolbar
Illustration 4.7: Add-Ons submenu and toolbar popup

It is also possible to create custom menus in the Menu Bar. You are free to choose your own menu title, and you can create menu items and submenus for your add-on. Custom menus are inserted between the Tools and Window menus. Separators are supported as well:

Screenshot showing a new menu entry
Illustration 4.8: Custom top-level menu

You can create toolbar icons in the Function Bar, which is usually the topmost toolbar. Below you see two toolbar items, an icon for Function 1 and a text item for Function 2 :

Scrennshot showing a new toolbar entry
Illustration 4.9: Toolbar icons for Function 1 and Function 2

The Help menu offers support for add-ons through help menu items that open the online help of an add-on. They are inserted below the Help - Registration item under a separator.

Guidelines

For a smooth integration, a developer should be aware of the following guidelines:

Add-Ons Submenu
Custom Top-Level Menu
Toolbar
Add-On Help menu

Every add-on should provide help to user. This help has to be made available through an entry in the  OpenOffice.org Help menu. Every add-on should only use a single Help menu item.

If the add-on comes with its own dialogs, it should also offer Help buttons in the dialogs.

Configuration

The user interface definitions of all add-ons are stored in the special configuration branch org.openoffice.Office.Addons .

The schema of the configuration branch org.openoffice.Office.Addons specifies how to define a user interface extension.

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-schema oor:name="Addons" oor:package="org.openoffice.Office" xml:lang="en-US" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <templates>

        <group oor:name="MenuItem">

            <prop oor:name="URL" oor:type="xs:string"/>

            <prop oor:name="Title" oor:type="xs:string" oor:localized="true"/>

            <prop oor:name="ImageIdentifier" oor:type="xs:string"/>

            <prop oor:name="Target" oor:type="xs:string"/>

            <prop oor:name="Context" oor:type="xs:string"/>

            <set oor:name="Submenu" oor:node-type="MenuItem"/>

        </group>

        <group oor:name="PopupMenu">

            <prop oor:name="Title" oor:type="xs:string" oor:localized="true"/>

            <prop oor:name="Context" oor:type="xs:string"/>

            <set oor:name="Submenu" oor:node-type="MenuItem"/>

        </group>

        <group oor:name="ToolBarItem">

            <prop oor:name="URL" oor:type="xs:string"/>

            <prop oor:name="Title" oor:type="xs:string" oor:localized="true"/>

            <prop oor:name="ImageIdentifier" oor:type="xs:string"/>

            <prop oor:name="Target" oor:type="xs:string"/>

            <prop oor:name="Context" oor:type="xs:string"/>

        </group>

        <group oor:name="UserDefinedImages">

            <prop oor:name="ImageSmall" oor:type="xs:hexBinary"/>

            <prop oor:name="ImageBig" oor:type="xs:hexBinary"/>

            <prop oor:name="ImageSmallHC" oor:type="xs:hexBinary"/>

            <prop oor:name="ImageBigHC" oor:type="xs:hexBinary"/>

            <prop oor:name=”ImageSmallURL” oor:type=”xs:string”/>

            <prop oor:name=”ImageBigURL” oor:type=”xs:string”/>

            <prop oor:name=”ImageSmallHCURL” oor:type=”xs:string”/>

            <prop oor:name=”ImageBigHCURL” oor:type=”xs:string”/>

        </group>

        <group oor:name="Images">

            <prop oor:name="URL" oor:type="xs:string"/>

            <node-ref oor:name="UserDefinedImages" oor:node-type="UserDefinedImages"/>

        </group>

        <set oor:name="ToolBarItems" oor:node-type="ToolBarItem"/>

    </templates>

    <component>

        <group oor:name="AddonUI">

            <set oor:name="AddonMenu" oor:node-type="MenuItem"/>

            <set oor:name="Images" oor:node-type="Images"/>

            <set oor:name="OfficeMenuBar" oor:node-type="PopupMenu"/>

            <set oor:name="OfficeToolBar" oor:node-type="ToolBarItems"/>

            <set oor:name="OfficeHelp" oor:node-type="MenuItem"/>

        </group>

    </component>

</oor:component-schema>

Menus

As explained in the previous section, OpenOffice.org supports two menu locations where an add-on can be integrated: a top-level menu or the Tools - Add-Ons submenu. The configuration branch org.openoffice.Office.Addons provides two different nodes for these locations:

Supported sets of org.openoffice.Office.Addons to define an Add-On menu

OfficeMenuBar

A menu defined in this set will be a top-level menu in the OpenOffice.org Menu Bar.

AddonMenu

A menu defined in this set will be a pop-up menu which is part of the Add-Ons menu item located on the bottom position of the Tools menu.

Submenu in Tools - Add-Ons

To integrate add-on menu items into the Tools – Add-Ons menu, use the AddonMenu set. The AddonMenu set consists of nodes of type MenuItem. The MenuItem node-type is also used for the submenus of a top-level add-on menu.

Properties of template MenuItem

oor:name

string. The name of the configuration node. The name must begin with an ASCII letter character.  It must be unique within the OfficeMenuBar set. Therefore, it is mandatory to use a schema such as org.openoffice.<developer>.<product>.<addon name> or com.<company>.<product>.<addon name> to avoid name conflicts. Keep in mind that your configuration file will be merged into the OpenOffice.org configuration branch. You do not know which add-ons, or how many add-ons, are currently installed.
The node name of menu items of a submenu must be unique only within their submenu. A configuration set cannot guarantee the order of its entries, so you should use a schema such as string + number, for example “m1”, as the name is used to sort the entries.  

URL

string. Specifies the command URL that should be dispatched when the user activates the menu entry. It will be ignored if the MenuItem is the title of a a submenu.
To define a separator you can use the special command URL "private:separator". A separator ignores all other properties.

Title

string. Contains the title of a top-level menu item.  This property supports localization: The default string, which is used when OpenOffice.org cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the xml:lang attribute. Assign the language/locale to the attribute, for example  <value xml:lang="en-US">string</value>.

ImageIdentifier

string. Defines an optional image URL that could address an internal OpenOffice.org image or an external user-defined image. The syntax of an internal image URL is: private:image/<number> where number specifies the image.

External user-defined images are supported using the placeholder variable %origin% representing the folder where the component will be installed by the pkgchk tool. The pkgchk tool will exchanges %origin% by another placeholder, which is substituted during runtime by OpenOffice.org to the real installation folder. Since OpenOffice.org supports two different configuration folders ( user and share ) this mechanism is necessary to determine the installation folder of a component.

For example the URL %origin%/image will be substituted to something like

vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/image .

The placeholder vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE will then be substituted during runtime by the real path.

As the ImageIdentifier property can only hold one URL but OpenOffice.org supports four different images (small/large image and both as high contrast), a naming schema is used to address them. OpenOffice.org adds _16.bmp and _26.bmp to the provided URL to address the small and large image. _16h.bmp and _26h.bmp is added to address the high contrast images. If the high contrast images are omitted the normal images are used instead.

OpenOffice.org supports bitmaps with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, which means that the background color of the display is used instead of the image pixel color when the image is drawn.

For optimal results the size of small images should be 16x16 pixel and for big images 26x26 pixel. Other image sizes are scaled automatically by OpenOffice.org.
If no high contrast image is provided, OpenOffice.org uses the normal image for high contrast environments. Images that are not valid will be ignored.
This property has a higher priority than the Images set when OpenOffice.org searches for images.

Target

string. Specifies the target frame for the command URL. Normally an add-on will use one of the predefined target names:

_top
Returns the top frame of the called frame, which is the first frame where isTop() returns true when traversing up the hierarchy.

_parent
Returns the next frame above in the frame hierarchy.

_self
Returns the frame itself, same as an empty target frame name. This means you are searching for a frame you already have, but it is legal to do so.

_blank
Creates a new top-level frame whose parent is the desktop frame.

Context

string. A list of service names, separated by a comma, that specifies in which context the add-on menu function should be visible. An empty Context means that the function should visible in all contexts.
The OpenOffice.org application modules use the following services names:

Writer:                com.sun.star.text.TextDocument

Spreadsheet:        com.sun.star.sheet.SpreadsheetDocument

Presentation:        com.sun.star.presentation.PresentationDocument

Draw:                com.sun.star.drawing.DrawingDocument

Formula:        com.sun.star.formula.FormulaProperties

Chart:                com.sun.star.chart.ChartDocument

Bibliography:        com.sun.star.frame.Bibliography

The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with UI element (toolbar, menu bar, ...). Thus the service name of the Writer model is com.sun.star.text.TextDocument. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.

Submenu

A set of  MenuItem entries. Optional to define a submenu for the menu entry.

The next examples shows a configuration file specifying a single menu item titled Add-On Function 1. The unique node name of the add-on is called org.openoffice.example.addon.example.function1.

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">

    <node oor:name="AddonUI">

        <node oor:name="AddonMenu">

            <node oor:name="org.openoffice.Office.addon.example.function1" oor:op="replace">
               <prop oor:name="URL" oor:type="xs:string">
                   <value>org.openoffice.Office.addon.example:Function1</value>
               </prop>

                <prop oor:name="ImageIdentifier" oor:type="xs:string"

                    <value/>
               </prop>

                <prop oor:name="Title" oor:type="xs:string">
                   <value/>
                   <value xml:lang="en-US">Add-On Function 1</value>
               </prop>
               <prop oor:name="Target" oor:type="xs:string">
                   <value>_self</value>
               </prop>
               <prop oor:name="Context" oor:type="xs:string">
                   <value>com.sun.star.text.TextDocument</value>
               </prop>
           </node>
       </node>

    </node>

Top-level Menu

If you want to integrate an add-on into the OpenOffice.org Menu Bar, you have to use the OfficeMenuBar set. An OfficeMenuBar set consists of nodes of type PopupMenu .

Properties of template PopupMenu

oor:name

string. The name of the configuration node. The name must begin with an ASCII letter character.  It must be unique within the OfficeMenuBar set. Therefore, it is mandatory to use a schema such as org.openoffice.<developer>.<product>.<addon name> or com.<company>.<product>.<addon name> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the OpenOffice.org configuration branch. You do not know what add-ons, or how many add-ons, are currently installed.

Title

string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when OpenOffice.org cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the xml:lang attribute. Assign the language/locale to the attribute, for example  <value xml:lang="en-US">string</value>.

Context

string. A list of service names, separated by a comma, that specifies in which context the add-on menu should be visible. An empty context means that the function should be visible in all contexts.
The OpenOffice.org application modules use the following services names:

Writer:                com.sun.star.text.TextDocument

Spreadsheet:        com.sun.star.sheet.SpreadsheetDocument

Presentation:        com.sun.star.presentation.PresentationDocument

Draw:                com.sun.star.drawing.DrawingDocument

Formula:        com.sun.star.formula.FormulaProperties

Chart:                com.sun.star.chart.ChartDocument

Bibliography:        com.sun.star.frame.Bibliography

The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with UI element (toolbar, menu bar, ...). Thus the service name of the Writer model is com.sun.star.text.TextDocument. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model it is possible to use its service name as a context for add-on UI items.

Submenu

A set of  MenuItem entries. Defines the submenu of the top-level menu. It must be defined on a top-level menu otherwise the whole menu will be ignored.
For more information how to define a submenu please refer to section 4.7.3 Writing UNO Components - Integrating Components into OpenOffice.org - User Interface Add-Ons - Guidelines where the MenuItem template is described.

The following example defines a top-level menu titled Add-On example with a single menu item titled Add-On Function 1. The menu item has a self-defined image used for displaying it next to the menu title.
In the example the nodes are called oor:name="org.openoffice.example.addon" and oor:name="m1".

Do not forget to specify the oor:op="replace" attribute in your self-defined nodes. The replace operation must be used to add a new node to a set or extensible node. Thus the real meaning of the operation is "add or replace". Dynamic properties can only be added once and are then considered mandatory, so during layer merging the replace operation always means "add" for them.
For more details about the configuration and their file formats please read
15 Configuration Management.

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">

    <node oor:name="AddonUI">

        <node oor:name="OfficeMenuBar">

            <node oor:name="org.openoffice.example.addon" oor:op="replace">

                <prop oor:name="Title" oor:type="xs:string">

                    <value/>

                    <value xml:lang="en-US">Add-On example</value>

                    <value xml:lang=”de”>Add-On Beispiel</value>

                </prop>

                <prop oor:name="Context" oor:type="xs:string">

                    <value>com.sun.star.text.TextDocument</value>

                </prop>

                <node oor:name="Submenu">

                    <node oor:name="m1" oor:op="replace">

                        <prop oor:name="URL" oor:type="xs:string">

                            <value>org.openoffice.Office.addon.example:Function1</value>

                        </prop>

                        <prop oor:name="Title" oor:type="xs:string">

                            <value/>

                            <value xml:lang=”en-US”>Add-On Function 1</value>

                            <value xml:lang="de">Add-On Funktion 1</value>

                        </prop>

                        <prop oor:name="Target" oor:type="xs:string">

                            <value>_self</value>

                        </prop>

                    </node>

                </node>

            </node>

        </node>

    </node>

</oor:component-data>

Toolbars

An add-on can also be integrated into the Function Bar of OpenOffice.org. The org.openoffice.Office.Addons configuration branch has a set called OfficeToolBar where you can add toolbar items for an add-on. The toolbar structure uses an embedded set called ToolbarItems , which is used by OpenOffice.org to group toolbar items from different add-ons. OpenOffice.org automatically inserts a separator between different add-ons toolbar items.

Pay attention to the following important text section

The space of the Function Bar is limited, so only the most used/important functions should be added to the OfficeToolBar set. Otherwise OpenOffice.org will add scroll-up/down buttons at the end of the Function Bar and the user has to scroll the toolbar to have access to all toolbar buttons.

Properties of template ToolBarItems

oor:name

string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the OfficeMenuBar set. Therefore it is mandatory to use a schema such as org.openoffice.<developer>.<product>.<addon name> or com.<company>.<product>.<addon name> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the OpenOffice.org configuration branch. You do not know what add-ons, or how many add-ons, are currently installed.

The ToolBarItems set is a container for the ToolBarItem nodes.

Properties of template ToolBarItem

oor:name

string. The name of the configuration node. It must be unique inside your own ToolBarItems set. A configuration set cannot guarantee the order of its entries, therefore use a schema such as string + number, for example "m1", as the name is used to sort the entries. Please be aware that the name must begin with an ASCII letter character.

URL

string. Specifies the command URL that should be dispatched when the user activates the menu entry. To define a separator you can use the special command URL "private:separator". A separator ignores all other properties.

Title

string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when OpenOffice.org cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the xml:lang attribute. Assign the language/locale to the attribute, for example <value xml:lang="en-US">string</value>.

ImageIdentifier

string. Defines an optional image URL that could address an internal OpenOffice.org image or an external user-defined image. The syntax of an internal image URL is: private:image/<number> where number specifies the image.

External user-defined images are supported using the placeholder variable %origin%, representing the folder where the component will be installed by the pkgchk tool. The pkgchk tool exchanges %origin% with another placeholder, which is substituted during runtime by OpenOffice.org to the real installation folder. Since OpenOffice.org supports two different configuration folders ( user and share ) this mechanism is necessary to determine the installation folder of a component.

For example the URL %origin%/image will be substituted with something like

vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/image .

The placeholder vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE is then substituted during runtime with the real path.

Since the ImageIdentifier property can only hold one URL but OpenOffice.org supports four different images (small/large image, and both as high contrast), a naming schema is used to address them. OpenOffice.org adds _16.bmp and _26.bmp to the provided URL to address the small and large image. _16h.bmp and _26h.bmp is added to address the high contrast images. If the high contrast images are omitted, the normal images are used instead.

OpenOffice.org supports bitmaps with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, which means that the background color of the display is used instead of the image pixel color when the image is drawn.

For optimal results, the size of small images should be 16x16 pixel, and for big images 26x26 pixel. Other image sizes are scaled automatically by OpenOffice.org.
If no high contrast image is provided, OpenOffice.org uses the normal image for high contrast
environments. Images that are not valid are ignored.
This property has a higher priority than the
Images set when OpenOffice.org searches for images.

Target

string. Specifies the target frame for the command URL. Normally an add-on will use one of the predefined target names:

_top
Returns the top frame of the called frame, which is the first frame where isTop() returns true when traversing up the hierarchy.

_parent
Returns the next frame above in the frame hierarchy.

_self
Returns the frame itself, same as an empty target frame name. This means you are searching for a frame you already have, but it is legal to do so.

_blank
Creates a new top-level frame whose parent is the desktop frame.

Context

string. A list of service names, separated by a comma, that specifies in which context the add-on menu should be visible. An empty context means that the function should be visible in all contexts.
The OpenOffice.org application modules use the following services names:

Writer:                com.sun.star.text.TextDocument

Spreadsheet:        com.sun.star.sheet.SpreadsheetDocument

Presentation:        com.sun.star.presentation.PresentationDocument

Draw:                com.sun.star.drawing.DrawingDocument

Formula:        com.sun.star.formula.FormulaProperties

Chart:                com.sun.star.chart.ChartDocument

Bibliography:        com.sun.star.frame.Bibliography

The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with an UI element (toolbar, menu bar, ...). Thus the service name of the Writer model is com.sun.star.text.TextDocument. That means, the context name is bound to the model of an application module. If you implement a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.

The following example defines one toolbar button for the function called org.openoffice.Office.addon.example:Function1 . The toolbar button is only visible when using the OpenOffice.org Writer module.

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">

    <node oor:name="AddonUI">

        <node oor:name="OfficeToolBar">

            <node oor:name="org.openoffice.Office.addon.example" oor:op="replace">

                <node oor:name=”m1”>

                    <prop oor:name="URL" oor:type="xs:string">

                        <value>org.openoffice.Office.addon.example:Function1</value>

                    </prop>

                    <prop oor:name="Title" oor:type="xs:string">

                        <value/>

                        <value xml:lang=”en-US”>Function 1</value>

                        <value xml:lang="de">Funktion 1</value>

                    </prop>

                    <prop oor:name="Target" oor:type="xs:string">

                        <value>_self</value>

                    </prop>

                    <prop oor:name="Context" oor:type="xs:string">

                        <value>com.sun.star.text.TextDocument</value>

                    </prop>

                </node>

            </node>

        </node>

    </node>

</oor:component-data>

Images for Toolbars and Menus

OpenOffice.org supports images in menus and toolboxes. In addition to the property ImageIdentifier, the add-ons configuration branch has a fourth set called Images that let developers define and use their own images. The image data can be integrated into the configuration either as hex encoded binary data  or as references to external bitmap files. The Images set binds a command URL to user defined images.

Properties of template Images

oor:name

string. The name of the configuration node. It must be unique inside the configuration branch. Therefore it is mandatory to use a schema such as org.openoffice.<developer>.<add-on name> or com.<company>.<product>.<add-on name> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the OpenOffice.org configuration branch. You do not know how many or which add-ons were installed before by the user.
Please be aware that the name must begin with an ASCII letter character.

URL

string. Specifies the command URL that should be bound to the defined images. OpenOffice.org searches for images with the command URL that a menu item/toolbox item contains.

UserDefinedImages

Group of  properties. This optional group provides self-defined images data to OpenOffice.org. There are two different groups of properties to define the image data. One property group provides the image data as ongoing hex values specifying an uncompressed bitmap format stream. The other property group uses URLs to external bitmap files. The names of these properties end with 'URL'. OpenOffice.org supports bitmap streams with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, meaning that the background color of the display will be used instead of the image pixel color when the image is drawn.
For best quality, the size of small images should be 16x16 pixel, and for big images 26x26 pixel. Other image sizes will be scaled automatically by OpenOffice.org.
If no high contrast image data is provided, OpenOffice.org uses the normal image for high contrast environments. Image data that is not valid will be ignored.

An Images node uses a second node called UserDefinedImages where the user defined images data are stored.

Properties of template UserDefinedImages

ImageSmall

HexBinary. Used for normal menu/toolbar items, standard size is 16x16 pixel.

ImageBig

HexBinary. Only toolbars can use big images. Standard size is 26x26 pixel. The user can activate large buttons with the Tools – Options – View – Large Buttons check box.

ImageSmallHC

HexBinary. Used for high contrast environments, which means that the background color of a menu or toolbar is below a certain threshold value for the brightness.

ImageBigHC

HexBinary. Only toolbars can use big images. Used for high contrast environments, which means that the background color of a toolbar is below a certain threshold value for the brightness.

ImageSmallURL

string. An URL to an external image which is used for menu items and normal toolbar buttons. External user-defined images are supported using the placeholder variable %origin%, representing the folder where the component will be installed by the pkgchk tool. The pkgchk tool exchanges %origin% with another placeholder, which is substituted during runtime by OpenOffice.org to the real installation folder. Since OpenOffice.org supports two different configuration folders ( user and share ) this mechanism is necessary to determine the installation folder of a component.

For example the URL %origin%/image will be substituted with something like

vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/image .

The placeholder vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE is then substituted during runtime with the real path.

ImageBigURL

string. An URL to an external image which is used for big toolbar buttons.

ImageSmallHCURL

string. An URL to an external image which is used for menu items and normal toolbar button in a high contrast environment.

ImageBigHCURL

string. An URL to an external image which is used for big toolbar buttons in a high contrast environment.

The embedded image data have a higher priority when used in conjunction with the URL properties. The embedded and URL properties can be mixed without a problem.

The next example creates two user-defined images for the function org.openoffice.Office.addon.example:Function1 . The normal image is defined using the embedded image data property ImageSmall and has a size of 16x16 pixel and a 4-bit color depth. The other one uses the URL property ImageSmallHCURL to reference an external bitmap file for the high contrast image.

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">

    <node oor:name="AddonUI">

        <node oor:name="Images">

            <node oor:name="com.sun.star.comp.framework.addon.image1" oor:op="replace">

                <prop oor:name="URL" oor:type="xs:string">

                    <value>org.openoffice.Office.addon.example:Function1</value>

                </prop>

                <node oor:name=”UserDefinedImages”>

                    <prop oor:name=”ImageSmall”>

                        <value>424df8000000000000007600000028000000100000001000000001000400000000000000 0000120b0000120b000000000000000000000000ff0000ffff0000ff0000ffff0000ff000000ff00ff00ffffff00c0c0c000808 0800000000000000080000080800000800000808000008000000080008000cccccccccccccccc2c266b181b666c2c5cc66b818b 6665c555566b181b66655555566b818b66655555566b181b6665555a8666bbb6668a55a0a866666668a0a5000a8666668a000a6 000a86668a000a556000a868a000a55556000a8a000a5555556000a000a55555555600000a55555555556000a55555555555560 a55555550000</value>

                    </prop>

                    <prop oor:name=”ImageSmallHCURL”>

                        <value>%origin%/function1.bmp</value>

                    </prop>

                </node>

            </node>

        </node>

    </node>

</oor:component-data>

Help Integration

OpenOffice.org supports the integration of add-ons into its Help menu. The add-on help menu items are inserted below the Registration menu item, guarded by separators. This guarantees that users have quick access to the add-on help.  
The OfficeHelp set uses the same MenuItem node-type as the AddonMenu set, but there are some special treatments of the properties.

Properties of template MenuItem

oor:name

string. The name of the configuration node. It must be unique inside the configuration branch. Therefore it is mandatory to use a schema such as org.openoffice.<developer>.<add-on name> or com.<company>.<product>.<add-on name> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the OpenOffice.org configuration branch. You do not know how many or which add-ons were installed before by the user.
Please be aware that the name must begin with an ASCII letter character.

URL

string. Specifies the help command URL that should be dispatched when the user activates the menu entry.
Separators defined by the special command URL "private:separator" are supported, but should not be used in the help menu, because every add-on should only use one menu item.

Title

string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when OpenOffice.org cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the xml:lang attribute. Assign the language/locale to the attribute, for example  <value xml:lang="en-US">string</value>.

ImageIdentifier

string. Defines an optional image URL that could address an internal OpenOffice.org image or an external user-defined image. The syntax of an internal image URL is: private:image/<number> where number specifies the image.

External user-defined images are supported using the placeholder variable %origin%, representing the folder where the component will be installed by the pkgchk tool. The pkgchk tool exchanges %origin% with another placeholder, which is substituted during runtime by OpenOffice.org to the real installation folder. Since OpenOffice.org supports two different configuration folders ( user and share ), this mechanism is necessary to determine the installation folder of a component.

For example the URL %origin%/image is substituted with something like

vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/image .

The placeholder vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE is then substituted during runtime by the real path.

Since the ImageIdentifier property can only hold one URL but OpenOffice.org supports four different images (small/large image and both as high contrast), a naming schema is used to address them. OpenOffice.org adds _16.bmp and _26.bmp to the provided URL to address the small and large image. _16h.bmp and _26h.bmp is added to address the high contrast images. If the high contrast images are omitted, the normal images are used instead.

OpenOffice.org supports bitmaps with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, which means that the background color of the display is used instead of the image pixel color when the image is drawn.

For optimal results the size of small images should be 16x16 pixel and for big images 26x26 pixel. Other image sizes will be scaled automatically by OpenOffice.org.
If no high contrast image is provided, OpenOffice.org uses the normal image for high contrast
environments. Images that are not valid are ignored.
This property has a higher priority than the
Images set when OpenOffice.org searches for images.

Target

string. Specifies the target frame for the command URL. Normally an add-on will use one of the predefined target names:

_top
Returns the top frame of the called frame, which is the first frame where isTop() returns true when traversing up the hierarchy.

_parent
Returns the next frame above in the frame hierarchy.

_self
Returns the frame itself, same as an empty target frame name. This means you are searching for a frame you already have, but it is legal to do so.

_blank
Creates a new top-level frame whose parent is the desktop frame.

Context

string. A list of service names, separated by a comma, that specifies in which context the add-on menu should be visible. An empty context means that the function is visible in all contexts.
The OpenOffice.org application modules use the following services names:

Writer:                com.sun.star.text.TextDocument

Spreadsheet:        com.sun.star.sheet.SpreadsheetDocument

Presentation:        com.sun.star.presentation.PresentationDocument

Draw:                com.sun.star.drawing.DrawingDocument

Formula:        com.sun.star.formula.FormulaProperties

Chart:                com.sun.star.chart.ChartDocument

Bibliography:        com.sun.star.frame.Bibliography

The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with an UI element (toolbar, menu bar, ...). Thus the service name of the Writer model is com.sun.star.text.TextDocument. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.

Submenu

A set of  MenuItem entries. Not used for OfficeHelp MenuItems , any definition inside will be ignored.

The following example shows the single help menu item for the add-on example.

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">

    <node oor:name="AddonUI">

        <node oor:name="OfficeHelp">
           <node oor:name="com.sun.star.comp.framework.addon" oor:op="replace">
               <prop oor:name="URL" oor:type="xs:string"

                    <value>org.openoffice.Office.addon.example:Help</value>
               </prop>
               <prop oor:name="ImageIdentifier" oor:type="xs:string">

                    <value/>

                </prop>
               <prop oor:name="Title" oor:type="xs:string">
                   <value xml:lang="de">Über Add-On Beispiel</value>
                   <value xml:lang="en-US">About Add-On Example</value>
               </prop>
               <prop oor:name="Target" oor:type="xs:string">
                   <value>_self</value>
              </prop>
           </node>
       </node>

    </node>

</oor:component-data>

Installation

After finishing the implementation of the UNO component and the definition of the user interface part you can create the UNO package. A UNO package can be used by an end-user to install the add-on into OpenOffice.org.

An UNO package is a zip file containing UNO components, type libraries or basic libraries. The pkgchk tool unzips all packages found in the package directory into the cache directory, preserving the file structure of the zip file. It also copies all single files recognized in the package directory to the cache directory.

The configuration files that were created for the add-on, such as protocol handler, jobs, and user interface definition must be added to the root of the zip file. The structure of a zip file supporting Windows should resemble the following code:

example_addon.zip:

    Addons.xcu

    ProtocolHandler.xcu

    windows.plt/

        example_addon.dll

Before you install the package, make absolutely sure there are no running instances of OpenOffice.org. The pkchk tool recognizes a running OpenOffice.org in a local installation, but not in a networked installation. Installing into a running office installation might cause inconsistencies and destroy your installation!

The package installation for the example add-on is as simple as changing to the <OfficePath>/program directory with a command-line shell and running

[<OfficePath>/program] $ pkgchk /foo/bar/example_addon.zip

For an explanation of the package structure and more deployment options, please refer to 4.9 Writing UNO Components - Deployment Options for Components.

4.7.4    Disable Commands

In OpenOffice.org, there may be situations where functions should be disabled to prevent users from changing or destroying documents inadvertently. OpenOffice.org maintains a list of disabled commands that can be maintained by users and developers through the configuration API.

A command request can be created by any object, but in most cases, user interface objects create these requests. Consider, for instance, a toolbox where different functions acting on the office component are presented as buttons. Once a button is clicked, the desired functionality should be executed. If the code assigned to the button is provided with a suitable command URL, the dispatch framework can handle the user action by creating the request and finding a component that can handle it.

The dispatch framework works with the design pattern chain of responsibility: everything a component needs to know if it wants to execute a request is the last link in a chain of objects capable of executing requests. If this object gets the request, it checks whether it can handle it or otherwise passes it to the next chain member until the request is executed or the end of the chain is reached.
The disable commands implementation is the first chain member and can therefore work as a wall for all disabled commands. They are not be sent to the next chain member, and disappear.

shows how the disable commands feature affects the normal command application flow.

Overview graphic showing how disabling commands works
Illustration 4.10: How the disable commands feature works

Pay attention to the following important text section

Since the disable commands implementation is the first part in the dispatch chain, there is no way to circumvent it. The disabled command must be removed from the list, otherwise it remains disabled.

Configuration

The disable commands feature uses the configuration branch org.openoffice.Office.Commands to read which commands should be disabled. The following schema applies:

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-schema oor:name="Commands" oor:package="org.openoffice.Office" xml:lang="en-US" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <templates>

        <group oor:name="CommandType">

            <prop oor:name="Command" oor:type="xs:string"/>

        </group>

    </templates>

    <component>

        <group oor:name="Execute">

            <set oor:name="Disabled" oor:node-type="CommandType"/>

        </group>

    </component>

</oor:component-schema>

The configuration schema for disabled commands is very simple. The org.openoffice.Office.Commands branch has a group called Execute. This group has only one set called Disabled. The Disabled set supports nodes of the type CommandType. The following table describes the supported properties of CommandType.

Properties of the CommandType  group

oor:component-data

string. It must be unique inside the Disabled set, but has no additional meaning for the implementation of the disable commands feature. Use a consecutive numbering scheme; even numbers are allowed.

Command

string. This is the command name with the preceding protocol. That means the command URL .uno:Open (which shows the File – Open dialog) must be written as Open.
The valid commands can be found in the document Index of Command Names in the Documentation section of the framework project on the OpenOffice.org web page. The OpenOffice.org SDK also includes the latest list of command names.

The example below shows a configuration file that disables the commands for File – Open, Edit – Select All, Help – About OpenOffice.org and File – Exit.

<?xml version="1.0" encoding="UTF-8" ?>

<oor:component-data oor:name="Commands" oor:package="org.openoffice.Office" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <node oor:name="Execute">

        <node oor:name="Disabled">

            <node oor:name="m1" oor:op="replace">

                <prop oor:name="Command">

                    <value>Open</value>

                </prop>

            </node>

            <node oor:name="m2" oor:op="replace">

                <prop oor:name="Command">

                    <value>SelectAll</value>

                </prop>

            </node>

            <node oor:name="m3" oor:op="replace">

                <prop oor:name="Command">

                    <value>About</value>

                </prop>

            </node>

            <node oor:name="m4" oor:op="replace">

                <prop oor:name="Command">

                    <value>Quit</value>

                </prop>

            </node>

        </node>

    </node>

</oor:component-data>

Disabling Commands at Runtime

The following code example first removes all commands that were defined in the user layer of the configuration branch org.openoffice.Office.Commands as having a defined starting point. Then it checks if it can get dispatch objects for some pre-defined commands.
Then the example disables these commands and tries to get dispatch objects for them again. At the end, the code removes the disabled commands again, otherwise OpenOffice.org would not be fully useable any longer.

import com.sun.star.bridge.XUnoUrlResolver;

import com.sun.star.uno.UnoRuntime;

import com.sun.star.uno.XComponentContext;

import com.sun.star.lang.XMultiComponentFactory;

import com.sun.star.beans.XPropertySet;

import com.sun.star.beans.PropertyValue;

import com.sun.star.lang.XMultiServiceFactory;

import com.sun.star.lang.XSingleServiceFactory;

import com.sun.star.util.XURLTransformer;

import com.sun.star.frame.XDesktop;

import com.sun.star.beans.UnknownPropertyException;

/*

 * Provides example code how to enable/disable

 * commands.

 */

public class DisableCommandsTest extends java.lang.Object {

   

    /*

     * A list of command names

     */

    final static private String[] aCommandURLTestSet =

    {

        new String( "Open" ),

        new String( "About" ),

        new String( "SelectAll" ),

        new String( "Quit" ),

    };

   

    private static XComponentContext xRemoteContext = null;

    private static XMultiComponentFactory xRemoteServiceManager = null;

    private static XURLTransformer xTransformer = null;

    private static XMultiServiceFactory xConfigProvider = null;

   

    /*

     * @param args the command line arguments

     */

    public static void main(String[] args) {

       

        try {

            // connect

            XComponentContext xLocalContext =

                com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);

            XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();

            Object urlResolver  = xLocalServiceManager.createInstanceWithContext(

                "com.sun.star.bridge.UnoUrlResolver", xLocalContext);

            XUnoUrlResolver xUnoUrlResolver = (XUnoUrlResolver) UnoRuntime.queryInterface(

                XUnoUrlResolver.class, urlResolver );

            Object initialObject = xUnoUrlResolver.resolve(

                "uno:socket,host=localhost,port=8100;urp;StarOffice.ServiceManager");

            XPropertySet xPropertySet = (XPropertySet)UnoRuntime.queryInterface(

                XPropertySet.class, initialObject);

            Object context = xPropertySet.getPropertyValue("DefaultContext");

            xRemoteContext = (XComponentContext)UnoRuntime.queryInterface(

                XComponentContext.class, context);

            xRemoteServiceManager = xRemoteContext.getServiceManager();

            Object transformer = xRemoteServiceManager.createInstanceWithContext(

                "com.sun.star.util.URLTransformer", xRemoteContext);

            xTransformer = (com.sun.star.util.XURLTransformer)UnoRuntime.queryInterface(

                com.sun.star.util.XURLTransformer.class, transformer);

            Object configProvider = xRemoteServiceManager.createInstanceWithContext(

                "com.sun.star.configuration.ConfigurationProvider", xRemoteContext);

            xConfigProvider = (com.sun.star.lang.XMultiServiceFactory)UnoRuntime.queryInterface(

                com.sun.star.lang.XMultiServiceFactory.class, configProvider);

            // First we need a defined starting point. So we have to remove

            // all commands from the disabled set!

            enableCommands();

           

            // Check if the commands are usable

            testCommands(false);

           

            // Disable the commands

            disableCommands();

           

            // Now the commands should not be usable anymore

            testCommands(true);

           

            // Remove disable commands to make Office usable again

            enableCommands();

        }

        catch (java.lang.Exception e){

            e.printStackTrace();

        }

        finally {

            System.exit(0);

        }

    }

    /**

     * Test the commands that we enabled/disabled

     */

    private static void testCommands(boolean bDisabledCmds) throws com.sun.star.uno.Exception {

        // We need the desktop to get access to the current frame

        Object desktop = xRemoteServiceManager.createInstanceWithContext(

                "com.sun.star.frame.Desktop", xRemoteContext );

        com.sun.star.frame.XDesktop xDesktop = (com.sun.star.frame.XDesktop)UnoRuntime.queryInterface(

                com.sun.star.frame.XDesktop.class, desktop);

        com.sun.star.frame.XFrame xFrame = xDesktop.getCurrentFrame();

        com.sun.star.frame.XDispatchProvider xDispatchProvider = null;

        if (xFrame != null) {

            // We have a frame. Now we need access to the dispatch provider.

            xDispatchProvider = (com.sun.star.frame.XDispatchProvider)UnoRuntime.queryInterface(

                    com.sun.star.frame.XDispatchProvider.class, xFrame );

            if (xDispatchProvider != null) {

                // As we have the dispatch provider we can now check if we get a dispatch

                // object or not.

                for (int n = 0; n < aCommandURLTestSet.length; n++) {

                    // Prepare the URL

                    com.sun.star.util.URL[] aURL  = new com.sun.star.util.URL[1];

                    aURL[0] = new com.sun.star.util.URL();

                    com.sun.star.frame.XDispatch xDispatch = null;

                   

                    aURL[0].Complete = ".uno:" + aCommandURLTestSet[n];

                    xTransformer.parseSmart(aURL, ".uno:");

                   

                    // Try to get a dispatch object for our URL

                    xDispatch = xDispatchProvider.queryDispatch(aURL[0], "", 0);

                   

                    if (xDispatch != null) {

                        if (bDisabledCmds)

                            System.out.println("Something is wrong, I got dispatch object for "

                                + aURL[0].Complete);

                        else

                            System.out.println("Ok, dispatch object for " + aURL[0].Complete);

                    }

                    else {

                        if (!bDisabledCmds)

                            System.out.println("Something is wrong, I cannot get dispatch object for "

                                + aURL[0].Complete);

                        else

                            System.out.println("Ok, no dispatch object for " + aURL[0].Complete);

                    }

                    resetURL(aURL[0]);

                }

            }

            else

                System.out.println("Couldn't get XDispatchProvider from Frame!");

        }

        else

            System.out.println("Couldn't get current Frame from Desktop!");

    }

    /**

     * Ensure that there are no disabled commands in the user layer. The

     * implementation removes all commands from the disabled set!

     */

    private static void enableCommands() {

        // Set the root path for our configuration access

        com.sun.star.beans.PropertyValue[] lParams = new com.sun.star.beans.PropertyValue[1];

        lParams[0] = new com.sun.star.beans.PropertyValue();

        lParams[0].Name  = new String("nodepath");

        lParams[0].Value = "/org.openoffice.Office.Commands/Execute/Disabled";

        try {

            // Create configuration update access to have write access to the configuration

            Object xAccess = xConfigProvider.createInstanceWithArguments(

                "com.sun.star.configuration.ConfigurationUpdateAccess", lParams);

       

            com.sun.star.container.XNameAccess xNameAccess = (com.sun.star.container.XNameAccess)

                UnoRuntime.queryInterface(com.sun.star.container.XNameAccess.class, xAccess);

            if (xNameAccess != null) {

                // We need the XNameContainer interface to remove the nodes by name

                com.sun.star.container.XNameContainer xNameContainer =

                        (com.sun.star.container.XNameContainer)

                        UnoRuntime.queryInterface(com.sun.star.container.XNameContainer.class, xAccess);

                // Retrieves the names of all Disabled nodes

                String[] aCommandsSeq = xNameAccess.getElementNames();

                for (int n = 0; n < aCommandsSeq.length; n++) {

                    try {

                        // remove the node

                        xNameContainer.removeByName( aCommandsSeq[n]);

                    }

                    catch (com.sun.star.lang.WrappedTargetException e) {

                    }

                    catch (com.sun.star.container.NoSuchElementException e) {

                    }

                }

            }                    

            // Commit our changes

            com.sun.star.util.XChangesBatch xFlush =

                (com.sun.star.util.XChangesBatch)UnoRuntime.queryInterface(

                com.sun.star.util.XChangesBatch.class, xAccess);

            xFlush.commitChanges();

        }

        catch (com.sun.star.uno.Exception e) {

            System.out.println("Exception detected!");

            System.out.println(e);

        }

    }

   

    /**

     * Disable all commands defined in the aCommandURLTestSet array

     */

    private static void disableCommands() {

        // Set the root path for our configuration access

        com.sun.star.beans.PropertyValue[] lParams = new com.sun.star.beans.PropertyValue[1];

        lParams[0] = new com.sun.star.beans.PropertyValue();

        lParams[0].Name  = new String("nodepath");

        lParams[0].Value = "/org.openoffice.Office.Commands/Execute/Disabled";

        try {

            // Create configuration update access to have write access to the configuration

            Object xAccess = xConfigProvider.createInstanceWithArguments(

                "com.sun.star.configuration.ConfigurationUpdateAccess", lParams);

       

            com.sun.star.lang.XSingleServiceFactory xSetElementFactory =

                (com.sun.star.lang.XSingleServiceFactory)UnoRuntime.queryInterface(

                com.sun.star.lang.XSingleServiceFactory.class, xAccess);

            com.sun.star.container.XNameContainer xNameContainer =

                (com.sun.star.container.XNameContainer)UnoRuntime.queryInterface(

                com.sun.star.container.XNameContainer.class, xAccess );

                       

            if (xSetElementFactory != null && xNameContainer != null) {

                Object[] aArgs = new Object[0];

                   

                for (int i = 0; i < aCommandURLTestSet.length; i++) {

                    // Create the nodes with the XSingleServiceFactory of the configuration

                    Object xNewElement = xSetElementFactory.createInstanceWithArguments( aArgs );

                    if (xNewElement != null) {

                        // We have a new node. To set the properties of the node we need

                        // the XPropertySet interface.

                        com.sun.star.beans.XPropertySet xPropertySet =

                            (com.sun.star.beans.XPropertySet)UnoRuntime.queryInterface(

                            com.sun.star.beans.XPropertySet.class,

                            xNewElement );

                           

                        if (xPropertySet != null) {

                            // Create a unique node name.

                            String aCmdNodeName = new String("Command-");

                            aCmdNodeName += i;

                           

                            // Insert the node into the Disabled set

                            xPropertySet.setPropertyValue("Command", aCommandURLTestSet[i]);

                            xNameContainer.insertByName(aCmdNodeName, xNewElement);

                        }

                    }

                }

               

                // Commit our changes

                com.sun.star.util.XChangesBatch xFlush = (com.sun.star.util.XChangesBatch)

                    UnoRuntime.queryInterface(com.sun.star.util.XChangesBatch.class, xAccess);

                xFlush.commitChanges();

            }            

        }

        catch (com.sun.star.uno.Exception e) {

            System.out.println("Exception detected!");

            System.out.println(e);

        }

    }    

    /**

     * reset URL so it can be reused

     *

     * @param aURL

     *          the URL that should be reseted

     */

    private static void resetURL(com.sun.star.util.URL aURL) {

        aURL.Protocol  = "";

        aURL.User      = "";

        aURL.Password  = "";

        aURL.Server    = "";

        aURL.Port      = 0;

        aURL.Path      = "";

        aURL.Name      = "";

        aURL.Arguments = "";

        aURL.Mark      = "";

        aURL.Main      = "";

        aURL.Complete  = "";

    }

}

4.8    File Naming Conventions

As a recommendation, UNO component libraries and UNO packages should be named according to the following naming scheme:

<NAME>[<VERSION>].uno.(so|dll|dylib|jar|zip)

This recommendation applies to shared libraries and Java archives, as well as UNO packages deployed by pkgchk as described in section 4.9.1 Writing UNO Components - Deployment Options for Components - UNO Package Installation.

This file name convention results in file names such as:

component.uno.so

component1.uno.dll

component0.1.3.uno.dylib

component.uno.jar

component1.5.uno.zip

<NAME> should be a descriptive name, optionally extended by version information as shown below, followed by the characters .uno and the necessary file extension.

The term .uno is placed next to the platform-specific extension to emphasize that this is a special type of shared library, jar, or zip file.

Usually a shared library or jar has to be registered with UNO to be useful, as its shared library interface only consists of the component operations. Zipped files cannot easily be recognized as UNO packages. In both cases the .uno tag informs users that a component or package file is meant for use with UNO.

Since the given naming scheme is only a suggestion, there might be component shared libraries that do not contain the .uno addition in their names. Therefore, no tool should build assumptions on whether a shared library name contains .uno or not.

<VERSION> is optional and should be in the form:

<VERSION>  =  <MAJOR> [.<MINOR> [.<MICRO>]]

<MAJOR>  =  <NUMBER>

<MINOR>  =  <NUMBER>

<MICRO>  =  <NUMBER>

<NUMBER>  =  0  |  1–9 0–9*

Using the version tag in the file name of a shared library or jar is primarily meant for simple components that are not part of a larger UNO package file deployed by pkgchk. Such components are usually made up of a single shared library, and different file names for different versions can be useful, for instance in bug reports.

The version of a larger UNO package should be indicated in the package file name, as in component1.5.uno.zip., which results in a corresponding path name in the package cache.

The version of components that are part of the OpenOffice.org installation is already well defined by the version and build number of the installed OpenOffice.org itself.

It is up to the developer how the version scheme is used. You can count versions of a given component shared library using MAJOR alone, or add MINOR and MICRO as needed.

Note graphics marks a special text section

If version is used, it must be placed before the platform-specific extension, never after it. Under Linux and Solaris, there is a convention to add a version number after the .so, but that version number has different semantics than the version number used here. In short, those version numbers change whenever the shared library's interface changes, whereas the UNO component interface with the component operations component_getFactory() etc. never changes.

The following considerations give an overview of ways that a component can evolve:

A component shared library's interface, as defined by the component operations such as component_getFactory() is assumed to be stable.

The UNO services offered by a component can change:

When an implementation in a component file is changed, for instance when a bug is fixed, such a change will typically be compatible unless clients made themselves dependent on the bug. This can happen when clients considered the bug a feature or worked around the bug in a way that made them dependent on the bug. Therefore developers must be careful to program according to the specification, not the implementation.

Finally, a component shared library can change its dependencies on other shared libraries. Examples of such dependencies are:

C/C++ runtime libraries

such as libc.so.6, libstdc++.so.3.0.1, and libstlport_gcc.so

UNO runtime libraries

such as libcppu.so.3.1.0 and libcppuhelpergcc3.so.3.1.0

OpenOffice.org libraries

such as libsvx644li.so

Dependency changes are typically incompatible, as they rely on compatible or incompatible changes of the component's environment.

4.9    Deployment Options for Components

There are a number of opportunities to deploy components to a OpenOffice.org environment. The options available depend on how the new component is to be deployed. If OpenOffice.org is installed in a network mode, the new component could be available to an entire network or to certain users. Another option is to install the new component to individual desktop installations. Third, you may want to use UNO components without any local installation at all. This chapter introduces a simple automatic deployment tool and provides a full understanding of the underlying deployment process, so that you can troubleshoot or deploy manually, if necessary.

4.9.1    UNO Package Installation

OpenOffice.org has a simple concept for adding components to an existing installation. Bringing a UNO component into a OpenOffice.org installation involves the following steps:

[<OfficePath>/program] $ pkgchk

[<OfficePath>/program] $ pkgchk --shared

The tool analyzes the packages in the package directories, matches them with a cache directory for custom extensions used by OpenOffice.org, registers the components found in the packages and configures them as needed.

As an alternative, the packages can also be specified as command line arguments. In that case, the zip files are automatically copied into the package directory and installed afterwards.

[<OfficePath>/program] $ pkgchk /foo/bar/my_package.zip

To remove a package from the OpenOffice.org installation, the opposite steps are necessary:

The pkgchk mechanism also works for user-defined OpenOffice.org Basic libraries. For details see 11 OpenOffice.org Basic and Dialogs.

Pay attention to the following important text section

Be careful not to run the pkgchk deployment tool while there are running instances of OpenOffice.org. For ordinary users, this case is recognized by the pkgchk process and leads to abortion, but for shared network installations (using option '--shared' or '-s'), this cannot be determined. If any user of a network installation has open processes, data inconsistencies may occur, and OpenOffice.org processes may crash afterwards.

Package Structure

A UNO package is a zip file containing UNO components, type libraries, configuration files or basic libraries. The pkgchk tool unzips all packages found in the package directory into the cache directory, preserving the file structure of the zip file. It also copies all single files recognized in the package directory to the cache directory. Subdirectories are normally ignored.

There is often the need for platform dependent files inside a package for the supported UNO platforms. For this purpose, create special platform directories with the extension .plt in the package, which are only processed if the platform is present. A package structure for all platforms currently supported by UNO has to look like the following:

my_package.zip:

    windows.plt/

        my_comp.dll

    solaris_sparc.plt/

        libmy_comp.so

    linux_x86.plt/

        libmy_comp.so

    linux_powerpc.plt/

        libmy_comp.so

    macosx_powerpc.plt/

        libmy_comp.so

    netbsd_sparc.plt/

        libmy_comp.so

A component library might need a third-party library shipped with the package. This library must not be registered if it is not a UNO component. In order to skip registration of shared libraries or jar files, place these libraries in a directory called skip_registration within each platform folder. This causes pkgchk to copy the files and directories below that directory without registering them.

After the cache directory has been made ready, pkgchk traverses the cache directory recursively. Depending on the extension of the files it detects, it carries out the necessary registration steps. Nothing is done for unknown file types.

Shared Libraries

The file extension for shared libraries is .dll for Windows and .so for Unix. Shared library files are registered and revoked in the registry database <CacheDir>/services.rdb and linked into the OpenOffice.org installation through the UNO_SERVICES entry in uno(.ini|rc) as shown in the following code. The leading '?' in uno(.ini|rc) indicates optional rdb files:

UNO_SERVICES=?$UNO_USER_PACKAGES_CACHE/services.rdb \

             ?$UNO_SHARED_PACKAGES_CACHE/services.rdb \

             $SYSBINDIR/applicat.rdb

Java Archive Files

Jar files are registered and revoked in the registry database <CacheDir>/services.rdb and added to the java classpath of the Java virtual machine used by OpenOffice.org.

Python Components

The UNO deployment tool pkgchk now supports registration of Python components (.py files). Those files are registered using the com.sun.star.loader.Python loader. For details concerning Python-UNO, please refer to http://udk.openoffice.org/python/python-bridge.html

Basic Libraries

Basic libraries are recognized by the extension .xlb, and they are linked to the basic library container files. Refer to 11 OpenOffice.org Basic and Dialogs for additional information.

Type Library Files

The file extension for type libraries is .rdb on all platforms. Type libraries in UNO packages are automatically integrated into OpenOffice.org during package installation.
For this purpose, new type library files are merged into the <CacheDir>/types.rdb file. In turn, types.rdb is linked into the OpenOffice.org installation through the UNO_TYPES entry in the file uno(.ini|rc). The file uno(.ini|rc) and its role is described in 4.9.2 Writing UNO Components - Deployment Options for Components - Background: UNO Registries. After package installation, uno(.ini|rc) contains an entry as shown below. The leading '?' denotes optional  type library files in uno(.ini|rc):

UNO_TYPES=$SYSBINDIR/applicat.rdb \

          ?$UNO_SHARED_PACKAGES_CACHE/types.rdb \

          ?$UNO_USER_PACKAGES_CACHE/types.rdb

Configuration Data Files

Configuration files are recognized by the extension .xcu and are mapped into the global OpenOffice.org configuration at runtime.

Configuration Schema Files

Configuration schema files are recognized by the extension .xcs. Beware of adding concurring schemata, for example, two .xcs files defining the same schema name (oor:package, oor:name), but different definitions.

Arbitrary Files

Arbitrary files are copied into the UNO packages cache. You can, for instance, deploy an image for add-on menus with the package, or any other file needed by your component. The OpenOffice.org configuration is used to find out in which path this file is located in a particular installation.
When you define a package containing additional files, include an .xcu configuration data file, which points to your files. Use a variable %origin% as a placeholder for the exact path where the file will be copied by the package installer. When pkgchk  installs the .xcu, it resolves %origin% to a file URL in the configuration that points to this path. The URL in the configuration contains a macro that has to be expanded before it is a valid file URL. This can be done using the com.sun.star.util.MacroExpander service. The %origin% variable is, for instance, used by the ImageIdentifier property of add-on menus and toolbar items, which is described in the 4.7.3 Writing UNO Components - Integrating Components into OpenOffice.org - User Interface Add-Ons - Configuration section.

Path Settings

The package directories are called uno-packages by default. The packages can be in <OfficePath>/share for shared installations and another package can be in <OfficePath>/user for single users. The cache directories are created automatically within the respective uno_package directory. OpenOffice.org must be configured to look for these paths in uno(.ini|rc). When pkgchk is launched, it checks uno(.ini|rc) for package entries; if they do not exist, the following default values are added:

[Bootstrap]
UNO_SHARED_PACKAGES=${$SYSBINDIR/bootstrap.ini::BaseInstallation}/share/uno_packages
UNO_SHARED_PACKAGES_CACHE=$UNO_SHARED_PACKAGES/cache
UNO_USER_PACKAGES=${$SYSBINDIR/bootstrap.ini::UserInstallation}/user/uno_packages
UNO_USER_PACKAGES_CACHE=$UNO_USER_PACKAGES/cache

The settings reflect the default values for the shared package and cache directory, and the user package and cache directory, described previously.

In a network installation, all users start the office from a common directory on a file server. The administrator puts the packages for all users of the network installation into the <OfficePath>/share/uno_packages folder of the shared installation. If a user wants to install packages locally so that only the single installation is affected, the packages must be copied to <OfficePath>/user/uno_packages.

The pkgchk is run differently for a shared and for a user installation. To install shared packages, run pkgchk with the -s (-shared) option, which causes pkgchk to process the shared packages only. If pkgchk is run without command-line parameters, the user packages are registered.

Additional Options

The pkgchk can be run with the option -h (--help) to get a comprehensive overview of all switches.

By default, the tool logs all actions into the <CacheDir>/log.txt file. Switch to another log file through the -l (–log) <file name> option.

Option -v (–verbose) logs to stdout, in addition to the log file.

The tool handles errors loosely. It continues after errors, even if a package cannot be inflated or a shared library cannot be registered. The tool logs these errors and proceeds silently. But you can switch on --strict_error handling to make the tool stop on every error.

When pkgchk is raised giving packages through the command line, then those packages are first copied to the packages directory. Then the packages directory is scanned, balancing the UNO packages cache directory. To avoid the loss of packages of the same name in the packages directory, pkgchk aborts if there is an existing file in the packages directory. You have to explicitly raise pkgchk with option -f (--force_overwrite) to overwrite those files.

If there is inconsistency between the package directory and the cache, renew it from the ground up by repeating the installation, using the option -r (–renewal). This could be necessary when the variables UNO_USER_PACKAGES_CACHE or UNO_SHARED_PACKAGES_CACHE have been modified or after the office installation has been relocated.

4.9.2    Background: UNO Registries

This section explains the necessary steps to deploy new UNO components manually into an installed OpenOffice.org. Background information is provided and the tools required to test deployment are described. The developer and deployer of the component should be familiar with this section. If the recommendations provided are accepted, interoperability of components of different vendors can be achieved easily.

UNO registries store binary data in a tree-like structure. The stored data can be accessed within a registry programmatically through the com.sun.star.registry.SimpleRegistry service, however this is generally not necessary. Note that UNO registries have nothing to do with the Windows registry, except that they follow a similar concept for data storage.

UNO-registries mainly store two types of data :

Type-library

To invoke UNO calls from BASIC or through an interprocess connection, the core UNO bridges need information about the used data types. UNO stores this information into a type library, so that the same data is reusable from any bridge. This is in contrast to the CORBA approach, where code is generated for each data type that needs to be compiled and linked into huge libraries. Every UNOIDL type description is stored as a binary large object (BLOB) that is interpreted by the com.sun.star.reflection.TypeDescriptionProvider service.

Information about registered components

One basic concept of UNO is to create an instance of a component simply by its service name through the ServiceManager. The association between the service name and the shared library or .jar-file where the necessary compiled code is found is stored into a UNO-registry.
The structure of this data is provided below. Future versions of OpenOffice.org will probably store this information in an XML file that will make it modifiable using a simple text editor.

Both types of data are necessary to run a UNO-C++ process. If the types of data are not present, it could lead to termination of the program. UNO processes in general open their registries during startup and close them when the process terminates. Both types of data are commonly stored in a file with an .rdb suffix ( rdb=registry database ), but this suffix is not mandatory.

UNO Type Library

All type descriptions must be available within the registry under the /UCR main key (UCR = Uno Core Reflection) to be usable in a UNO C++ process . Use the regview tool to view the file <officepath>/install/program/ applicat.rdb. The regview tool comes with the OpenOffice.org SDK.

For instance:

$ regview applicat.rdb /UCR

prints all type descriptions used within the office to stdout. To check if a certain type is included within the registry, invoke the following command:

$ regview applicat.rdb /UCR/com/sun/star/bridge/XUnoUrlResolver

/UCR/com/sun/star/bridge/XUnoUrlResolver
  Value: Type = RG_VALUETYPE_BINARY
  Size = 461
  Data = minor version: 0
  major version: 1
  type: 'interface'
  name: 'com/sun/star/bridge/XUnoUrlResolver'
  super name: 'com/sun/star/uno/XInterface'
  Doku: ""
  number of fields: 0
  number of methods: 1
  method #0: com/sun/star/uno/XInterface resolve([in] string sUnoUrl)
  raises com/sun/star/connection/NoConnectException,
         com/sun/star/connection/ConnectionSetupException,
         com/sun/star/lang/IllegalArgumentException
  Doku: ""
  number of references: 0

The regview tool decodes the format of the BLOB containing the type description and presents it in a readable form.

Component Registration

The UNO component provides the data about what services are implemented. In order not to load all available UNO components into memory when starting a UNO process, the data is assembled once during setup and stored into the registry. The process of writing this information into a registry is called component registration. The tools used to perform this task are discussed below.

For an installed OpenOffice.org, the applicat.rdb contains the component registration information. The data is stored within the /IMPLEMENTATIONS and /SERVICES key. The code below shows a sample SERVICES key for the com.sun.star.io.Pipe service.

$ regview applicat.rdb /SERVICES/com.sun.star.io.Pipe

/SERVICES/com.sun.star.io.Pipe
 Value: Type = RG_VALUETYPE_STRINGLIST
        Size = 38
        Len  = 1
        Data = 0 = "com.sun.star.comp.io.stm.Pipe"

The code above contains one implementation name, but it could contain more than one. In this case, only the first is used. The following entry can be found within the IMPLEMENTATIONS section:

$ regview applicat.rdb /IMPLEMENTATIONS/com.sun.star.comp.io.stm.Pipe

/IMPLEMENTATIONS/com.sun.star.comp.io.stm.Pipe
/ UNO
  / ACTIVATOR
    Value: Type = RG_VALUETYPE_STRING
           Size = 34
           Data = "com.sun.star.loader.SharedLibrary"

   / SERVICES
    / com.sun.star.io.Pipe
  / LOCATION
    Value: Type = RG_VALUETYPE_STRING
           Size = 8
           Data = "stm.dll"

The implementations section holds three types of data.

  1. The loader to be used when the component is requested at runtime (here com.sun.star.loader.SharedLibrary).

  1. The services supported by this implementation.

  1. The URL to the file the loader uses to access the library (the url may be given relative to the OpenOffice.org library directory for native components as it is in this case).

4.9.3    Command Line Registry Tools

There are various tools to create, modify and use registries. This section shows some common use cases. The regmerge tool is used to merge multiple registries into a sub-key of an existing or new registry. For instance:

$ regmerge new.rdb / test1.rdb test2.rdb

merges the contents of test1.rdb and test2.rdb under the root key / of the registry database new.rdb . The names of the keys are preserved, because both registries are merged into the root-key. In case new.rdb existed before, the previous contents remain in new.rdb unless an identical key names exist in test1.rdb and test2.rdb. In this case, the content of these keys is overwritten with the ones in test1.rdb or test2.rdb. So the above command is semantically identical to:

$ regmerge new.rdb / test1.rdb
$ regmerge new.rdb / test2.rdb

The following command merges the contents of test1.urd and test2.urd under the key /UCR into the file myapp_types.rdb.

$ regmerge myapp_types.rdb /UCR test1.urd test2.urd

The names of the keys in test1.urd and test2.urd should only be added to the /UCR key. This is a real life scenario as the files produced by the idl-compiler have a .urd-suffix. The regmerge tool needs to be run before the type library can be used in a program, because UNO expects each type description below the /UCR key.

Component Registration Tool

Components can be registered using the regcomp tool. Below, the components necessary to establish an interprocess connection are registered into the myapp_services.rdb.

$ regcomp -register -r myapp_services.rdb \
                   -c uuresolver.dll             \
                   -c brdgfctr.dll               \
                   -c acceptor.dll               \
                   -c connectr.dll               \
                   -c remotebridge.dll

The \ means command line continuation. The option -r gives the registry file where the information is written to. If it does not exist, it is created, otherwise the new data is added. In case there are older keys, they are overwritten. The registry file (here myapp_services.rdb) must NOT be opened by any other process at the same time. The option -c is followed by a single name of a library that is  registered. The -c option can be given multiple times. The shared libraries registered in the example above are needed to use the UNO interprocess bridge.

Registering a Java component is currently more complex. It works only in an installed office environment, the <OfficePath>/program must be the current working directory, the office setup must point to a valid Java installation that can be verified using jvmsetup from the <OfficePath>/program, and Java must be enabled. See Tools - Options - General - Security. The office must not run. On Unix, the LD_LIBRARY_PATH environment variable must additionally contain the directories listed by the javaldx tool (which is installed with the office).

Copy the regcomp executable into the <officepath>/program directory. The regcomp tool must then be invoked using the following parameters :

$ regcomp -register -r your_registry.rdb \

                    -br applicat.rdb \

                    -l com.sun.star.loader.Java2 \

                    -c file:///i:/StarOffice6.0/program/classes/JavaTestComponent.jar

The option -r (registry) tells regcomp where to write the registration data and the -br (bootstrap registry) option points regcomp to a registry to read common types from. The regcomp tool does not know the library that has the Java loader. The -l option gives the service name of the loader to use for the component that must be com.sun.star.loader.Java2. The option can be omitted for C++ components, because regcomp defaults to the com.sun.star.loader.SharedLibrary loader. The option -c gives the file url to the Java component.

File urls can be given absolute or relative. Absolute file urls must begin with 'file:/// '. All other strings are interpreted as relative file urls. The '3rdpartYcomp/filterxy.dll', '../../3rdpartycomp/filterxyz.dll', and 'filterxyz.dll' are a few examples. Relative file urls are interpreted relative to all paths given in the PATH variable on Windows and LD_LIBRARY_PATH variable on Unix.

Java components require an absolute file URL for historical reasons.

Tip graphics marks a hint section in the text

The regcomp tool should be used only during the development and testing phase of components. For deploying final components, the pkgchk tool should be used instead. See 4.9.1 Writing UNO Components - Deployment Options for Components - UNO Package Installation.

UNO Type Library Tools

There are several tools that currently access the type library directly. They are encountered when new UNOIDL types are introduced.

4.9.4    Manual Component Installation

Manually Merging a Registry and Adding it to uno.ini or soffice.ini

Registry files used by OpenOffice.org are configured within the uno(.ini|rc) and soffice(.ini|rc) files found in the program directory. After a default OpenOffice.org installation, the files look like this:

uno.ini :

[Bootstrap]

UNO_TYPES=$SYSBINDIR/applicat.rdb

UNO_SERVICES=$SYSBINDIR/applicat.rdb

soffice.ini:

[Bootstrap]

Logo=1

UNO_WRITERDB=$SYSUSERCONFIG/user60.rdb

The three UNO variables are relevant for UNO components. The UNO_TYPES variable gives a space separated list of type library registries, and the UNO_SERVICES variable gives a space separated list of registries that contain component registration information. These registries are opened read-only. The same registry may appear in UNO_TYPES and UNO_SERVICES variables, for example, the applicat.rdb. The UNO_WRITERDB provides one registry that is opened in read-write mode. The $SYSBINDIR points to the directory where the soffice executable is located and $SYSUSERCONFIG points to the user's home directory.

OpenOffice.org uses the applicat.rdb as a type and component registration information repository. When a programmer or software vendor releases a UNO component, the following files must be provided at a minimum:

The latter two can be integrated into a single file.

Note graphics marks a special text section

In fact, a vendor may release more files, such as documentation, the .idl files of the user defined types, the source code, and configuration files. While every software vendor is encouraged to do this, there are currently no recommendations how to integrate these files into OpenOffice.org. These type of files are ignored in the following paragraphs. These issues will be addressed in next releases of OpenOffice.org.

The recommended method to add a component to OpenOffice.org manually is described in the following steps:

  1. Copy new shared library components into the <OfficePath>/program directory and new Java components into the <OfficePath>/program/classes directory.

  2. Copy the registry containing the type library into the <OfficePath>/program directory, if needed and available.

  3. Copy the registry containing the component registration information into the <OfficePath>/program directory, if required. Otherwise, register the component with the regcomp command line tool coming with the OpenOffice.org SDK into a new registry.

  4. Modify the uno(.ini|rc) file, and add the type registry to the UNO_TYPES variable and the component registry to the UNO_SERVICES variable. The new uno(.ini|rc) might look like this:

[Bootstrap]
UNO_TYPES=$SYSBINDIR/applicat.rdb $SYSBINDIR/filterxyz_types.rdb
UNO_SERVICES=$SYSBINDIR/applicat.rdb $SYSBINDIR/filterxyz_services.rdb

After these changes are made, every office that is restarted can use the new component. The uno(.ini|rc) changes directly affect the whole office network installation. If adding a component only for a single user, pass the modified UNO_TYPES and UNO_SERVICES variables per command line. An example might be:

$ soffice “-env:UNO_TYPES=$SYSBINDIR/applicat.rdb $SYSBINDIR/filterxyz_types.rdb“

          “-env:UNO_SERVICES=$SYSBINDIR/applicat.rdb $SYSBINDIR/filter_xyz_services.rdb” ).

Alternatives

There are more ways to add a component to the office with their own advantages and disadvantages. Below are some alternatives :

  1. When adding many third-party components to your office, the startup performance suffers from having types scattered about many registries. To avoid this, merge all third-party type registries into a single type registry and all third-party service registries into a single service registry using the regmerge tool.

New types and services can be merged into the applicat.rdb directly. With this method, the uno(.ini|rc) does not have to be modified. Modifying the applicat.rdb while there are running office instances is not allowed. This is important in a network installation.
Once merged, these registries can not be 'unmerge'. To remove a certain type library, a merge with all the other source types will have to be performed, that is, repeat the installation.

  1. When separating the OpenOffice.org installation from any third-party additions, the additional registries, shared libraries and .jar files can be stored into a directory other than the <OfficePath>/program directory. In this case, use relative filenames for component registrations, for instance ../../office3rdparty/filterxyz.dll. The only file that needs to be modified is the uno(.ini|rc).

  2. Configuring your Application with Bootstrap Parameters

A flexible approach is to use the UNO bootstrap parameters and the defaultBootstrap_InitialComponentContext() function. Arguments, such as registry names are not passed to this function, rather they are given through bootstrap parameters.

4.9.5    Bootstrapping a Service Manager

Bootstrapping a service manager means to create an instance of a service manager that is able to instantiate the UNO objects needed by a user. All UNO applications, that want to use the UnoUrlResolver for connections to the office, have to bootstrap a local service manager in order to create a UnoUrlResolver object. If developers create a new language binding, for instance for a scripting engine, they have to find a way to bootstrap a service manager in the target environment.

There are many methods to bootstrap a UNO C++ application, each requiring one or more registry files to be prepared. Once the registries are prepared, there are different options available to bootstrap your application. A flexible approach is to use UNO bootstrap parameters and the defaultBootstrap_InitialComponentContext() function.

#include <cppuhelper/bootstrap.hxx>

using namespace com::sun::star::uno;

using namespace com::sun::star::lang;

using namespace rtl;

using namespace cppu;
int main( )
{

    // create the initial component context

    Reference< XComponentContext > rComponentContext =

        defaultBootstrap_InitialComponentContext();

    // retrieve the service manager from the context

    Reference< XMultiComponentFactory > rServiceManager =

        rComponentContext()->getServiceManager();

    // instantiate a sample service with the service manager.

    Reference< XInterface > rInstance =

        rServiceManger->createInstanceWithContext(

            OUString::createFromAscii("com.sun.star.bridge.UnoUrlResolver" ),

            rComponentContext );

       

    // continue to connect to the office ....

}

No arguments, such as a registry name, are passed to this function. These are given using bootstrap parameters . Bootstrap parameters can be passed through a command line, an . ini file or using environment variables.

For bootstrapping the UNO component context, the following three variables are relevant:

  1. UNO_TYPES
    Gives a space separated list of type library registry files. Each registry must be given as an absolute or relative file url. Note that some special characters within the path require encoding, for example, a space must become a %20
    . The registries are opened in read-only.

  2. UNO_SERVICES
    Gives a space separated list of registry files with component registration information. The registries are opened in read-only. The same registry may appear in UNO_TYPES and UNO_SERVICES variables.

  3. UNO_WRITERDB

    Gives one registry file that is opened in read-write mode. Using this variable is optional, because it registers components at runtime and uses them directly.

An absolute file URL must begin with the file:/// prefix (on windows, it must look like file:///c:/mytestregistry.rdb). To make a file URL relative, the file:/// prefix must be omitted. The relative url is interpreted relative to the current working directory.

Within the paths, use special placeholders.

Bootstrap variable

Meaning

$SYSUSERHOME

Path of the user's home directory (see osl_getHomeDir())

$SYSBINDIR

Path to the directory of the current executable.

$SYSUSERCONFIG

Path to the directory where the user's configuration data is stored (see osl_getConfigDir())

The advantage of this method is that the executable can be configured after it has been built. The OpenOffice.org bootstraps the service manager with this mechanism.

Consider the following example:

A tool needs to be written that converts documents between different formats. This is achieved by connecting to OpenOffice.org and doing the necessary conversions. The tool is named docconv. In the code, the defaultBootstrap_InitialComponentContext() function is used as described above to create the component context. Two registries are prepared: docconv_services.rdb with the registered components and applicat.rdb that contains the types coming with OpenOffice.org. Both files are placed beside the executable. The easiest method to configure the application is to create a docconv(.ini|rc) ascii file in the same folder as your executable, that contains the following two lines:

UNO_TYPES=$SYSBINDIR/applicat.rdb

UNO_SERVICES=$SYSBINDIR/docconv_services.rdb

No matter where the application is started form, it will always use the mentioned registries. Note that this also works on different machines when the volume is mapped to different location mount points as $SYSBINDIR is evaluated at runtime.

The second possibility is to set UNO_TYPES and UNO_SERVICES as environment variables, but this method has drawbacks. All UNO applications started with this shell use the same registries.

The third possibility is to pass the variables as command line parameters, for instance

docconv -env:UNO_TYPES=$SYSBINDIR/applicat.rdb -env:UNO_SERVICES=$SYSBINDIR/docconv_services.rdb

Note that on UNIX shells, you need to quote the $ with a backslash \.

The command line arguments do not need to be passed to the UNO runtime, because it is generally retrieved from some static variables. How this is done depends on the operating system, but it is hidden from the programmer. The docconv executable should ignore all command line parameters beginning with '-env:'. The easiest way to do this is to ignore argc and argv[] and to use the rtl_getCommandLineArg() functions defined in rtl/process.h header instead which automatically strips the additional parameters.

  1. Combine the methods mentioned above. Command line parameters take precedence over .ini file variables and .ini file parameter take precedence over environment variables. That way, it is possible to overwrite the UNO_SERVICES variable on the command line for one invocation of the program only.

4.9.6    Special Service Manager Configurations

The com.sun.star.container.XSet interface allows the insertion or removal of com.sun.star.lang.XSingleServiceFactory or com.sun.star.lang.XSingleComponentFactory implementations into or from the service manager at runtime without making these changes persistent. When the office applications terminate, all the changes are lost. The inserted object must support the com.sun.star.lang.XServiceInfo interface. This interface returns the same information as the XServiceInfo interface of the component implementation which is created by the component factory.

With this feature, a running office can be connected, a new factory inserted into the service manager and the new service instantiated without registering it beforehand. This method of hard coding the registered services is not acceptable with OpenOffice.org, because it must be extended after compilation.

Java applications can use a native persistent service manager in their own process using JNI (see 3.4.1 Professional UNO - UNO Language Bindings - Java Language Binding), or in a remote process. But note, that all services will be instantiated in this remote process.

Dynamically Modifying the Service Manager

Bootstrapping in pure Java is simple, by calling the static runtime method createInitialComponentContext() from the Bootstrap class. The following small test program shows how to insert service factories into the service manager at runtime. The sample uses the Java component from the section 4.5.6 Writing UNO Components - Simple Component in Java - Storing the Service Manager for Further Use. The complete code can be found with the JavaComp sample component.

The example shows that there is the possibility to control through command line parameter, whether the service is inserted in the local Java service manager or the remote office service manager. If it is inserted into the office service manager, access the service through OpenOffice.org Basic. In both cases, the component runs in the local Java process.

If the service is inserted into the office service manager, instantiate the component through OpenOffice.org Basic calling createUnoService(" JavaTestComponentB"), as long as the Java process is not terminated. Note, to add the new types to the office process by one of the above explained mechanisms, use uno.ini.

    public static void insertIntoServiceManager(

                XMultiComponentFactory serviceManager, Object singleFactory)

            throws com.sun.star.uno.Exception {

        XSet set = (XSet ) UnoRuntime.queryInterface(XSet.class, serviceManager);

        set.insert(singleFactory);

    }

    public static void removeFromServiceManager(

                XMultiComponentFactory serviceManager, Object singleFactory)

            throws com.sun.star.uno.Exception {

        XSet set = (XSet) UnoRuntime.queryInterface( XSet.class, serviceManager);

        set.remove(singleFactory);

       

    }

    public static void main(String[] args) throws java.lang.Exception {

        if (args.length != 1) {

            System.out.println("usage: RunComponent local|uno-url");

            System.exit(1);

        }

        XComponentContext xLocalComponentContext =

            Bootstrap.createInitialComponentContext(null);

       

        // initial serviceManager

        XMultiComponentFactory xLocalServiceManager = xLocalComponentContext.getServiceManager();

       

        XMultiComponentFactory xUsedServiceManager = null;

        XComponentContext xUsedComponentContext = null;

        if (args[0].equals("local")) {

            xUsedServiceManager = xLocalServiceManager;

            xUsedComponentContext = xLocalComponentContext;

            System.out.println("Using local servicemanager");

            // now the local servicemanager is used !

        }

        else {

            // otherwise interpret the string as uno-url

            Object xUrlResolver = xLocalServiceManager.createInstanceWithContext(

                "com.sun.star.bridge.UnoUrlResolver", xLocalComponentContext);

            XUnoUrlResolver urlResolver = (XUnoUrlResolver) UnoRuntime.queryInterface(

                XUnoUrlResolver.class, xUrlResolver);

            Object initialObject = urlResolver.resolve(args[0]);

            xUsedServiceManager = (XmultiComponentFactory) UnoRuntime.queryInterface(

                XMultiComponentFactory.class, initialObject);

            System.out.println("Using remote servicemanager");

            // now the remote servicemanager is used.

        }

        // retrieve the factory for the component implementation

        Object factory = TestServiceProvider.__getServiceFactory(

            "componentsamples.TestComponentB", null, null);

        // insert the factory into the servicemanager

        // from now on, the service can be instantiated !

        insertIntoServiceManager( xUsedServiceManager, factory );

           

        // Now instantiate one of the services via the servicemanager !

        Object objTest= xUsedServiceManager.createInstanceWithContext(

            "JavaTestComponentB",xUsedComponentContext);

        // query for the service interface

        XSomethingB xs= (XSomethingB) UnoRuntime.queryInterface(

            XSomethingB.class, objTest);

        // and call the test method.

        String s= xs.methodOne("Hello World");

        System.out.println(s);

        // wait until return is pressed

        System.out.println( "Press return to terminate" );

        while (System.in.read() != 10);

        // remove it again from the servicemanager, otherwise we have

        // a dangling reference ( in case we use the remote service manager )

        removeFromServiceManager( xUsedServiceManager, factory );

        // quit, even when a remote bridge is running

        System.exit(0);

    }

Creating a ServiceManager from a Given Registry File

To create a service manager from a given registry, use a single registry that contains the type library and component registration information. Hard code the name of the registry in the program and use the createRegistryServiceFactory() function located in the cppuhelper library.

#include <cppuhelper/servicefactory.hxx>

using namespace com::sun::star::uno;

using namespace com::sun::star::lang;

using namespace rtl;

using namespace cppu;
int main( )
{

    // create the service manager on the registry test.rdb

    Reference< XMultiServiceFactory > rServiceManager =

                createRegistryServiceFactory( OUString::createFromAscii( “test.rdb” ) );

    // instantiate a sample service with the service manager.

    Reference< XInterface > rInstance =

                rServiceManger->createInstance(

            OUString::createFromAscii(“com.sun.star.bridge.UnoUrlResolver” ) );

       

    // continue to connect to the office ....

}

Note graphics marks a special text section

This instantiates the old style service manager without the possibility of offering a component context. In future versions, (642) you will be able to use the new service manager here.

4.10    The UNO Executable

In chapter 3.4.2 Professional UNO - UNO Language Bindings - UNO C++ Binding, several methods to bootstrap a UNO application were introduced. In this section, the option UNO executable is discussed. With UNO executable, there is no need to write executables anymore, instead only components are developed. Code within executables is locked up, it can only run by starting the executable, and it can never be used in another context. Components offer the advantage that they can be used from anywhere. They can be executed from Java or from a remote process.

For these cases, the com.sun.star.lang.XMain interface was introduced. It has one method:

/* module com.sun.star.lang.XMain */

interface XMain: com::sun::star::uno::XInterface

{

    long run( [in] sequence< string > aArguments );

};

Instead of writing an executable, write a component and implement this interface. The component gets the fully initialized service manager during instantiation. The run() method then should do what a main() function would have done. The UNO executable offers one possible infrastructure for using such components.

Basically, the uno tool can do two different things:

  1. Instantiate a UNO component which supports the com.sun.star.lang.XMain interface and executes the run() method.

    // module com::sun::star::lang
    interface XMain: com::sun::star::uno::XInterface
    {
       long run( [in] sequence< string > aArguments );
    };

  2. Export a UNO component to another process by accepting on a resource, such as a tcp/ip socket or named pipe, and instantiating it on demand.

In both cases, the uno executable creates a UNO component context which is handed to the instantiated component. The registries that should be used are given by command line arguments. The goal of this tool is to minimize the need to write executables and focus on writing components. The advantage for component implementations is that they do not care how the component context is bootstrapped. In the future there may be more ways to bootstrap the component context. While executables will have to be adapted to use the new features, a component supporting XMain can be reused.

Standalone Use Case

Simply typing uno gives the following usage screen :

uno (-c ComponentImplementationName -l LocationUrl | -s ServiceName)
   [-ro ReadOnlyRegistry1] [-ro ReadOnlyRegistry2] ... [-rw ReadWriteRegistry]
   [-u uno:(socket[,host=HostName][,port=nnn]|pipe[,name=PipeName]);urp;Name
       [--singleaccept] [--singleinstance]]
   [-- Argument1 Argument2 ...]

Choosing the implementation to be instantiated

Using the option -s servicename gives the name of the service which shall be instantiated. The uno executable then tries to instantiate a service by this name, using the registries as listed below.

Alternatively, the -l and -c options can be used. The -l gives an url to the location of the shared library or .jar file, and -c the name of the desired service implementation inside the component. Remember that a component may contain more than one implementation.

Choosing the registries for the component context (optional)

With the option -ro, give a file url to a registry file containing component's registration information and/or type libraries. The -ro option can be given multiple times. The -rw option can only be given once and must be the name of a registry with read/write access. It will be used when the instantiated component tries to register components at runtime. This option is rarely needed.

Note that the uno tool ignores bootstrap variables, such as UNO_TYPES and UNO_SERVICES.

The UNO URL (optional)

Giving a UNO URL causes the uno tool to start in server mode, then it accepts on the connection part of the UNO URL. In case another process connects to the resource (tcp/ip socket or named pipe), it establishes a UNO interprocess bridge on top of the connection (see also 3.3.1 Professional UNO - UNO Concepts - UNO Interprocess Connections). Note that urp should always be used as protocol. An instance of the component is instantiated when the client requests a named object using the name, which was given in the last part of the UNO URL.

Option --singleaccept

Only meaningful when a UNO URL is given. It tells the uno executable to accept only one connection, thus blocking any further connection attempts.

Option --singleinstance

Only meaningful when a UNO URL is given. It tells the uno executable to always return the same (first) instance of the component, thus multiple processes communicate to the same instance of the implementation. If the option is not given, every getInstance() call at the com.sun.star.bridge.XBridge interface instantiates a new object.

Option -- (double dash)

Everything following –- is interpreted as an option for the component itself. The arguments are passed to the component through the initialize() call of com.sun.star.lang.XInitialization interface.

Note graphics marks a special text section

The uno executable currently does not support the bootstrap variable concept as introduced by 3.4.2 Professional UNO - UNO Language Bindings - UNO C++ Binding. The uno registries must be given explicitly given by command line.

The following example shows how to implement a Java component suitable for the uno executable.

import com.sun.star.uno.XComponentContext;

import com.sun.star.comp.loader.FactoryHelper;

import com.sun.star.lang.XSingleServiceFactory;

import com.sun.star.lang.XMultiServiceFactory;

import com.sun.star.registry.XRegistryKey;

public class UnoExeMain implements com.sun.star.lang.XMain

{

    final static String __serviceName = "MyMain";

    XComponentContext _ctx;

   

    public UnoExeMain( XComponentContext ctx )

    {

        // in case we would need the component context !

        _ctx = ctx;

    }

    public int run( /*IN*/String[] aArguments )

    {

        System.out.println( "Hello world !" );

        return 0;

    }

    public static XSingleServiceFactory __getServiceFactory(

        String implName, XMultiServiceFactory multiFactory, XRegistryKey regKey)

    {

        XSingleServiceFactory xSingleServiceFactory = null;

       

        if (implName.equals(UnoExeMain.class.getName()))

        {

            xSingleServiceFactory =

                FactoryHelper.getServiceFactory(

                    UnoExeMain.class, UnoExeMain.__serviceName, multiFactory, regKey);

        }

        return xSingleServiceFactory;

    }

   

    public static boolean __writeRegistryServiceInfo(XRegistryKey regKey)

    {

        boolean b = FactoryHelper.writeRegistryServiceInfo(

            UnoExeMain.class.getName(),

            UnoExeMain.__serviceName, regKey);

        return b;

    }

}

The class itself inherits from com.sun.star.lang.XMain. It implements a constructor with the com.sun.star.uno.XComponentContext interface and stores the component context for future use. Within its run() method, it prints 'Hello World'. The last two mandatory functions are responsible for instantiating the component and writing component information into a registry. Refer to 4.5.6 Writing UNO Components - Simple Component in Java - Storing the Service Manager for Further Use for further information.

The code needs to be compiled and put into a .jar file with an appropriate manifest file:

RegistrationClassName: UnoExeMain

These commands create the jar:

javac UnoExeMain
jar -cvfm UnoExeMain.jar Manifest UnoExeMain.class

To be able to use it, register it with the following command line into a separate registry file (here test.rdb). The <OfficePath>/program directory needs to be the current directory, and the regcomp and uno tools must have been copied into this directory.

regcomp -register \
        -br applicat.rdb \
        -r test.rdb \
        -c file:///c:/devmanual/Develop/samples/unoexe/UnoExeMain.jar \
        -l com.sun.star.loader.Java2

The \ means command line continuation.

The component can now be run:

uno -s MyMain -ro applicat.rdb -ro test.rdb

This command should give the output "hello world !"

Server Use Case

This use case enables the export of any arbitrary UNO component as a remote server. As an example, the com.sun.star.io.Pipe service is used which is already implemented by a component coming with the office. It exports an com.sun.star.io.XOutputStream and a com.sun.star.io.XInputStream interface. The data is written through the output stream into the pipe and the same data from the input stream is read again. To export this component as a remote server, switch to the <OfficePath>/program directory and issue the following command line.

i:\o641l\program>uno -s com.sun.star.io.Pipe -ro applicat.rdb -u uno:socket,host=0,port=2002;urp;test

> accepting socket,host=0,port=2002...

Now a client program can connect to the server. A client may look like the following:

import com.sun.star.lang.XServiceInfo;

import com.sun.star.uno.XComponentContext;

import com.sun.star.bridge.XUnoUrlResolver;

import com.sun.star.io.XOutputStream;

import com.sun.star.io.XInputStream;

import com.sun.star.uno.UnoRuntime;

// Note: This example does not do anything meaningful, it shall just show,

//       how to import an arbitrary UNO object from a remote process.

class UnoExeClient {

    public static void main(String [] args) throws java.lang.Exception {

        if (args.length != 1) {

            System.out.println("Usage : java UnoExeClient uno-url");

            System.out.println("   The imported object must support the com.sun.star.io.Pipe service");

            return;

        }

        XComponentContext ctx =

            com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);

        // get the UnoUrlResolver service

        Object o = ctx.getServiceManager().createInstanceWithContext(

            "com.sun.star.bridge.UnoUrlResolver" , ctx);

        XUnoUrlResolver resolver = (XUnoUrlResolver) UnoRuntime.queryInterface(

            XUnoUrlResolver.class, o);

        // connect to the remote server and retrieve the appropriate object

        o = resolver.resolve(args[0]);

        // Check if we got what we expected

        // Note: This is not really necessary, you can also use the try and error approach

        XServiceInfo serviceInfo = (XServiceInfo) UnoRuntime.queryInterface(XServiceInfo.class,o);

        if (serviceInfo == null) {

            throw new com.sun.star.uno.RuntimeException(

                "error: The object imported with " + args[0] + " did not support XServiceInfo", null);

        }

        if (!serviceInfo.supportsService("com.sun.star.io.Pipe")) {

            throw new com.sun.star.uno.RuntimeException(

                "error: The object imported with "+args[0]+" does not support the pipe service", null);

        }

        XOutputStream output = (XOutputStream) UnoRuntime.queryInterface(XOutputStream.class,o);

        XInputStream input = (XInputStream) UnoRuntime.queryInterface(XInputStream.class,o);

        // construct an array.

        byte[] array = new byte[]{1,2,3,4,5};

        // send it to the remote object

        output.writeBytes(array);

        output.closeOutput();

        // now read it again in two blocks

        byte [][] read = new byte[1][0];

        System.out.println("Available bytes : " + input.available());

        input.readBytes( read,2 );

        System.out.println("read " + read[0].length + ":" + read[0][0] + "," + read[0][1]);

        System.out.println("Available bytes : " + input.available());

        input.readBytes(read,3);

        System.out.println("read " + read[0].length + ":" + read[0][0] +

            "," + read[0][1] + "," + read[0][2]);

        System.out.println("Terminating client");

        System.exit(0);

    }

}

After bootstrapping the component context, the UnoUrlResolver service is instantiated to access remote objects. After resolving the remote object, check whether it really supports the Pipe service. For instance, try to connect this client to a running OpenOffice.org — this check will fail. A byte array with five elements is written to the remote server and read again with two readBytes() calls. Starting the client with the following command line connects to the server started above. You should get the following output:

I:\tmp>java UnoExeClient uno:socket,host=localhost,port=2002;urp;test

Available bytes : 5

read 2:1,2

Available bytes : 3

read 3:3,4,5

Terminating client

Using the uno Executable

The main benefit of using the uno tool as a replacement for writing executables is that the service manager initialization is separated from the task-solving code and the component can be reused. For example, to have multiple XMain implementations run in parallel in one process. There is more involved when writing a component compared to writing an executable. With the bootstrap variable mechanism there is a lot of freedom in bootstrapping the service manager (see chapter 3.4.2 Professional UNO - UNO Language Bindings - UNO C++ Binding).

The uno tool is a good starting point when exporting a certain component as a remote server. However, when using the UNO technology later, the tool does have some disadvantages, such as multiple objects can not be exported or the component can only be initialized with command line arguments. If the uno tool becomes insufficient, the listening part in an executable will have to be re-implemented.

Note graphics marks a special text section

To instantiate Java components in build version 641, you need a complete setup so that the uno executable can find the java.ini file.

[ Previous document | Content Table | Next document ]