Obba Documentation: Installation and Configuration

Contents

1. Introduction
2. Installation
3. Configuration
4. Running a Server Manually on the Local Machine
5. Running a Server on Remote Machine

Introduction

Obba provides spreadsheet functions to communicate with a Java virtual machine. In the following we call this Java virtual machine "server" (because it is the process providing the calculations, like a "calculation server"). Likewise we call the spreadsheet "client".

Obba can be used in three different ways:

1. If you open a spreadsheet using Obba functions and the client cannot find a running server, then Obba will launch a server, i.e., a Java virtual machine.
2. If you start the Obba server in a separate shell/command prompt, Obba will use that server. This allows you to start the Java virtual machine with you own JVM parameters and/or classpath. Note: This feature is very handy for debugging your code. For example, you may start the Obba server directly from you IDE (Eclipse, Netbeans, IntelliJ). The spreadsheet will then connect to that JVM.
3. You may start the Obba server on a different machine. In that case you have to edit a configuration file on the machine running the client (the spreadsheet) and tell the client about the ip address of the server's machine.

Installation

Obba is easy to install. After the following two steps (one for "Obba for Excel" and one for "Obba for OpenOffice"), Obba can run on your local machine. To use advanced features, like running the spreadsheet and the Java virtual machine (Obba server) on different computers (see below) you need to configure a configuration file.

Obba for Excel

To install Obba for Excel execute the installer in the folder "Obba for Excel for Windows".

Obba for OpenOffice / LibreOffice

To install Obba for OpenOffice / LibreOffice / NeoOffice open the file Obba.oxt with OpenOffice / LibreOffice / NeoOffice.

Notes

• The installation of Obba requires Java to be enabled in OpenOffice/LibreOffice.
• Installing Obba 6.x or better on system with an installation of Obba 5.x or older requires the manual uninstall of any older version of Obba prior (re-)installation of the new version.
• You may experience issues installing Obba on OS X / macOS, but these may be resolved. See next section.

Notes for Obba for OpenOffice/LibreOffice on a Mac (OS X, macOS)

Important: Installing a Java addin, like Obba.oxt, on OS X / macOS may lead to issues: OpenOffice/LibreOffice may hang, you might be prompted to install Java 6 (which is not required) or you might see a cryptic error. Below you find the installation steps resolving these issues:

• If you see an error dialog: open LibreOffice/OpenOffice and enable Java in Preferences / LibreOffice/OpenOffice / Advanced.
• If the installation hangs: Due to a bug in LibreOffice 4.2, 5.1, 5.2 the installation will hang if Obba.oxt is opened via "Double Click". Instead, start LibreOffice, Open Extension Manager and select "Add" to add Obba.oxt manually. If the installation still hangs, uninstall any old version of Obba.oxt.
• If you are prompted to install Java 6: Java 6 is not required to run Obba, in fact, Obba 5.x or better requires Java 8. However, the Extension manager looks for a specific JRE which triggers this dialog (this is a bug, see documentfoundation.org/show_bug.cgi?id=74877).
  There are two possibilities to resolve this issue: Either you install Java 6 (you may deinstall it after Obba.oxt has been installed) or you modify your Java implementation, follow the steps on https://unfinishedbitness.info/2015/03/03/os-x-legacy-java-se-6-error-resolution/ :
  1. Open Terminal
  2. Change directory to the Contents folder of your Java installation, e.g., cd /Library/Java/JavaVirtualMachines/jdk1.8.0_144.jdk/Contents.
  3. Edit the file Info.plist (via sudo), e.g. using vi by sudo vi Info.plist
  4. Change the key JVMCapabilities from

     	<key>JVMCapabilities</key>
     	<array>
     		<string>CommandLine</string>
     	</array>
     	

     to

     	<key>JVMCapabilities</key>
     	<array>
     		<string>JNI</string>
     		<string>BundledApp</string>
     		<string>WebStart</string>
     		<string>Applets</string>
     		<string>CommandLine</string>
     	</array>
     	

     (using vi, move to the position after the <array>, press i (for insert) and copy-and-paste the missing lines).

Configuration

Obba will look for two configuration files: ObbaClient.properties and Obba.properties:

• The file ObbaClient.properties is needed to configure the client (the spreadsheet add-in) if the server runs on a different machine (see below). It is searched on the machine where the spreadsheet runs.
• The file Obba.properties contains all other configuration. It is searched on the machine where the server runs (which may be the machine running the client spreadsheet).

Location of the Configuration Files

Excel Client

1. If the environment variable OBBA_HOME is defined, the client tries to load ObbaClient.properties from there.
2. If the environment variable OBBA_HOME is not defined, the client tries to load ObbaClient.properties from installation directory of the Obba.dll, which is usually %LOCALAPPDATA%/Obba.
3. otherwise, it uses a default configuration.

On Windows XP the environment variable %LOCALAPPDATA% may not be defined. In that case the corresponding directory is C:\Documents and Settings\≤username≥\Local Settings\Application Data. On newer Windows versions the variable %LOCALAPPDATA% is usually defined as C:\Users\≤username≥\AppData\Local.

Note: Versions prior to Obba 3.2 used %APPDATA% instead of %LOCALAPPDATA%.

OpenOffice/LibreOffice/NeoOffice Client

1. If the environment variable OBBA_HOME is defined, the client tries to load ObbaClient.properties from there.
2. If the environment variable OBBA_HOME is not defined, the client tries to load ObbaClient.properties from the OpenOffice directory "UserConfig".
   • On Mac OS X this is ~/Library/Application Support/OpenOffice.org/3/user/config/
   • On Linux this is ~/.config/OpenOffice.org/3/user/config/
3. otherwise, it uses a default configuration.

Obba Server

The server looks for a configuration file Obba.properties (which also stores the registration data).

• If the client started a "local server", the server will check the same directory as the client did for ObbaClient.properties (see above).
• If the server was started manually (see below), the server will try to locate Obba.properties according to the following steps:
  1. If the environment variable OBBA_HOME is defined, the server tries to load Obba.properties from there.
  2. If the environment variable OBBA_HOME is not defined, the server tries to load Obba.properties from the directory where its Obba.jar was loaded from.
  3. otherwise, it uses a default configuration.

Configurable Properties

Properties are stored in standard java .properties-files using a key=value syntax. Below the keys and the corresponding default values are listed.

Configurable Properties for the Client

Obba.Server.Ip=127.0.0.1

IP of the machine running the Obba server. Change this property if you like to run Obba server on a remote machine. The default port for the connection is TCP/IP port 10000. The port may be configured with via property Obba.Server.Port.

Obba.Server.Port=10000

Port on which Obba server is listing. Change this property if you like to connect to an Obba server process listening on a different port.

Obba.Client.AutoStartLocalServer=true

Let the client start a server, if it does not find an already running server. Warning: If you set this property to false, sheets will not work until a server has been started.

Obba.Client.LocalServer.Params=-Xmx1024m

Command line parameters used when the client starts a local server. By default -Xmx1024m is used, i.e., the JVM has a maximum heap space of 1 GB.

Obba.Client.LocalServer.ShowConsole=true

When running the local server, show a console window. The console window will show you Obba's log messages. Note: This feature currently only works with Obba for Excel. For Obba for OpenOffice/LibreOffice use a standard Java logger to view the log messages.

Configurable Properties for the Server

userid=Trial User

Registration data; the user id.

serial=

Registration data; the serial number.

Obba.Server.Port=10000

Port on which Obba server is listing. Change this property if you like to run an Obba server process listening on a different port. It is possible to run multiple Obba server processes on a single machine. Clone the Obba Server directory, each with its own Obba.properties, set a different port in each property file and launch the server processes from their respective directory.

Obba.Server.Shutdown.WhenClientDisconnects=true

Shut down the server when the client disconnects. This is only done for a server which was not launched manually.

Note: There is an open issue related to this feature for Obba for Excel. If you close Excel and Excel shows you the dialog warning of unsaved changes, pressing Cancel will leave the sheet open, but kill the local server. This may leave the sheet in an inconsistent state, since the sheet considers cells calculated while all Obba functions would need a re-calculation. There is currently no fix for this issue.

Running a Server Manually on the Local Machine

Usually, Obba starts a JVM upon the first call to an Obba spreadsheet function. Alternatively, you may start the server manually by "running" Obba.jar from the folder "Obba Server":

1. Open a command prompt / shell.
2. Change the working directory to the folder "Obba Server".
3. Execute the command java -jar Obba.jar

Running a Server on Remote Machine

The Obba server JVM can be run on a remote machine. In order to have this work, you have to start the server on the remote machine and configure the servers ip address on the client machine. This has to be done before launching any sheet on the client machine(s) (otherwise the client will not find the server and start a local server).

1. Start the server on the remote machine: On the server's machine:
   1. Open a command prompt / shell.
   2. Change the working directory to the folder "Obba Server".
   3. Execute the command java -jar Obba.jar
   Note: If the (Linux) server does not have a display (DISPLAY not set), start in headless more using java -Djava.awt.headless=true -jar Obba.jar.
2. Configure the client to connect to the remote server: On the client's machine:
   • To configure Obba for Excel:
     1. In the configuration file %LOCALAPPDATA%/Obba/ObbaClient.properties set the key Obba.Server.Ip to the ip adress of the server.
   • To configure Obba for OpenOffice:
     1. Set the environment variable OBBA_HOME to the directory "Obba Client" containing the file ObbaClient.properties.
        Note: On OS X that environment variable is set by the terminal command launchctl setenv OBBA_HOME /path/to/directory where /path/to/directory is the path to the "Obba Client" directory.
     2. In the configuration file $OBBA_HOME/ObbaClient.properties set the key Obba.Server.Ip to the ip adress of the server.

Running a Server with an alternative Classpath

A spreadsheet may add paths to the Obba class loader via the functions obAddAllJars, obAddJar, obAddAllJars. These add a path to the Obba class loader.

You may also modify the classpath of the Obba server on the command line. Instead of java -jar Obba.jar use java -classpath [...] info.obba.server.Server making sure that Ice.jar and Obba.jar are part of the classpath [...]. This classpath is added to the parent of the Obba classloader (i.e., classes found though the command line class paths do not know classes found through the classpath added via obAddAllJars, obAddJar, obAddAllJars).