An interface is a collection of methods that provide a certain
functionality. In order to provide a language-independent programming
environment, all interfaces must be described in an interface
definition language (IDL). As a rule, Universal
Network Objects interfaces are specified in the UNO
IDL and must be derived from a mandatory base interface (com.sun.star.uno.XInterface).
This base interface provides three methods: queryInterface(),
acquire(), and release(). Because UNO supports multiple interfaces,
the queryInterface() method is necessary for navigating between
the different interfaces (comparable to COM). The acquire() and
release() methods handle the life cycle of UNO objects (global
reference counting).
In the following one describes, which steps have to be accomplished,
in order to provide an interface definition language file. The
interface org.openoffice.XTest with a method getNumber() should
exemplify the creation of an IDL file.
Mounting directories
Invoking the IDL wizard
Creating modules
Creating interfaces
Creating methods
Creating IDL files
Compiling IDL files
Mounting directories
Before an IDL can be provided with the help of the IDL Wizard,
the desired working directory should be mounted in file system
explorer window of the integrated development environment.

Further on, the necessary module structure should be created
in this work directory. That is, if an interface "org.openoffice.XTest"
is to be provided, a directory "org/openoffice" has
to be created in the working directory. In the future the creation
of the necessary directories for the interface will be performed
by the Wizard.

Invoking the IDL
wizard
If you choose New/OpenOffice.org SDK/New IDL type from the context
menu of the target directory, the window with the title "New
From Template Wizard" is displayed.

Because the name of the IDL file should be the same as the name
of the interface, you should insert your favored name with a leading
"X". Every interface for OpenOffice.org 1.0.2 should begin
with the uppercase character "X".

The next dialog allows you to design your IDL file.

Creating modules
At first you should select the element referred to as "Module".

If you select the button "create" a dialog will pop
up. Here, you can insert the name of your module.

The new module is displayed like an directory.

Further modules can be provided in the manner described above.

Creating interfaces
Then you have to select the element referred to as "Interface".

After pressing the button "create", in a new window
dialogue the name of the interface and its basis interface must
be entered.

Thereafter you have to select the element referred to as "Operation".

Creating methods
After pressing the button "create", in a new window
dialogue the name of the method, its return type, its parameters,
and its exceptions must be entered.
All inputs must satisfy for the UNO
IDL syntax.
The following table shows the mapping of IDL basic types to the
corresponding Java types.
IDL
|
Java
|
boolean |
boolean |
short |
short |
unsigned short |
short |
long |
int |
usigned long |
int |
hyper |
long |
unsigned hyper |
long |
float |
float |
double |
double |
char |
char |
byte |
byte |
string |
java.lang.String |
any |
com.sun.star.uno.Any |
type |
com.sun.star.uno.Type |
void |
void |
If you want to know more about allowed return types, you should
visit the following web page:
Mapping
of Uno IDL to Java.
The parameter definition begins with the direction flag which
is bound with [ ]. Valid flags for the direction are in ( in parameter),
out (out parameter) or inout (in and out parameter). The direction
follows an identifier for the parameter type and an identifier
for the parameter name. More than one parameter definitions are
separated by comma.
The definition of an exception begins with the keyword exception
following by the identifier of the exception. The body of the
definition is bound with { } and the complete definition ends
with a semicolon. Inside the body it is possible to define some
members. A member definition begins with the identifier of the
type following by the identifier of the member name. The definition
end with a semicolon. The body of the structure is a new namespace.
Inside this namespace it is possible to use all identifiers as
names which are definite. It is possible to define an inheritance
for the exception. An inheritance will be defined after the name
identifier by a colon following an identifier of the parent exception.
Inheritance of exceptions is UNO specific and not CORBA compatible.
Oneway means that the function is asynchronous and don`t wait
for a reply. To use this flag the function must return void, don`t
take any out or inout parameters and don`t raise an exception.

In this way the IDL wizard serves for the representation, navigation,
and editing of tree-like, hierarchical data structures.

Creating IDL files
After finishing the IDL wizard, a new IDL file will be created
in your working directory.

Compiling IDL files
If you choose Compile from the context menu, three files will
be generated: An URD file, a RDB file, and a Java file.

In order to get these three files, the OpenOffice.org 1.0.2 Support
Module uses three SDK tools: IDL Compiler, Registry Merge Tool,
and Java Maker.
The IDL Compiler transforms the interface definitions written
in IDL into an URD file.

The URD file is then going to be merged into the type library
"types.rdb". Registry Merge Tool is a small tool to
merge different registry files under a specified key into another
registry file.
The Java Maker generates the appropriate java file for each idl
type.

|