OpenOffice Maven2 Integration

From Apache OpenOffice Wiki
Jump to: navigation, search

Overview

Maven is a well-know build framework for Java applications provided by the Apache foundation. It can be extended using plugins to perform custom actions. Maven manages the project dependencies which are fetched from remote or local repositories.

Some steps are missing in the Maven build to create and build OpenOffice.org extensions:

  • Generate Java classes from IDL files
  • Generate an OXT file to package the project
  • Create a simple OpenOffice.org extension project structure

Features

A Maven 2 plugin for OpenOffice.org extensions is currently under development. It already provides:

  • A goal to generate the Java classes from the IDL files
  • An archetytpe for the structure of an OpenOffice.org Extension project

Generating an Extension project

This will be done, by using a maven archetype for Uno projects. Here are the parameters to pass to maven execution to create an test-uno project.

[bash] mvn archetype:generate \

 -DnewGroupId=org.openoffice.dev.tests         \
 -DnewArtifactId=ooo-ext-test                  \
 -DnewVersion=1.0                              \
 -Dpackage=org.openoffice.dev                  \
 -DarchetypeGroupId=org.openoffice.dev         \
 -DarchetypeArtifactId=maven-ooo-plugin        \
 -DarchetypeVersion=1.1

The started project will create the file and folder structure to place IDL folders and the Java sources. It will also add a generic UNO registration class like the one described by this blog post. The generated project pom.xml will contain dependencies to the OOo libraries and the needed basic configuration to run the goals provided by this maven2 plugin.

The generated project will be structured in order to fit the UNO extension packaging needs. This is not yet fully determined, but will need to be studied.

Building the IDL files

To build the IDL files, some additional configuration will be needed in the project pom.xml. The configuration will be like the following: [xml]

 <build>
   <plugins>
     <plugin>
       <groupId>org.openoffice.dev</groupId>
       <artifactId>maven-ooo-plugin</artifactId>
       <version>1.0</version>
       <configuration>
         <idlDir>${basedir}/src/main/idl</idlDir>
         <ooo>/path/to/an/ooo/installation</ooo>
         <sdk>/path/to/an/ooo/sdk/installation</sdk>
       </configuration>
       <executions>
         <execution>
           <phase>generate-sources</phase>
             <goals>
               <goal>build-idl</goal>
             </goals>
         </execution>
       </executions>       
     </plugin>
   </plugins>
 </build>

The configuration for idlDir is new in 1.1 and can be ommitted if you use src/main/idl as default path (as in this example).

This Mojo configuration is not really clean, because it needs to define the path to an OpenOffice.org installation and the to OOo SDK. A solution would be to provide a default guess for the OOo installation path. This feature will be available in 1.1 but don't expect that it will work for all OS'es and installations.

Another solution is to use System Properties for the locations. System Properties can be set in the users Maven2 settings.xml (.m2/settings.xml) ie: [xml] <?xml version="1.0"?> <settings xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">

 ...
 <profiles>
   <profile>
     <id>default</id>
     ...
     <properties>
       <ooo>/path/to/an/ooo/installation</ooo>
       <sdk>/path/to/an/ooo/sdk/installation</sdk>
     </properties>
     ...
   </profile>
 </profiles>
 <activeProfiles>
   <activeProfile>default</activeProfile>
 </activeProfiles>

</settings> Now, in the pom you can refer to the variables by ${ooo} and ${sdk} like this: [xml] ...

       <configuration>
         <ooo>${ooo}</ooo>
         <sdk>${sdk}</sdk>
       </configuration>

... I think this is the best solution which is available in Maven2. It allows you to use the same pom file for your buildserver and local development environment. Even it allows multiple OpenOffice versions if you give the properties other names.

Using this configuration the Java classes corresponding to the UNO types defined in the IDL files, are generated before the Java compilation phase. Using the standard maven build command is enough: [bash] mvn generate-sources

Creating a new UNO type implementation

This feature is not yet developed

Creating a new UNO type implementation is quite hard. The maven plugin will provide a goal to create a skeleton for the implementation of a UNO type, either of the extension project or an OpenOffice.org one. This goal will delegate the skeleton creation to the uno-skeletonmaker tool.

It could be invoked in the following way: [bash] mvn ooo:skeleton \

   -Dtype=the.type.to.implement        \
   -DimplementationName=the.class.name \
   -Djava.version=1.4

The java.version parameter would be optional and could be set to 1.4 or 1.5 to indicate which version of Java the implementation will support.

This Mojo will run the uno-skeletonmaker and add the new implementation to the implementations list of the project.


Building the IDL files

As a first example for an IDL file you find a little WorldInterface.idl in the src/main/idl directory:

#ifndef __hello_WorldInterface_idl__
#define __hello_WorldInterface_idl__
module hello {    

    interface WorldInterface {
		void print();
    };

};
#endif

This example and other UNO types defined in the IDL files are generated before the Java compilation phase. To do this start

mvn generate-sources

The result of the idlc command is stored in the target/urd directory.


Generating the OOo-Plugin

mvn package

generates the OpenOffice extension. You’ll find the generated plugin ooo-ext-test-0.1-SNAPSHOT.oxt in the target directory.

Installation...

...as Maven Artifact

Normally the generated OOo plugin is installed direct as OOo plugin. If you don’t want this and want to install the OOo plugin as artifact into your local Maven repository you can use the system property “org.openoffice.maven.install=repository”:

mvn -Dorg.openoffice.maven.install=repository install

In this case the generated OOo plugin is not installed into OpenOffice but you find it in your local Maven repository which is normally located into your home directory under .m2/repository.

...as OOo-Plugin

Be sure thet the plugin isn’t installed already. If yes call unopkg remove ooo-ext-test-0.1-SNAPSHOT.oxt. Then you can install the generated OOo plugin of the previous step with the ‘unopkg’ command (‘unopkg add -v ooo-ext-test-0.1-SNAPSHOT.oxt’). Or you can use the install phase of Maven and call:

mvn install

To verify if the OOo plugin is really installed you can start OpenOffice and select the extension manager of you can use unopkg list from the commandline. If you start ‘unopkg’ be sure OpenOpffice is not running!

Uninstalling the OOo-Plugin

You can use OpenOffice’s extension manager or unopkg remove ooo-ext-test-0.1-SNAPSHOT.oxt to deinstall the OOo plugin.

To verify if the OOo plugin is really deinstalled you can start unopkg list from the commandline and see if plugin is absent.

Getting started

In the past the sources were located on the API project CVS: http://api.openoffice.org/source/browse/api/maven2integration/. But these sources are out-of-date.

The actual sources are located now at http://github.com/fredericmorin/maven-ooo-plugin.

...

Explain how to get started with the development and how to use the plugin.

...

Repository

If you want to use the latest snapshot (1.1-SNAPSHOT) of the maven-ooo-plugin you can use the repository at http://labs.agentes.de/repository/ and add the following lines to your POM:

<repositories>
  ...
  <repository>
    <id>agentes</id>
    <name>agentes repository</name>
    <url>http://labs.agentes.de/repository/</url>
  </repository>
  ...
</repositories>


Troubleshooting

The only problem with troubleshooting is, that sometimes the trouble shoots back!

It can have many reasons why the registration or activation of an OOo plugin can fail. Some of the known reasons are listed here.

Some General Hints

If you install your OOo plugin with the extension manager and it fails try to install it manually using the unopkg command. There is an option "-v" available which gives you some verbose infos:

unopkg add -v ooo-ext-test-0.1-SNAPSHOT.oxt

Environment "OO_SDK_HOME" not set

You'll need the OpenOffice SDK on your system. If it was installed at the usual place (e.g. "C:\Program Files\OpenOffice.org 3\Basis\" under Windows) it is automatically recogniced. If not you will get the following error message:

...
[ERROR] Error during idl-build
java.lang.IllegalStateException: call setOoSdkHome() if environment "OO_SDK_HOME" not set
	at org.openoffice.maven.Environment.getOoSdkHome(Environment.java:213)
	at org.openoffice.maven.ConfigurationManager.getSdk(ConfigurationManager.java:152)
	...

In this case set the environment variable "OO_SDK_HOME" to the installation directory of the OpenOffice SDK.

DeploymentException

ERROR: (com.sun.star.deployment.DeploymentException) { { Message = "Fehler beim Aktivieren von: ooo-ext-test-0.1-SNAPSHOT.oxt", Context = (com.sun.star.uno.XInterface) @3ccb98c }, Cause = (any) { (com.sun.star.registry.CannotRegisterImplementationException) { { Message = "", Context = (com.sun.star.uno.XInterface) @0 } } } }

If you see this (or a similar) error message there can be many reasons for such a DeploymentException (see also http://oli.blogger.de/stories/1717382/):

  • an incomplete classpath entry in the generated manifest file,
  • a missing __writeRegistryServiceInfo,
  • a missing __getComponentFactory method in a Java component or
  • others.

If you have generated your project from scratch (as described in this article) you'll find a OOoDiagnostics class in your sources which can help you to examine the classpath problem (and also the missing methods):

  1. unpack your generated OOo plugin into an empty directory: unzip ../ooo-ext-test-0.1-SNAPSHOT.oxt
  2. start the main method: java -cp ooo-ext-test-0.1-SNAPSHOT.jar org.openoffice.dev.OOoDiagnostics

Adapt the jar file name and OOoDiagnostics package to your environment. If the check was ok you see the following output:

=============================
Starting some diagnostics ...
=============================
class org.openoffice.dev.RegistrationHandler found
java.lang.NoClassDefFoundError: com/sun/star/lang/XSingleComponentFactory - required methods are not checked
=============================
Diagnostic succesful finished
=============================

Because the check is started outside OpenOffice the OOo jars are missing. But you can add it the classpath:

java -cp ooo-ext-test-0.1-SNAPSHOT.jar:/opt/ooo/OpenOffice.org.app/Contents/basis-link/ure-link/share/java/ridl.jar org.openoffice.dev.OOoDiagnostics

This example was started on a Mac where OpenOffice is installed at /opt/ooo/. For your system look at e.g. the file "ridl.jar" to find the missing OOo jars. If all is ok you'll see the following output:

=============================
Starting some diagnostics ...
=============================
class org.openoffice.dev.RegistrationHandler found
public static com.sun.star.lang.XSingleComponentFactory org.openoffice.dev.RegistrationHandler.__getComponentFactory(java.lang.String) found
public static boolean org.openoffice.dev.RegistrationHandler.__writeRegistryServiceInfo(com.sun.star.registry.XRegistryKey) found
=============================
Diagnostic succesful finished
=============================

As you can see that the required methods (__getComponentFactory and __writeRegistryServiceInfo) are checked now.

More Infos

Personal tools