openinfoman tutorial for 'hello, world'

openinfoman-tutorial.md

"Hello, world" for openinfoman

openinfoman uses basex. basex is Java-based XML database, XQuery engine, and RestXQ web application framework. Installing openinfoman also installs basex.

Using a fresh Ubuntu 14.x install the openhie repository and then openinfoman. Accept the default options for openinfoman (heap size: default, url: leave blank, database: provider_directory).

sudo add-apt-repository ppa:openhie/release
sudo apt-get update
sudo apt-get install openinfoman

After installation, openinfoman will be running and the web application admin interface is at http://localhost:8984/CSD

Three different processes are running: The basex database server on port 1984, which services calls to the XML database and XQueries; the basex web application using Jetty on port 8984; and port 8985 for graceful web server shutdowns.

Stopping and starting openinfoman

When openinfoman is installed it puts both the basex and openinfoman repository under /var/lib/openinfoman. In bin/ the basex script launches the command line REPL, also referred to as 'basex standalone'. basexhttp launches all components needed for openinfoman (web server, database, web server shutdown). All of these are shell scripts that define the Java classpath and fires up Java.

To shutdown and launch openinfoman, use the upstart service (/etc/init/openinfoman) which uses a simple wrapper script. Starting the service increases the heap size then calls the basex web application (basexhttp). Stopping the openinfoman service sends a call for the graceful shutdown of the web server then stops the other processes.

Root user privileges are needed to stop/start openinfoman.

sudo service openinfoman stop
sudo service openinfoman start

We will use basex standalone basex to install modules, but /var/lib/openinfoman/bin is not added to $PATH. If you directly invoke the shell script used to start the REPL (basex) or the web application (basexhttp) it will error out with The program 'basex' is currently not installed. You can install it by typing: sudo apt-get install basex Ignore the error and call the executable with the correct path.

Hello, world

The oi user and group owns openinfoman but it disabled. We need to be the oi user to create and load functions in basex standalone. Assign a password with sudo passwd oi to enable it then switch user with su - oi

Have a look at all of the modules installed by openinfoman.

cd /var/lib/openinfoman/
ls -a
.  ..  .basex  .basexhome  BaseX.jar  bin  data  etc  lib  LICENSE  README.md  repo  repo-src  resources  webapp
$ ./bin/basex
BaseX 8.5.3 [Standalone]
Try 'help' to get more information.
> repo list
> exit
cd /var/lib/openinfoman/repo/com/github/openhie/openinfoman
ls
...

From the BaseX docs, 'If an XQuery file is specified as input for the install command, it will be parsed as XQuery library module. If parsing was successful, the module URI will be rewritten to a file path and attached with the .xqm file suffix, and the original file will be renamed and copied to that path into the repository.'

What this means for 'hello, world' is that the file we create will be parsed by the basex standalone command and will write a series of folders and copy the file into that folder path. /var/lib/openinfoman/repo/com/github/openhie/openinfoman is an example of this, where the original xqm files were placed into the path created.

As the oi user, create a directory for our 'hello, world' module, e.g. tests, in /var/lib/openinfoman and create a file for the 'Hello, world' XQuery module.

A 'hello, world' example is included in the GitHub basex repo. We will get that file and then use basex standalone to install it as a module which will copy it into the correct path. We can then list the basex repos to see that it was successfully installed.

mkdir tests
cd tests
wget https://raw.github.com/BaseXdb/basex/master/basex-api/src/main/webapp/restxq.xqm
../bin/basex
BaseX 8.5.3 [Standalone]
> repo install /var/lib/openinfoman/tests/restxq.xqm
> repo list
...
org.basex.modules.web-page ... - Internal  org/basex/modules/web-page.xqm
...
> exit

Stop and start the openinfoman service as a user with sudo privileges. The visit http://localhost:8984/hello/world

It FAILS

$ tail /var/lib/openinfoman/data/.logs/*
...
15:49:03.592	127.0.0.1:42374	admin	REQUEST	[GET] http://localhost:8984/hello/world
15:49:03.635	127.0.0.1:42374	admin	404	No function found that matches the request.	43.09 ms