NetBeans/Sun ONE Studio 4 Integration   SDK home
Sun One Studio 4 Integration | Wizards | IDL Wizard | UNO Component Wizard | Calc Addin Wizard | Deploying Components
 
IDL Wizards - Providing interfaces for your service

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.

 

Copyright 2003 Sun Microsystems, Inc.