Orion - Administration

Index

Installing Orion

Note: This document is very out-of date and needs rewriting.

Orion is distributed as a single file called orion.war. This file cannot be used as is, and must have its contents extracted before Orion can be used.

To extract the required files, you must first decide upon a location for the Orion distributed files. For example, installation could be into a directory called /home/orion.

This document will refer to this location as _INSTDIR_.

Note: If you are planning to set up Orion to be served by Jakarta Tomcat, you are best to install the product into you Tomcat installation. See here for more information.

The following commands should be issued:

cd _INSTDIR_
jar -xvf orion_package.jar

This leads to the following files being extracted:

index.html
doc/index.html
doc/admin.html
doc/index.html
doc/keys.html
doc/style.html
doc/bugparade.html
doc/doc.css
doc/docprint.css
doc/images
doc/images/orion3.jpg
lib/orion.jar
lib/orionapplet.jar
lib/oriontags.jar
lib/orionservlet.jar
WEB-INF/lib/orionservlet.jar
WEB-INF/lib/sample_web.xml

Of these files, it is orionXXX.jar files that are crucial to Orion operation. These are the actual executable content of orion that allow all forms of orion execution.

Setting up a tags file

A tags file is created using the oriontags program. This program is in the oriontags.jar file.

The usage of this is

Usage: java -jar oriontags.jar -d <srcdir> <outdbname> [-x <dir,dir...>]

For example, to create a database for my MTP source tree I can use the command

java oriontags -d e:\work\trans\5200\unikixsrc -f trans.tags
Note: If there are a large number of files then Java can die with an out of memory error. This is the case when producing a tags file for the MTP source base. The solution is to add an extra flag on the command like this 
                    java -mx64m -jar oriontags.jar -d e:\work\trans\5200\unikixsrc -f trans.tags

When this command is run, it will produce a number of lines like:

Parsing [1] e:\work\trans\5200\unikixsrc\admin\accounting\kixjas.c
Parsing [2] e:\work\trans\5200\unikixsrc\admin\console\kixlog.c
Parsing [3] e:\work\trans\5200\unikixsrc\admin\console\kxtrace_defines.h
Parsing [4] e:\work\trans\5200\unikixsrc\admin\console\unikixprt.c
Parsing [5] e:\work\trans\5200\unikixsrc\admin\include\kxcmn.h
Parsing [6] e:\work\trans\5200\unikixsrc\admin\include\kxdummy.h
Parsing [7] e:\work\trans\5200\unikixsrc\admin\include\kxerrmsg.h
Parsing [8] e:\work\trans\5200\unikixsrc\admin\kixdump\kixabort.c
Parsing [9] e:\work\trans\5200\unikixsrc\admin\kixdump\kixdump.c

and then finally it will produce a set of statistics.

Configuring Orion

The configuration of Orion depends entirely upon the mode of operation that you require. All modes of operation require a tags file to be available (see previous section).

Servlet Configuration

The servlet version of Orion can take 2 forms. The traditional form is higher functionality, but is more complex to configure.

For both forms, there is a single Java servlet called orionservlet.class that is contained in orion.jar. For most Servlet environments, this is specified without the suffix as orionservlet.

Traditional

When configuring the servlet, the following parameters are available:

Parameter Description Required?
cconfdir This is a full path specification of a directory that will be used by the servlet to store information pertenant to each client access. Yes
database This is a full path specification of the Orion database file. Yes
instdir This is the full path specification of the location of the Orion files. That is, the value of _INSTDIR_ as used in the 'Installing Orion' section. Yes
title The title to be placed on the Orion HTML page. No

Example of setup for Apache JServ

The following is a snippet of an Apache JServ configuration to serve Orion.

servlet.jorion.initArgs=cconfdir=/home/orion/clientconfig
servlet.jorion.initArgs=database=/home/orion/j7.tags
servlet.jorion.initArgs=instdir=/home/orion/orion
servlet.jorion.initArgs=title=Orion of JDK 1.7 Source

Example of setup for Apache Jakarta Tomcat

Apache Tomcat works with a fundamental concept of a Web Application (webapp). These web applications normally live under the webapps directory of a tomcat installation.

It is recommended that you set up a separate web application for orion. This will ease maintenance for you, and provide isolation of function.

The following discussion will use the symbol $TOMCAT to mean the directory into which you have installed tomcat. To create a web application for orion, you should do the following.

  1. Create the directory $TOMCAT/webapps/orion. This will be your Orion web application.
  2. Create the directory $TOMCAT/webapps/orion/WEB-INF.
  3. Create a directory to store client configuration information. This can be anywhere, but it is recommended that you use a directory under the $TOMCAT/webapps/orion/WEB-INF directory.
  4. Extract the orion_package.jar into this WEB-INF directory.
  5. Create the file $TOMCAT/webapps/orion/WEB-INF/web.xml. The contents of the file should be along the lines of the example below. You should ensure that the values you place in the fields are correct for your installation. It should be further noted that multiple orion instances can be specified in this piece of XML, and so this web application can be used for all of your orion requirements.
<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">

<web-app>
  <servlet>
    <servlet-name>
      testorion
    </servlet-name>
    <servlet-class>
      orionservlet
    </servlet-class>
    <init-param>
      <param-name>database</param-name>
      <param-value>e:/work/code/fish.tags</param-value>
    </init-param>
    <init-param>
      <param-name>cconfdir</param-name>
      <param-value>e:/work/acs/conf</param-value>
    </init-param>
    <init-param>
      <param-name>instdir</param-name>
      <param-value>d:/lpp/jakarta-tomcat/webapps/orion/WEB-INF/lib</param-value>
    </init-param>
    <init-param>
      <param-name>title</param-name>
      <param-value>Testing Orion</param-value>
    </init-param>
  </servlet>
  <servlet-mapping>
    <servlet-name>
      testorion
    </servlet-name>
    <url-pattern>
      /test/*
    </url-pattern>
  </servlet-mapping>
</web-app>

Application Configuration

The Orion Application configuration is (at least initially) not pretty. Once the initial file is set up, however configuration is fine. This configuration will improve in subsequent versions.

Orion uses a configuration file that is located in your HOME directory. This directory can be difficult to determine, and indeed it changes depending on the version of Java you are using, on which platform.

The easiest way to determine the location of the file is to try running Orion without the file existing. You should then get an exception produced with a message something like 

java.lang.IllegalArgumentException: D:\stevem.orion.properties
	at uk.co.ruelgnoj.tools.orion.OrionConfig.<init>(OrionConfig.java:49)
	at uk.co.ruelgnoj.tools.orion.Orion.<init>(Orion.java:56)
	at uk.co.ruelgnoj.tools.orion.Orion.main(Orion.java:174)

The emphasised location is the name of the properties file which you must now produce.

You should create the above named file, and put the single line in it

orion.database=YOUR_TAGS_FILE

For example, my setting is

orion.database=e:\\tags\\fish.tags

Note the tags file name needs to be a fully qualified path name, and on Windows platforms, each \ needs to be doubled (as can be seen above).

Configuration of the display colors, size, Font, etc can be done by using the Menu Items of Orion itself.