steve
/
orion-old


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305
							<!DOCTYPE html>
<html>
    <head>
        <title>Orion - Administration</title>
        <link rel="StyleSheet" href="doc.css" type="text/css" media="screen"/>
        <link rel="StyleSheet" href="docprint.css" type="text/css" media="print"/>
        <script type="text/javascript" src="../js/jquery.js"></script>
        <script type="text/javascript" src="../js/stripe.js"></script>
    </head>
    <body>
        <div id="page">
            <div id="menu">
                <ul>
                    <li><a href="index.html">Index</a></li>
                    <li>Installation and Administration</li>
                    <li><a href="index.html#RunApplet"><b>Orion</b> as a Java Applet</a></li>
                    <li><a href="index.html#RunApplication"><b>Orion</b> as a Java Application</a></li>
                    <li><a href="keys.html">Key Mappings</a></li>
                    <!--
                    <li><a href="bugparade.html">Bug Parade</a></li>
                    -->
                    <li><a href="licenses.html">Licenses</a></li>
                </ul>
            </div>
            <div id="content">
                <h1>Orion - Administration</h1>
                <h2>Index</h2>
                <ul>
                    <li><a href="#Installing">Installation</a></li>
                    <li><a href="#TagsSetup">Setting up a tags file</a></li>
                    <li><a href="#Config">Configuration</a></li>
                </ul>
                <h2 id="Installing">Installing Orion</h2>
                <div class="important">
                    <b>Note:</b> This document is very out-of date and needs rewriting.
                </div>
                <p><span class="Orion">Orion</span> is distributed as a single file called
                <span class="fileref">orion.war</span>.
                This file cannot be used as is, and must have its contents extracted
                before <span class="Orion">Orion</span> can be used.</p>
                <p>To extract the required files, you must first decide upon a
                location for the <span class="Orion">Orion</span> distributed files.
                For example, installation could be into a directory called
                <span class="fileref">/home/orion</span>.</p>
                <p>This document will refer to this location as
                <a class="instdir">_INSTDIR_</a>.</p>
                <div class="important">
                    <b>Note:</b> If you are planning to set up
                    <span class="Orion">Orion</span> to be served by Jakarta Tomcat, you are
                    best to install the product into you Tomcat installation.
                    See <a href="#jakartaconf">here</a> for more information.
                </div>
                <p>The following commands should be issued:</p>
                <pre class="codesnippet">
cd <a class="instdir">_INSTDIR_</a>
jar -xvf orion_package.jar
                </pre>
                <p>This leads to the following files being extracted:</p>
                <pre class="codesnippet">
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
<span class="emphasis">lib/orion.jar</span>
<span class="emphasis">lib/orionapplet.jar</span>
<span class="emphasis">lib/oriontags.jar</span>
<span class="emphasis">lib/orionservlet.jar</span>
<span class="emphasis">WEB-INF/lib/orionservlet.jar</span>
WEB-INF/lib/sample_web.xml
                </pre>
                
                <p>Of these files, it is <span class="fileref">orionXXX.jar</span> files
                    that are crucial to Orion operation.
                    These are the actual executable content of orion that allow all forms
                of orion execution.</p>
                
                <h2 id="TagsSetup">Setting up a tags file</h2>
                <p>A tags file is created using the <code>oriontags</code> program.
                This program is in the <span class="fileref">oriontags.jar</span> file.</p>
                <p>The usage of this is</p>
                <pre class="codesnippet">
Usage: java -jar oriontags.jar -d &lt;srcdir&gt; &lt;outdbname&gt; [-x &lt;dir,dir...&gt;]
                </pre>
                <p>For example, to create a database for my MTP source tree I can use
                the command</p>
                <pre class="codesnippet">
java oriontags -d e:\work\trans\5200\unikixsrc -f trans.tags
                </pre>
                <div class="important">
                    <b>Note:</b> 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
                    <pre class="codesnippet">
                    java -mx64m -jar oriontags.jar -d e:\work\trans\5200\unikixsrc -f trans.tags</pre>
                </div>
                
                <p>When this command is run, it will produce a number of lines
                like:</p>
                <pre class="codesnippet">
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
                </pre>
                <p>and then finally it will produce a set of statistics.</p>
                
                <h2 id="Config">Configuring Orion</h2>
                
                <p>The configuration of <span class="Orion">Orion</span> depends entirely
                    upon the mode of operation that you require.
                    All modes of operation require a tags file to be available
                (<a href="#TagsSetup">see previous section</a>).</p>
                
                <h3 id="ConfigServlet">Servlet Configuration</h3>
                <p>The servlet version of <span class="Orion">Orion</span> can take 2 forms.
                    The traditional form is higher functionality, but is more complex to
                configure.</p>
                <p>For both forms, there is a single Java servlet called
                    <span class="fileref">orionservlet.class</span> that is contained in
                    <span class="fileref">orion.jar</span>.
                    For most Servlet environments, this is specified without the suffix
                as <span class="fileref">orionservlet</span>.</p>
                
                
                <h4>Traditional</h4>
                <p>When configuring the servlet, the following parameters are
                available:</p>
                <table cellspacing="0" summary="Configuration Parameters" class="ot striped">
                    <thead>
                        <tr>
                            <th>Parameter</th>
                            <th>Description</th>
                            <th>Required?</th>
                        </tr>
                    </thead>
                    <tbody>
                    <tr>
                        <td><code>cconfdir</code></td>
                        <td>This is a full path specification of a directory that will be
                            used by the servlet to store information pertenant to each
                        client access.</td>
                        <td>Yes</td>
                    </tr>
                    <tr>
                        <td><code>database</code></td>
                        <td>This is a full path specification of the Orion database
                        file.</td>
                        <td>Yes</td>
                    </tr>
                    <tr>
                        <td><code>instdir</code></td>
                        <td>This is the full path specification of the location of the
                            Orion files.
                            That is, the value of <a class="instdir">_INSTDIR_</a> as used
                            in the '<a href="#Installing">Installing Orion</a>'
                        section.</td>
                        <td>Yes</td>
                    </tr>
                    <tr>
                        <td><code>title</code></td>
                        <td>The title to be placed on the Orion HTML page.</td>
                        <td>No</td>
                    </tr>
                    </tbody>
                </table>
                
                <h4>Example of setup for Apache JServ</h4>
                <p>The following is a snippet of an
                    <a href="http://java.apache.org">Apache JServ</a> configuration to
                serve <span class="Orion">Orion</span>.</p>
                <pre class="codesnippet">
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
                </pre>
                
                <h4 id="jakartaconf">Example of setup for Apache Jakarta Tomcat</h4>
                <p><a href="http://jakarta.apache.org">Apache Tomcat</a> works with a
                fundamental concept of a Web Application (webapp).
                These web applications normally live under the <code>webapps</code>
                directory of a tomcat installation.</p>
                <p>It is recommended that you set up a separate web application for
                orion.
                This will ease maintenance for you, and provide isolation of function.</p>
                <p>The following discussion will use the symbol <code>$TOMCAT</code>
                to mean the directory into which you have installed tomcat.
                To create a web application for orion, you should do the following.</p>
                <ol>
                    <li>Create the directory <code>$TOMCAT/webapps/orion</code>.
                    This will be your <span class="Orion">Orion</span> web application.</li>
                    <li>Create the directory <code>$TOMCAT/webapps/orion/WEB-INF</code>.</li>
                    <li>Create a directory to store client configuration information.
                    This can be anywhere, but it is recommended that you use a
                    directory under the <code>$TOMCAT/webapps/orion/WEB-INF</code>
                    directory.</li>
                    <li>Extract the <span class="fileref">orion_package.jar</span> into this
                    <code>WEB-INF</code> directory.</li>
                    <li>Create the file
                        <code>$TOMCAT/webapps/orion/WEB-INF/web.xml</code>.
                        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.</li>
                </ol>
                <pre class="codesnippet">
&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;

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

&lt;web-app&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;
      testorion
    &lt;/servlet-name&gt;
    &lt;servlet-class&gt;
      orionservlet
    &lt;/servlet-class&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;database&lt;/param-name&gt;
      &lt;param-value&gt;<a class="emphasis">e:/work/code/fish.tags</a>&lt;/param-value&gt;
    &lt;/init-param&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;cconfdir&lt;/param-name&gt;
      &lt;param-value&gt;e:/work/acs/conf&lt;/param-value&gt;
    &lt;/init-param&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;instdir&lt;/param-name&gt;
      &lt;param-value&gt;<a class="emphasis">d:/lpp/jakarta-tomcat/webapps/orion/WEB-INF/lib</a>&lt;/param-value&gt;
    &lt;/init-param&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;title&lt;/param-name&gt;
      &lt;param-value&gt;Testing Orion&lt;/param-value&gt;
    &lt;/init-param&gt;
  &lt;/servlet&gt;
  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;
      testorion
    &lt;/servlet-name&gt;
    &lt;url-pattern&gt;
      /test/*
    &lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;
&lt;/web-app&gt;
                </pre>
                
                <h3 id="ConfigApplication">Application Configuration</h3>
                <p>The <span class="Orion">Orion</span> Application configuration is
                    (at least initially) not pretty.
                    Once the initial file is set up, however configuration is fine.
                    <span class="note">This configuration will improve in subsequent
                versions.</span> </p>
                <p><span class="Orion">Orion</span> 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.</p>
                <p>The easiest way to determine the location of the file is to try
                    running <span class="Orion">Orion</span> without the file existing.
                    You should then get an exception produced with a message something
                like </p>
                <pre class="codesnippet">
java.lang.IllegalArgumentException: <a class="emphasis">D:\stevem.orion.properties</a>
	at uk.co.ruelgnoj.tools.orion.OrionConfig.&lt;init&gt;(OrionConfig.java:49)
	at uk.co.ruelgnoj.tools.orion.Orion.&lt;init&gt;(Orion.java:56)
	at uk.co.ruelgnoj.tools.orion.Orion.main(Orion.java:174)
                </pre>
                <p>The emphasised location is the name of the properties file which you must now produce.</p>
                <p>You should create the above named file, and put the single line in it</p>
                <pre class="codesnippet">
orion.database=YOUR_TAGS_FILE
                </pre>
                <p>For example, my setting is</p>
                <pre class="codesnippet">
orion.database=e:\\tags\\fish.tags
                </pre>
                <p>Note the tags file name needs to be a fully qualified path
                    name, and on Windows platforms, each <code>\</code> needs to be
                doubled (as can be seen above).</p>
                <p>Configuration of the display colors, size, Font, etc can be done
                by using the Menu Items of <span class="Orion">Orion</span> itself.</p>
            </div>
            <div id="copyright">
                <p><a href="http://www.ruelgnoj.co.uk/">Copyright &#169; 1997,2017 by Steve Millington. All Rights Reserved.</a></p>
            </div>
        </div>
    </body>
</html>