Writing the specification

Now you should have a new UNO-IDL project like the one presented by the illustration 9. It is made of several folders and files which you will have to know:

source

contains you Java implementation classes

build

contains all the generated temporary files, such as the results of the specification files ( .idl files) compilation ( .urd files) or the class files corresponding to the specifications ( .class files)

idl

contains the specifications of the component

types.rdb

is the generated UNO types registry from which the class files will be generated

JRE and the jars

are describing the classpath of the component. They are visible only in the Java package explorer. The OpenOffice.org jars are changed if the OpenOffice.org version associated to the project is changed. In a future version, they will be packed in a user library to take less space in the tree.

Created UNO-IDL project
Illustration 9: Created UNO-IDL project

Some other folders will be added in this tutorial because the plugin does not support all the build chain currently. However, this feature will be added in a next version of the plugin and will simplify your task: so do not worry.

We will now have to write a new XHelloworld interface to the component. This interface will define a sayHello() method that will return a hello message. To launch the interface creation wizard, select a file in your project before selecting the File NewOther menu item and select the UNO UNO-IDL interface wizard as shown by the illustration 10. Note that if you didn't select something in the UNO component project, you will not be able to click on the next button.

UNO-IDL wizards list
Illustration 10: UNO-IDL wizards list

The new interface wizard presents you several fields to fill as you can see it on the illustration 11. We will now see what these fields means and what you could do with them.

Package

corresponds to the UNO-IDL module where to add the interface. If the text field is left empty, the interface will be added in the root module of the component (filled in the project wizard). This field would be renamed in "module" in a next version

Interface name

is the interface name. By convention, we generally name a interface beginning with an "X". In this tutorial case, the interface will be named XHelloworld

Published

specifies if the interface is published or not. The published notion is translated into a keyword in UNO-IDL language. Declaring a UNO-IDL type as published means that it will not change in future releases: we will check it because this is far too complex for our example

Inherited interfaces

is a list of all the interfaces from which the one that is about to be created will inherit. This is one of the changes in UNO-IDL between OpenOffice.org 1.1.x and 2.0: that is why the plugin does not support OpenOffice.org version prior to 2.0. All the UNO-IDL interfaces are inheriting directly or not from the com::sun::star::uno::XInterface type. As the XHelloworld interface is very easy, there will be only this mother interface

"?" column

specifies if the interface inheritance is mandatory or not. If the box is checked, thus the interface inheritance is optional and may not be implemented.

"Add" and "Del" buttons

allows to add an interface to the inherited ones or removing the selected interface.

UNO-IDL interface creation wizard
Illustration 11: UNO-IDL interface creation wizard

Clicking one the Finish button will add a new UNO-IDL file named Xhelloworld.idl and a UNO-IDL text editor should be opened with the created file. There is now to add the sayHello() method to make the new interface ready for use. Of course you can add some Javadoc like comments to document your component API, but this will not be discussed in this tutorial. You will better have to look at the links section to go further on this point.

To add the sayHello() method, you just have to change the XHelloworld code into the following:

published interface XHelloworld{
 interface com::sun::star::uno::XInterface;

 /** is just saying hello to the caller.
     
     @return
    a string to say hello
       */
 string sayHello();
};

The interface is now correct, but do you remember that the service was exporting the XInterface interface? You will now have to change the interface to make the service exports the fresh XHelloworld interface. For this, just double-click on the Helloworld.idl file to edit it and change the code into the following:

#include <org/openoffice/helloworld/XHelloworld.idl>

module org {
 module openoffice {
  module helloworld {
   published service Helloworld : XHelloworld {
   };
  };
 };
};

Note that we have changed the UNO-IDL interface after the ":" of the service definition which corresponds to the exported interface. Since OpenOffice.org 2.0, a service can export only one interface, but this will be more detailed in the "Going further" section. We had to change the include line too: this works exactly as the C++ pre-compilation directives and has the same role as the Java imports.