Documentation/DevGuide/JavaBean for Office Components

This chapter describes the  component, a generic Java Bean wrapper for LibreOffice components. It is assumed that the reader is familiar with the Java Beans technology. Additional information about Java Beans can be found at https://docs.oracle.com/javase/tutorial/javabeans/.

With the, a developer can easily write Java applications, harnessing the power of LibreOffice. It encapsulates a connection to a locally running LibreOffice process, and hides the complexity of establishing and maintaining that connection from the developer.

It also allows embedding of LibreOffice documents within the Java environment. It provides a Java AWT window into which the backend LibreOffice process draws its visual representation. This window can then be plugged into the UI hierarchy of the hosting Java application. The embedded document is controlled from the Java environment, since the  allows developers to access the complete LibreOffice API from their Java environment giving them full control over the embedded document, its appearance and behavior.

Using the OOoBean
The Java class  can be instantiated directly, or application classes can be derived from this class. If a real Java Bean is to be created, which for example can be used in Java Bean UI builders, it has to be subclassed. The application class then might use the UNO bootstrapping mechanism to find the, LibreOffice and its API classes. This mechanism is not built into  itself because it can not be used to find itself. And once the  class has been found, you intrinsically also find the LibreOffice installation and the API classes.

A standard LibreOffice is a prerequisite. The LibreOffice executable, as well as the UNO libraries and runtime, is found using the Java Class Loader. Moving or copying the needed class files will not result in a working.

The OOoBean by Example
The  is a Java application that displays LibreOffice documents in a Java AWT applet, which allows for the control of some toolboxes, the menu bar and the status bar, as well as storing and loading the document content to/from an internal buffer.



The  utilizes the class   directly without subclassing it:

Initially, the OOoBean component does not contain a document. A document can be created with the loadFromURL method:

Some tool windows of the document window within the Java Bean can be controlled directly by the OOoBean API. For example, to toggle visibility of the menu bar:

The examples above provide an overview of how the  API is used to create Java Beans that can be used in Java applications and applets. For concrete Java Beans, you usually subclass  and create appropriate BeanInfo classes for integrating within an IDE (Integrated Development Environment), such as the Bean Development Kit or Forte for Java. Developers can use the examples as a guideline when using the  API to write new beans, or use or extend the example beans.

API Overview
The OOoBean offers methods that can be applied to all LibreOffice document types.

Configuring the Office Bean


The fundamental framework of the Office Bean is contained in the officebean.jar archive file that depends on a local library officebean.dll or libofficebean.so, depending on the platform. The interaction between the backend LibreOffice process, officebean local library, Office Bean and the Java environment is shown in the illustration below.

The Office Bean allows the developer to connect to and communicate with the LibreOffice process through a named pipe. It also starts up a LibreOffice instance if it cannot connect to a running office. This is implemented in the Office Bean local library. The Office Bean depends on three configuration settings to make this work. It has to find the local library, needs the location of the LibreOffice executable, and the bean and office must know the pipe name to use.

Default Configuration
The Office Bean uses default values for all the configuration settings, if none are provided:


 * Since OpenOffice.org 1.1.0 the officebean.jar is located in the /program/classes directory.
 * It looks for the local library (Windows: officebean.dll, Unix: libofficebean.so) relative to the officebean.jar in the /program directory. The local library depends on the following shared libraries:
 * The library sal3 (Windows: sal3.dll, Unix: libsal3.so) is located in the /program folder. It maybe necessary to add the /program folder to the PATH environment variable if the bean cannot find sal3.
 * The library jawt.dll is needed in Windows. If the bean cannot find it, check the Java Runtime Environment binaries (/bin) in your PATH environment variable.
 * It expects the LibreOffice installation in the default install location for the current platform. The soffice executable is in the program folder of a standard installation.
 * The pipe name is created using the value of the  Java property. The name of the pipe is created by appending " " to the name of the currently logged on user, for example, if the user.name is " ", the name of the pipe is " ".

Based on these default values, the Office Bean tries to connect to an office. The office must run in listening mode. That is, it must have been started with the -accept command line option. If there is no running office, then it attempts to start one. The exact parameters used by the bean are:

# WINDOWS soffice.exe -bean -accept=pipe,name=_Office;urp;StarOffice.NamingService

# UNIX soffice -bean "-accept=pipe,name=_Office;urp;StarOffice.NamingService"

In case an office document is displayed outside of the Java frame, then the office has probably been started with wrong or no arguments. Providing the proper command-line arguments is necessary, so that the LibreOffice process can open a correctly named pipe, through which it communicates with the Java application. Only if this pipe can be established, the office will display the document in the Java window.

You can avoid providing the command-line options by editing the file \user\config\registry\instance\org\openoffice\Setup.xml. Within the  element, the developer adds an   element with settings for a named pipe. The following example shows a user-specific Setup.xml that configures a named pipe for a user named :

With this user-specific Setup.xml file, the office opens a named pipe  whenever it starts up. It does not matter if the user double clicks a document, runs the Quickstarter, or starts a new, empty document from a LibreOffice template.

Customized Configuration
Besides these default values, the Office Bean can be configured to use other parameters. There are three possibilities:
 * starting the connection with an explicit UNO URL including path and pipe name parameters
 * creating the connection manually and handing this object to the
 * creating the  with such a manually created connection object.

The first method that a developer uses to configure the Office Bean is through the UNO URL passed in the  call. The syntax of the UNO URL is as follows:

url := 'uno:localoffice'[',' ]';urp;StarOffice.NamingService' params := [',' ] path := 'path=' pipe := 'pipe=' pathv := platform_specific_path_to_the_local_office_distribution pipev := local_office_connection_pipe_name

Here is an example of how to use  in code:

Internal Architecture
These details are not needed for developers utilizing the  class. This information is directed to developers who want to adapt the  mechanisms to other technologies, e.g. to implement access to a remote LibreOffice instance.

Internally, the  consists of three major parts which are all included in the officebean.jar file. The classes  and   implement a fundamental framework that makes it possible to connect to the office and display the document window of a local LibreOffice installation in an AWT or Swing frame.

The Internal Office Bean API
The Office Bean API is exported in two Java interfaces,  and.

An implementation of  is provided in the class. The class  implements. The relationship between the Office Bean interfaces and their implementation classes is shown in the illustration below.



The following sections describe the Office Bean interfaces  and. Refer to the section Using the OOoBean for an explanation of how the implementation classes are used.

OfficeConnection Interface
The  interface contains the methods used to configure, initiate,and manage the connection to LibreOffice. These methods are:

The client uses  to specify to the Office Bean how it connects to the LibreOffice process. See the section Configuring the Office Bean for a description of the syntax of the URL. A  is thrown by the concrete implementation if the client passes a badly formed URL as an argument.

The method  gets an object that implements the com.sun.star.uno.XComponentContext interface from the Office Bean. This object is then used to obtain objects implementing the full LibreOffice API from the backend LibreOffice process.

A call to  requests a new   from the. The client obtains the  from the   to plug into its UI. See the  method below on how to obtain the Component from the. The client provides  that indicates to the implementation what kind of   it is to create.

The method  specifies to the Office Bean the factory object it uses to create Java AWT windows to display popup windows in the Java environment. This factory object implements the  interface. See below for a definition of the  interface.

If the client does not implement its own  interface, the Office Bean uses its own default   creating instances of.

OfficeWindow Interface
The  interface encapsulates the relationship between the AWT window that the client plugs into its UI, and the com.sun.star.awt.XWindowPeer object, which the LibreOffice process uses to draw into the window. It provides two public methods:

The client uses  to obtain the Component window associated with an OfficeWindow. This Component is then added to the clients UI hierarchy.

The method  obtains the UNO com.sun.star.awt.XWindowPeer object associated with an   defines a factory class that the client implements if it needs to control how popup windows generated by the backend LibreOffice process are presented within the Java environment. The factory has only one method:

It returns a.

LocalOfficeConnection and LocalOfficeWindow
The class  implements a connection to a locally running LibreOffice process that is an implementation of the interface. Its method  creates an instance of the class , that is an implementation of the interface.

Where  keeps a single connection to the LibreOffice process, there are multiple, shared   instances for multiple beans. The  implements the embedding of the local LibreOffice document window into a.