JavaEclipseTuto

How to create a Java component with Eclipse

Introduction

This paper is a tutorial to guide UNO newcomers to create their first Java component. This tutorial will use Eclipse and it's plugin for the OpenOffice.org development. Of course, every step will be detailed, but if your are still an experienced UNO programmer, you can have a look at the next pages to have a better view of how to use the Eclipse plugin.

UNO Components

This section will explain some very basic things about UNO components. You might skip it if you already know it. First I will explain what is a component and it's mains parts. Afterwards, I will explain what is needed to create a UNO component to help you to fully understand the different tools and their use during the tutorial.

Components anatomy

"A component is a system element offering a predefined service and able to communicate with other components" explains Wikipedia (Fr) (Even thought there is a definition on the English wikipedia article, I prefer the French one because of it completeness). In UNO case a component will generally be delivered as a package containing a library (share library in C++ or jar in Java). For UNO a component is made of two distinct parts: specifications and an implementation.

• Specification: definition in a common language of what the component should do. For UNO, this language is called UNO-IDL and is more or less similar to Corba IDL. The documented part that will be provided as an API to use the component is the specification. Thus it should be complete and implementation independent.
• Implementation: is the code that will realize what is described in the component specifications. This programming language can either be C++, Java, Python or some others. This is the internal part of the component and will not be accessible from another component.

In order UNO knows which implementation corresponds to which specification, the component will use registries. There are two of them: the first one describes all the component specifications (types.rdb) and the second translates the implementation into specifications (services.rdb) and is generated from the implementation.

Components creation process

To help you better understand what should be done to get a component from it's specification and sources, you should have a look at the next illustration. As shown by the diagram, the specifications are compiled and merged into one types.rdb registry. Class files are generated from that file to translate the specifications into a Java class definition file which is build with the implementation into class using the java compiler. All the classes are delivered as a jar file with a specific manifest as we will see further in this tutorial. This doesn't make a usable OpenOffice.org: the types.rdb and jar file will have to be zipped into a .uno.pkg file described with another manifest.

As I will explain it later, the Eclipse plugin will hide some of these operations, however you will need to know how they work to fully understand the build process and what we will do in the next steps.

Installing the development platform

Now that you perfectly know what to do, we will install and configure the development tools. This is quite simple but you might be trapped into some problems if you don't read the next lines carefully. I will now assume that you have none of the development tools. The OpenOffice.org Eclipse integration minimal requirements are the following one:

• OpenOffice.org 2.0
• OpenOffice.org SDK 2.0.4
• Eclipse 3.2
• Java 1.5 (the GNU Java doesn't work with the Eclipse integration)

OpenOffice.org

First of all, you will need to have a working OpenOffice.org 2.0 and it's Software Development Kit (SDK). The last version are available on the OpenOffice.org download pages for the most current platforms. The OpenOffice.org SDK version 2.0.4 is mandatory to use the plugin correctly. It includes a new tool used by the plugin: the uno-skeletonmaker. This tool will generate the implementation skeleton to help you to concentrate only on your code.

This tutorial assumes that you used the "Official" OpenOffice.org distribution from the project's website. Other distributions may not work with the Eclipse integration.

Eclipse and the plugin

To get Eclipse, just get to their download pages and download the last Eclipse SDK. You will have Eclipse and it's SDK. Of course, you might want to download only the binary runtime, but you will have to follow more links. Once you have Eclipse, unzip it on your computer and that's it: eclipse has a Java plugin to help you program in Java.

Now we will install the OpenOffice.org development plugin for Eclipse using the Eclipse software update system. Do not try to download an archive somewhere: Eclipse will do it for you during the next steps. Select the Help > Software updates > Find and install menu to get the window of the next illustration. Check the second option on this window and click on the Next button.

On the following page, you will see a list of "update sites". These are URLs pointing to directories containing plugins informations and archives. Now click on the Add remote site button to get a small window asking for a name that will be displayed in the list and an URL. The URL of OpenOffice.org plugin update site is http://cedric.bosdonnat.free.fr/ooeclipseintegration.

Do not hope to get an archive to download here: it's the update site for Eclipse.

Then validate the new update site parameters and be sure that the OpenOffice.org site is checked before clicking on the Finish button. You should now see a window like the one of the next illustration. Select the OpenOffice.org plugin Core and Java plugins, click next and let the wizard guide you through the end of the process. You will be asked to accept the plugin licence and validate the installation archives which are not signed.

Congratulations, you have installed the OpenOffice.org plugin successfully, there is now to configure it. The following steps will guide you through this task. Go to the Eclipse options via the Window > Preferences... menu. In the list on the left, select the OpenOffice.org plugin > SDK configuration item to get a window like the one shown by the next illustration.

In this window you will have to configure the path to your OpenOffice.org and to it's SDK. So let us begin with the SDK path: click on the Add button next to the SDKs list. You will have a window like the next illustration, browse to your OpenOffice.org 2.0 SDK and validate. Then you will have to do the same for the OpenOffice.org path using the other Add button.

Note that a URE installation can be selected instead of a complete OpenOffice.org installation. Please report to the Java URE application tutorial for more details on the plugin's URE support.

Please make sure that the path to the SDK doesn't contains any space on Windows: it could cause some problems when building your UNO projects afterwards.

Now your OpenOffice.org plugin is ready to work: you can begin to create your new component. If there was any problem during the plugin installation, do not hesitate to report it to the dev@api.openoffice.org mailing-list.

Creating a new component

For the Eclipse plugin, a UNO component is a UNO project. This tutorial will explain how to easily create a new UNO component using the Eclipse plugin. We will now assume that you have very simple needs: the component that will be created is a "Hello world" service and its implementation. Creating a component defining and implementing more services is a bit more complex and need advanced Java UNO knowledge.

There are several ways to create a UNO component project using the plugin:

• the first one is the File > New > Project menu entry and choose the UNO > UNO-IDL Project item as shown by the next illustration.

• the second one is the icon in the toolbar representing a blue folder with a star as show by the next illustration.

Then you only have to follow the wizard to create your UNO component project, its specification and a skeleton of implementation. This wizard is composed of several pages:

• The main configuration page to define the general project properties
• The implementation language configuration page.
• The service configuration page
• The interface configuration page

After all these steps you can get a running component... doing nothing. The next sections will describe the different wizard pages and where to place your code.

The project configuration page

The first page in the project wizard is the only page containing fields that need to be filled. All the others have default values to help you through the component creation. In our case, we will need all the pages to explain them all and define some mew methods and attributes in our component.

• Project name: is the component name, in our case, it will be "Helloworld"
• Location: is the directory on your computer where the project will be created. You can change the default one by deselecting the Use default check box. The default location of each Eclipse project is a directory with your project name in the current Eclipse workspace. Please avoid spaces in this path on Windows: it could prevent your component to be built.
• Root package: is the name of the first module of your component. It generally composed of two parts: the vendor name (here org.openoffice) and the project name (here helloworld).
• Used SDK: selects the OpenOffice.org SDK which will be used to develop the component. You generally will have only one SDK in the list, but you can add others in the preferences or by clicking on the Configure SDKs button.
• Used OOo: selects the version of OpenOffice.org to use to develop the component. As for the SDK, you will generally have only one entry in the list, but you can add others in the preferences or by clicking on the OOo Installations button.
• Programming language: selects the programming language for the component implementation. For the moment, there is only Java available, however C++ and python are planned.

The implementation language configuration page

This page depends on the chosen language. For Java, the default values should be kept: they define which class is the main class of the component. The component's main class contains some code mapping the services to their implementation.

The service configuration page

• Module: 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).
• Service name: is the service name. By keeping the default value, you will be able to define your own interface using the interface configuration page. Otherwise, you can reuse an existing interface.
• 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 keep it unchecked because our component is really far from being a stable API.

The interface configuration page

• Module: 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).
• 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.
• 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 more or less directly from the com::sun::star::uno::XInterface type. As the XHelloworld interface is very easy, no super interface will be added: that will implicitly define XInterface as the only parent for the new 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.
• Members: is a list of all the methods and properties of the interface. See the explanations about the members some lines below. In this tutorial, just create one string sayHello([in] boolean isBadBoy) method and a LadyName property.
• 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 keep it unchecked because our component is really far from being a stable API.

A UNO interface can contain two kind of members: methods and properties. When clicking on the Add button near the members' list, the following window will be shown. When double-clicking on a line in the members' list, you will edit the corresponding member through the same window.

When the window is opened to create a new member, you can choose whether the member will be a property or a method. The name and returned type fields are always present, but the lower part of the dialog is different for a method and a property.

• The arguments list: defines the name, type and direction of the parameters of the method. Simply click on the cell to edit it.
• Read-only and Bound check boxes: selecting these boxes sets the corresponding IDL flag on the property.

Tip: you can use Ctrl+Space to complete the type name in the Return type field and Type column.

Writing the implementation

After having completed the wizard, you need to write the component implementation. Hopefully a skeleton has been generated and opened: you just need to complete the code where there are some TODOS. The generated project contains the following directories and files to know:

• source: directory containing your Java implementation classes
• build: directory containing 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: directory containing the specifications of the component
• types.rdb: generated UNO types registry from which the classes 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.

The generated skeleton already contains the methods for the implementation registration. The only things to modify are:

• Change the code of the setters and getters for the defined properties
• Change the code of the defined methods.

The Eclipse integration even manages the libraries needed by your implementation. Let us imagine, that we want to use the Fraction class from the Apache common-math jar. Download this jar from the Apache website, and import the common-math-1.1.jar file into your component project: for example in a lib directory. Add the jar to the project build path in the same way than in any other Eclipse Java project and use it:

[java]

   // org.openoffice.helloworld.XHelloworld:
   private String mLadyName = "";
   
   public String getLadyName()
   {
       return mLadyName;
   }

   public void setLadyName(String the_value)
   {
       mLadyName = the_value;
   }

   public String sayHello(boolean isBadBoy)
   {
   	String hello = "Hello Mrs. " + getLadyName();
       if (isBadBoy) {
       	Fraction f = new Fraction(1, 3);
       	hello = "A third is " + f.doubleValue();
       }
       return hello;
   }

The above code show you what could be an implementation of our component. Now, there is only to package it properly and test it.

Packaging and testing the component

The next lines will show you how to export your component into an OpenOffice.org package. There is quite nothing to do apart from following these small steps:

• Select the File > Export menu. Then choose the UNO > OpenOffice.org package export type.
• The next page of the wizard, asks for the UNO project to export (already selected), the directory where to export the package and the OpenOffice.org minimum compatibility version for the package. Depending of the selected OpenOffice.org version, the package will get a different name and a different structure.
• Then click on the Finish button. The wizard will ask you whether to deploy to package or not and asks for the old package removal if needed.

Then we will suppose that the package is deployed on the OpenOffice.org installation and we will test it using the following OooBasic macro.

[oobas] Sub testHelloworld oHelloworld = createUnoService( "org.openoffice.helloworld.Helloworld" ) oHelloworld.LadyName = "Robinson" print oHelloworld.sayHello( false ) print oHelloworld.sayHello( True ) End Sub

This macro should open two message windows with "Hello Mrs. Robinson" and "A third is 0.3333333". Your first UNO component is now running, enjoy doing others.

Going further

This chapter is only for those who enjoyed this tutorial and want to know more about the UNO component creation in Java or other languages. You will have a list of useful links for any UNO developer in the next line.

• OpenOffice.org developer's guide is a huge source of documentation for any OpenOffice.org developer. You should probably have a look at the chapters 3 and 4 for UNO components informations.
• OOo Java reference is the UNO binding for Java reference.
• OOo C++ reference is the UNO binding for C++ reference.
• OOo Developer's Wiki is the wiki for all the OpenOffice.org developers. It contains very useful informations even for people who just begin with UNO.
• http://udk.openoffice.org/common/man/draft/multinherit.html for further informations on what changes in UNO-IDL between OpenOffice.org 1.1.x and 2.0
• Autodoc Java reference is the reference for javadoc like comments in UNO-IDL files.
• Autodoc C++ documentation is the reference for javadoc like comments in C++ components.
• URE C++ application tutorial explains how to create a C++ application based on the URE, that is a UNO C++ component that does not need OpenOffice.org.