How to create a Java component with Eclipse
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 LibreOffice 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.
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.
“A component is a system element offering a predefined service and able to communicate with other components” explains Wikipedia (Fr). 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.
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 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 LibreOffice: 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.
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 LibreOffice Eclipse integration minimal requirements are the following one:
-
LibreOffice
-
LibreOffice
-
Eclipse
-
Java
First of all, you will need to have a working LibreOffice and it's Software Development Kit (SDK). The last version are available on the LibreOffice download pages for the most current platforms.
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 LibreOffice development plugin for
Eclipse using the Eclipse Marketplace.
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 LibreOffice plugin update site is http://eclipse-plugins.libreoffice.org. 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 LibreOffice site is checked before clicking on the Finish button. You should now see a window like the one of the illustration 3. Select the LibreOffice 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 LibreOffice 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 LibreOffice 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 LibreOffice 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 LibreOffice SDK and validate. Then you will have to do the same for the LibreOffice path using the other Add button.
Note that a URE installation can be selected instead of a complete LibreOffice 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 LibreOffice 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 author.
[1] Even thought there is a definition on the English wikipedia article, I prefer the French one because of it completeness