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 its plugin for the OpenOffice.org development. Of course, every step will be detailed, but if you 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 a component is and what its main parts are. 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 (shared 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 its specification and sources, you should have a look at the illustration 1. 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.

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.

If you have installed OpenOffice.org using a different distribution, please check that you have the development package. This tutorial assumes that you used the "Official" OpenOffice.org distribution from the project's website.

Eclipse and the plugin

To get Eclipse, just get to their download pages and download the last Eclipse SDK. You will have Eclipse and its 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. Select the menu: Help > Software updates > Find and install, you should get the window of the illustration 2. 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

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 illustration 3. Select the OpenOffice.org plugin as shown on the screen-shot and click next and follow the indications. You will be asked to accept the plugin licence and validate the installation the archive 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 illustration 4.

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 illustration 5, 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.

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, an UNO component is a UNO project. Thus the first step will consist in creating the project. Next, you will need to write the UNO-IDL specifications of your component and then implement them.

This tutorial will guide you in the "Hello world" component creation. The component you are about to create just says hello when you ask him to do so.

Creating the project

There are several ways to create a UNO 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 illustration 6.

the second one is the icon in the toolbar representing a blue folder with a star as shown by the illustration 7.

Next you have to fill in a form (see illustration 8) to configure your project: the next lines will describe the different fields and their meaning to help you fill them.

Project name: is the component name, in our case, it will be "Helloworld"
Directory: 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.
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.

You can now click on the "Finish" button or "Next" if you are eager to know a bit more on what will happen during the project's creation. For this tutorial we will go further to better understand what you will get after the wizard. In fact the next step in the wizard will consist in configuring an empty service for the component. The default name of this service is the project name and it implements the com.sun.star.uno.XInterface interface. However you can change the default interface by clicking on the "Browse" button which will provide you a list of the known interfaces.

As we will define a new interface for our Helloworld service, we will keep the default values and change the interface name when we will have created it.

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.

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 > New > Other 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.

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.

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:

[unoidl] 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:

[unoidl]



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.

Writing the implementation

You now have complete specifications for your component, but there is still the implementation to do. For the moment, the plugin doesn't assist you enough and you will have to copy-paste some code that could be automatically generated in next version. The tutorial will now assume that you know how to handle Java code in Eclipse, otherwise it would be too long to read.

Implementing the code

To implement the code, you will create a new Java class named HelloworldImpl in the implementation package, that is: org.openoffice.helloworld.comp. This class will extend com.sun.star.lib.uno.helper.WeakBase and implement XHelloworld. This is a quite difficult part to understand: the UNO-IDL interface is translated into a Java interface and we implement the interfaces. The mapping between the UNO-IDL service and its implementation will be done in the next chapter of this tutorial.

The WeakBase class which is extended is a helper to implement some other basic interfaces. In our tutorial, we will need it only to implement the com.sun.star.lang.XTypeProvider interface used by OpenOffice.org basic to get an access to the component's methods and attributes.

If you checked the "Inherit abstract methods" box in the class wizard, you can note that the XHelloworld method sayHello() is added to the generated code. The implementation will just consist in filling the empty body of this method. Thus you can change the code to the following:

[java] public String sayHello() {


   return "Hello UNO world from Java";

}

Of course, serious components will have more complex specifications and implementations, but it is a beginning: just a simple standard "Hello world".

The registration class

Now that our interface is implemented, we will need to make the link between the service and its implementation. This would perhaps be performed automatically in future versions of the plugin, but we still have to do it now. You will just have to copy the following code in your HelloworldImpl class. I will not explain this code here, because it should be created automatically and is only a rearranged copy-paste from the OpenOffice.org Developer's Guide. If you are interested in this topic, please report to the "Going further" section of this tutorial. You just have to remember that the class containing this code is named "Registration class" because you will need to give its name to package the component.

[java] /** is used by the registration methods to return the implemented


*  service name.
*/

final static String __serviceName = "org.openoffice.helloworld.Helloworld";
public static XSingleServiceFactory __getServiceFactory( 

               String implName, 
               XMultiServiceFactory multiFactory, 
               XRegistryKey regKey){

   XSingleServiceFactory xSingleServiceFactory = null;

   if (implName.equals(HelloworldImpl.class.getName())) {
       xSingleServiceFactory = FactoryHelper.getServiceFactory(
                HelloworldImpl.class, __serviceName, 
                multiFactory, regKey);
   }

   return xSingleServiceFactory;

}
public static boolean __writeRegistryServiceInfo(

               XRegistryKey regKey) {

   boolean b = FactoryHelper.writeRegistryServiceInfo(
                   HelloworldImpl.class.getName(), 
                   __serviceName, regKey);
   return b;

}

Testing the component

There is now to package and test our component. This part will be a bit more hard because the plugin does not support these features for the moment. The following lines will not explain all the code in details because this should be done by the plugin in future versions. However it is necessary now to test our work.

Packaging the component

The package component is a zip containing the UNO-IDL types registry (types.rdb) and a jar with the compiled classes. To generate this, we will create an Ant build file (build.xml) with the following code:

[xml] <?xml version="1.0"?> <project name="Helloworld" default="package">


   <description>
           This ant file is only to package the Helloworld component
   </description>

   <property name="out.path" value="bin/ant"/>

   <target name="package" depends="purge">

   	<mkdir dir="${out.path}" />		
   	<copy todir="${out.path}" file="types.rdb">
   		<fileset dir="bin">
   			<include name="**/*.class" />
   		</fileset>
   		<fileset dir="build">

			<include name="**/*.class" />

   		</fileset>
   	</copy>
   	
   	<jar basedir="${out.path}" includes="**/*"
   		excludesfile="types.rdb"
   		destfile="${out.path}/Helloworld.jar">
   		<manifest>
   			<attribute name="RegistrationClassName" 
   				value="org.openoffice.helloworld.comp.HelloworldImpl"/>
   		</manifest>
   	</jar>
   
   	<mkdir dir="${out.path}/META-INF" />
   	<copy todir="${out.path}/META-INF" file="manifest.xml" />
   	
   	<zip destfile="${out.path}/helloworld.uno.pkg" basedir="${out.path}" 
   		includes="Helloworld.jar,META-INF/manifest.xml,types.rdb" />
   	
   </target>

   <target name="purge">
       <delete dir="${out.path}" />
   </target>

</project>

You will also need to create a manifest.xml file containing a description of the zip file. The syntax of these files is detailed in the OpenOffice.org Developer's Guide and will not be explained here. You just have to create the file at the project's root with the following XML code:

[xml] <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">

<manifest:manifest>


  <manifest:file-entry 
          manifest:full-path="Helloworld.jar" 
          manifest:media-type="application/vnd.sun.star.uno-component;type=Java"/>
  <manifest:file-entry 
          manifest:full-path="types.rdb" 
          manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=RDB"/>

</manifest:manifest>

You are now ready to execute the newly created ant script to generate the package bin/ant/helloworld.uno.pkg. To perform this action, you will have to open the Ant view by selecting the Window > Show View > Ant menu item. You now have a tab like the one presented by the illustration 12. In this view, click on the ant icon to add your build.xml file to the list of ant files. You can now execute the package target by double-clicking on it in the Ant view. The build output is also shown in the Eclipse console view.

If the console show you a result similar to the one below, then your component has been successfully generated. To see the generated files you can switch to the Resource perspective: they are generated in the bin/ant folder which is hidden in the Java package explorer.

Buildfile: /home/chef/develOOoppement/eclipse/Helloworld/build.xml
purge:
package:
    [mkdir] Created dir: /home/chef/develOOoppement/eclipse/Helloworld/bin/ant
     [copy] Copying 4 files to /home/chef/develOOoppement/eclipse/Helloworld/bin/ant
      [jar] Building jar: /home/chef/develOOoppement/eclipse/Helloworld/bin/ant/Helloworld.jar
    [mkdir] Created dir: /home/chef/develOOoppement/eclipse/Helloworld/bin/ant/META-INF
     [copy] Copying 1 file to /home/chef/develOOoppement/eclipse/Helloworld/bin/ant/META-INF
      [zip] Building zip: /home/chef/develOOoppement/eclipse/Helloworld/bin/ant/helloworld.uno.pkg
BUILD SUCCESSFUL
Total time: 1 second

Testing using OpenOffice.org macros

You will now have to test the component using OpenOffice.org macros. There are two steps for this:

Add the component to the package manager. In OpenOffice.org 2.0 open the package manager using the tools > package manager menu item. Next select the "My Packages" category and click on the "Add" button. You just have to select the bin/ant/helloworld.uno.pkg file in your project and check that the package is activated.
Writing and executing a basic macro call the sayHello() method.

Now you will create and execute a basic macro containing the code below. You should see a small window with the "Hello UNO world from Java" or whatever text you returned in your implementation.

[oobas] Sub TestHelloworld helloworld = createUnoService("org.openoffice.helloworld.Helloworld") print helloworld.sayHello() End Sub

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 IDL 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.
A simple Calc addIn in C++
An other addIn in C++
Using Java Inspector in C++

Public Documentation License Notice

The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the "License"); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at http://www.openoffice.org/licenses/PDL.html.

The Original Documentation is "UNO Java component creation explained". The Initial Writer of the Original Documentation is (JCA) Cédric Bosdonnat (C) 2006. All Rights Reserved. (Initial Writer contact(s): cedricbosdo@openoffice.org.)

Note: The text of this Appendix may differ slightly from the text of the notices in the files of the Original Documentation. You should use the text of this Appendix rather than the text found in the Original Documentation for Your Modifications.

JavaEclipseTuto

Contents