Icon
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

To install Obba for OpenOffice / LibreOffice / NeoOffice open the file Obba.oxt with OpenOffice / LibreOffice / NeoOffice. Note: If Obba 2.x is installed in the extension manager, it has to be removed prior installation of Obba 3.x.

Notes

Configuration

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

Location of the Configuration Files

Excel Client

If you are running Excel, then ObbaClient.properties is searched in the following locations:
  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

If you are running OpenOffice/LibreOffice/NeoOffice Client, then ObbaClient.properties is searched in the following locations:
  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".
  3. otherwise, it uses a default configuration.

Obba Server

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

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

The following lists the properties and their default values in ObbaClient.properties.
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

The following lists the properties and their default values in Obba.properties.
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
This has to be done before launching any sheet (otherwise the client will not find the server and start a local server).

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: