source: trunk/doc/src/docbook/appendix/jobagent.properties.xml @ 3363

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: jobagent.properties.xml 3363 2007-05-22 20:48:49Z nicklas $
  
  Copyright (C) Authors contributing to this file.
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<appendix id="appendix.jobagent.properties">
  <title>jobagent.properties reference</title>
  
  <para>
    The <filename>jobagent.properties</filename> file is the main configuration file
    for job agents. It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
    directory.
  </para>

  <simplesect id="appendix.jobagent.properties.base">
    <title>BASE settings</title>
    
    <para>
      This section describes the configuration parameters that 
      are used by the job agent to get access to the BASE server.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>agent.user</property></term>
      <listitem>
        <para>
          Required. The BASE user account the job agent should use to login 
          to the BASE server. The user account must have sufficient privileges 
          to access jobs and job agents. The <emphasis>Job agent</emphasis>
          role is a predefined role with all permissions a job agent needs.
          There is also a predefined user account with the login 
          <emphasis>jobagent</emphasis>. This account is disabled by default and
          has to be enabled and given a password before it can be used.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>agent.password</property></term>
      <listitem>
        <para>
          Required. The password for the user account.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>agent.id</property></term>
      <listitem>
        <para>
          Required. A unique ID that identifies this job agent among other 
          job agent. If multiple job agents are installed each job agent 
          should have it's own unique ID.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>agent.name</property></term>
      <listitem>
        <para>
          Optional. The name of the job agent. If not specified the ID is used. 
          The name is only used when registering the job agent with the BASE 
          server.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>agent.description</property></term>
      <listitem>
        <para>
          Optional. A description of the job agent. This is only used when 
          registering the job agent.
        </para>
      </listitem>
    </varlistentry>
    </variablelist>
    
  </simplesect>

  <simplesect id="appendix.jobagent.properties.jobagent">
    <title>Job agent server settings</title>
    
    <para>
      This section describes the configuration parameters that 
      affect the job agent server itself.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>agent.port</property></term>
      <listitem>
        <para>
          Optional. The port the job agent listens to for control requests. 
          Control requests are used for starting, stopping, pausing and getting 
          status information from the job agent. It is also used by the 
          <command>jobagent.sh</command> script to control 
          the local job agent. The default value is 47822.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>agent.remotecontrol</property></term>
      <listitem>
        <para>
          Optional. A comma-separated list of ip addresses or names of 
          computers that are allowed to send control requests to the job 
          agent. If no value is specified, only the local host is allowed 
          to connect. It is recommended that the web server is added to 
          the list if the job agent is not running on the same server as
          the web server.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>agent.allowremote.stop</property></term>
      <listitem>
        <para>
          Optional. If the <command>stop</command> command should be 
          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting. 
          If <constant>false</constant>, which is the default value,
          only the local host is allowed to stop the job agent.
        </para>
        
        <note>
          <para>
          Once the job agent has been stopped it can't be started
          by remote control. You must use the <command>jobagent.sh</command>
          script for this.
          </para>
        </note>
        
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>agent.allowremote.start</property></term>
      <listitem>
        <para>
          Optional. If the <command>start</command> command should be 
          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting. 
          If <constant>false</constant>, only the local host is allowed to 
          start the job agent. The default value is <constant>true</constant>.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>agent.allowremote.pause</property></term>
      <listitem>
        <para>
          Optional. If the <command>pause</command> command should be 
          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting. 
          If <constant>false</constant>, only the local host is allowed to 
          pause the job agent. The default value is <constant>true</constant>.
        </para>
      </listitem>
    </varlistentry>
    </variablelist>

  </simplesect>

  <simplesect id="appendix.jobagent.properties.execution">
    <title>Job execution settings</title>
    
    <para>
      This section describes the configuration parameters that 
      affect the execution of jobs.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>agent.executor.class</property></term>
      <listitem>
        <para>
          The name of the Java class that handles the actual execution of jobs. 
          The default implementation for a job agent ships three 
          implementations:
          
          <itemizedlist>
          <listitem>
            <para>
            <classname>net.sf.basedb.clients.jobagent.executors.ProcessJobExecutor</classname>: 
            Executes the job in an 
            external process. This is the recommended executor and is the default
            choice if no value has been specified. With this executor a 
            misbehaving plugin doesn't affect the job agent or other jobs.
            The drawback is that since a new virtual machine has to be started,
            more memory is required and the startup time can be long.
            </para>
          </listitem>
          
          <listitem>
            <para>
            <classname>net.sf.basedb.clients.jobagent.executors.ThreadJobExecutor</classname>:      
            Executes the job in a separate thread. This is only recommended 
            for plugins that are  trusted and safe. A misbehaving plugin can affect the job agent 
            and other jobs, but the statup time is short and less memory 
            is used.
            </para>
          </listitem>
          
          <listitem>
            <para>
            <classname>net.sf.basedb.clients.jobagent.executors.DummyJobExecutor</classname>:     
            Doesn't execute the job. It only marks the job as beeing executed, 
            and after waiting some time, as finished successfully. 
            Use it for debugging the job agent. 
            </para>
          </listitem>
          </itemizedlist>

          It is possible to create your own implemetnation of a job executor. 
          Create a class that implements the 
          <interfacename>net.sf.basedb.clients.jobagent.JobExecutor</interfacename>
          interface.          
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>agent.executor.process.java</property></term>
      <listitem>
        <para>
          Optional. The path to the Java executable used by the 
          <classname>ProcessJobExecutor</classname>. If not specified the 
          <envar>JAVA_HOME</envar> environment variable will be checked. 
          As a last resort <command>java</command> is used without path 
          information to let the operating system find the default 
          installation.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>agent.executor.process.options</property></term>
      <listitem>
        <para>
          Optional. Additional command line options to the Java executable. 
          Do not add memory options (<option>-Mx</option> or 
          <option>-Ms</option>), it will be added automatically by the 
          executor. This setting is used by the 
          <classname>ProcessJobExecutor</classname> only.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>agent.executor.dummy.wait</property></term>
      <listitem>
        <para>
          Optional. Number of seconds the <classname>DummyJobExecutor</classname> should 
          wait before returning from the "job execution". The executor first sets 
          the progress to 50% then waits the specified number of seconds before 
          setting the job to completed. If no value is specified it returns immediately.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>agent.checkinterval</property></term>
      <listitem>
        <para>
          Optional. Number of seconds between checks to the database 
          for jobs that are waiting for execution. The default value
          is 30 seconds.
        </para>
      </listitem>
    </varlistentry>
    
    </variablelist>
  </simplesect>
  
  <simplesect id="appendix.jobagent.properties.slots">
    <title>Slots and priorities</title>
    
    <para>
      The job agent doesn't execute any number of jobs at the same time.
      This would sooner or later break the server. Instead, it uses a
      simple system with four different slots. Each slot is reserved for
      jobs that are estimated to be finished in a certain amount of time.
      The exception is that a quick job may use a slot with longer expected time
      since that will not block the slot very long. 
    </para>
    
    <para>
      With each slot is also associated a thread priority. The priority
      is a value between 1 and 10 as defined by the 
      <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html"
        ><classname>java.lang.Thread</classname></ulink> class.
    </para>
    
    <informaltable frame="all" align="center">
    <tgroup cols="3">
      <colspec colname="property" />
      <colspec colname="default" align="center"/>
      <colspec colname="time" />
      <thead>
        <row>
          <entry>Property</entry>
          <entry>Default value</entry>
          <entry>Estimated execution time</entry>
        </row>
      </thead>
      
      <tbody>
        <row>
          <entry>agent.shortest.slots</entry>
          <entry>1</entry>
          <entry morerows="1">&lt; 1 minute</entry>
        </row>
        <row>
          <entry>agent.shortest.priority</entry>
          <entry>4</entry>
        </row>
        <row>
          <entry>agent.short.slots</entry>
          <entry>1</entry>
          <entry morerows="1">&lt; 10 minutes</entry>
        </row>
        <row>
          <entry>agent.short.priority</entry>
          <entry>4</entry>
        </row>
        <row>
          <entry>agent.medium.slots</entry>
          <entry>2</entry>
          <entry morerows="1">&lt; 1 hour</entry>
        </row>
        <row>
          <entry>agent.medium.priority</entry>
          <entry>3</entry>
        </row>
        <row>
          <entry>agent.long.slots</entry>
          <entry>2</entry>
          <entry morerows="1">&gt; 1 hour</entry>
        </row>
        <row>
          <entry>agent.long.priority</entry>
          <entry>3</entry>
        </row>
      </tbody>
    </tgroup>
    </informaltable>
    

  </simplesect>


</appendix>