XmlBlaster Logo

REQUIREMENT

engine.runlevel

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic XmlBlaster supports different run levels
Des
cription

An xmlBlaster server instance has different states, we call it run levels as a gesture of honor to the UNIX run levels.
The run level 0 is a stopped xmlBlaster, the run level 9 is a fully operational run level.

Here is a description of the different run levels:
Level No active Services Description
HALTED 0 - XmlBlaster is not existing
HALTED_POST 1 - The persistent topics are loaded
STANDBY_PRE 2 The persistence plugin is activated All persistent sessions and subscriptions are loaded
STANDBY 3 Only administrative access from outside is possible XmlBlaster has sync'd all databases and just waits, it is ready to be killed or reactivated. You can access xmlBlaster with JMX or telnet.
STANDBY_POST 4 All configured protocol plugins (for example IOR and SOCKET) are alive but only administrative access from outside is possible The Availability checker prohibits operational client access.
CLEANUP_PRE 5 The cluster manager is ready.
Delivered services and your native service plugins are activated. 		The cluster manager needs the protocol plugins from run level 4 to configure itself.
If you register your own native plugins this runlevel is a good place to do
CLEANUP 6 All configured plugins are alive and operational but only administrative access from outside is possible XmlBlaster still flushes queues to other cluster nodes or to connected clients
CLEANUP_POST 7 The Availability checker allows ordinary access from outside Normal clients may access XmlBlaster (connect, publish,etc.)
RUNNING_PRE 8 Your ordinary native client plugins are activated If you register some ordinary native clients this runlevel is a good place to do
RUNNING 9 All configured plugins are alive XmlBlaster is fully operational

Administration features:

  • Administer run level changes:
    The internal command manager supports the attribute getRunlevel() and setRunlevel() allowing to monitor or change the run level via SNMP, telnet or other supported administration protocols (see requirement admin below).
  • Configure the plugins:
    An xml file describes the plugin configuration. It defines among other things startup and shutdown sequence, classname and plugin specific attributes. This file describes both plugins loaded by the runlevel manager (further called static plugins) and plugins which are loaded on client demand (further called dynamic plugins). The default name for this file is xmlBlasterPlugins.xml.

The xmlBlasterPlugins.xml file is searched in the following locations and the given order:
location or parameter example
user.dir .
Command line parameter '-pluginsFile' -pluginsFile /tmp/xmlBlasterPlugins.xml
$PROJECT_HOME java -DPROJECT_HOME=/opt/xmlBlaster ...
$HOME user.home
classpath /opt/xmlBlaster/lib/xmlBlaster.jar:....
java.ext.dirs /opt/jdk1.2.2/jre/lib/ext
java.home /opt/jdk1.2.2/jre/lib 

<xmlBlaster>
   <!-- A typical plugin which is loaded by client request -->
   <plugin id='dispatchPriority'
           className='org.xmlBlaster.util.dispatch.plugins.prio.PriorizedDispatchPlugin'
           jar='/tmp/my.jar'>
      <attribute id='config'>
         &lt;![CDATA[
         <msgDispatch defaultStatus='64k' defaultAction='send'>
         <onStatus oid='_bandwidth.status' content='64k' defaultAction='destroy'>
            <action do='send'  ifPriority='7-9'/>
            <action do='queue'  ifPriority='2-6'/>
         </onStatus>
         <onStatus oid='_bandwidth.status' content='2M'>
            <action do='send'  ifPriority='0-9'/>
         </onStatus>
         </msgDispatch>
         ]]&gt;
      </attribute>
   </plugin>

   <plugin id='queueCACHE' className='org.xmlBlaster.util.queue.cache.CacheQueueInterceptorPlugin'>
      <attribute id='transientQueue'>queueRAM</attribute>
      <attribute id='persistentQueue'>queueJDBC</attribute>
   </plugin>
   
   <plugin id='queueRAM' className='org.xmlBlaster.util.queue.ram.RamQueuePlugin'/>

   <plugin id='storageCACHE' className='org.xmlBlaster.engine.msgstore.cache.PersistenceCachePlugin'>
      <attribute id='transientQueue'>storageRAM</attribute>
      <attribute id='persistentQueue'>storageJDBC</attribute>
   </plugin>
   
   <plugin id='storageRAM' className='org.xmlBlaster.engine.msgstore.ram.MapPlugin'/>
   
   <!-- and here the declarations which are specific to the given nodes -->
   <node id='heron'>
      <plugin id='SOCKET-admin' className='org.xmlBlaster.protocol.socket.SocketDriver'>
         <attribute id='port'>69000</attribute>
      </plugin>
     
      <!-- /node/heron/plugin/SOCKET/attribute/port=6901 -->
      <!-- /node/heron/plugin/SOCKET/action/LOAD/onStartupRunlevel=3 -->
      <!-- /node/heron/plugin/SOCKET/action/LOAD/sequence=5 -->
      <plugin id='SOCKET' className='org.xmlBlaster.protocol.socket.SocketDriver'>
         <attribute id='port'>6901</attribute>
         <action do='LOAD' onStartupRunlevel='3' sequence='5' onFail='resource.configuration.pluginFailed'/>
         <action do='STOP' onShutdownRunlevel='2' sequence='4'/>
      </plugin>
     
      <plugin id='queueJDBC' className='org.xmlBlaster.util.queue.jdbc.JDBCQueueCommonTablePlugin'>
         <attribute id='url'>jdbc:oracle:thin:@localhost:1521:noty</attribute>
         <attribute id='user'>joe</attribute>
         <attribute id='password'>secret</attribute>
         <attribute id='connectionBusyTimeout'>90000</attribute>
         <attribute id='maxWaitingThreads'>300</attribute>
      </plugin>
     
      <plugin id='storageJDBC' className='org.xmlBlaster.engine.msgstore.cache.PersistenceCachePlugin'>
         <attribute id='url'>jdbc:oracle:thin:@localhost:1521:noty</attribute>
         <attribute id='user'>joe</attribute>
         <attribute id='password'>secret</attribute>
         <attribute id='connectionBusyTimeout'>90000</attribute>
         <attribute id='maxWaitingThreads'>300</attribute>
      </plugin>
    </node> <!-- heron -->
 
    <node id='avalon'>
       ...
      <plugin id='queueJDBC' className='org.xmlBlaster.util.queue.jdbc.JDBCQueueCommonTablePlugin'>
         <attribute id='url'>jdbc:oracle:thin:@localhost:1521:noty</attribute>
         <attribute id='user'>joe</attribute>
         <attribute id='password'>secret</attribute>
         <attribute id='connectionBusyTimeout'>90000</attribute>
         <attribute id='maxWaitingThreads'>300</attribute>
         <attribute id='tableNamePrefix'>AVALON_</attribute>
      </plugin>
      ...
    </node>
</xmlBlaster>

If a plugin is defined directly under the xmlBlaster tag, then its definition affects all nodes. Definitions under a specific node are stronger (i.e. they will overwrite any definition found under xmlBlaster and affect only the node under which they are defined.

If you don't want to load a plugin you simply don't put it in the xml tree. Alternatively you comment it out according to the xml syntax:

The plugin element:
The plugin tag has the following attributes:
  • id (mandatory) which is the name uniquely identifying this plugin configuration. The structure used to identify the plugins can be free chosen, it is needed for referencing the plugin with refid. Note that this id must be unique, you can not assign the same id to more than one plugin.
  • className (mandatory) the full name of the java class implementing the plugin.
  • jar (optional) the coloumn (:) separated list of jar files on which to search for the class to be loaded.
Besides the attributes, the plugin element has the following subtags:
  • attribute configuration parameters to be passed to the plugin (0 to n times)
  • action the action to be undertaken on the specified circumstances (0 to n times where n is normally 2)
The action subelement:
  • do attribute describing what to do on the specified event. It can be LOAD (which means load the plugin) or STOP (which means shutdown the plugin).
  • The event is specified by the attributes onStartupRunLevel (which is fired if the run level change is incrementing) or onShutdownRunLevel (which is fired by decrementing run level changes). The values of these attributes is an integer which corresponds to the run level on which they have to be activated respectively deactivated. If these attributes are omitted, then the run level manager will not load (respectively unload) the plugin. The plugins are loaded on client request (dynamically). It is allowed to define both attributes in the same action tag but we don't recommended it. It would mean that the same action is done both on increasing run level changes and in decreasing ones.
  • The sequence attribute is an integer defining the sequence number within the specified run level, on which do undertaken the specified action. If omitted it will implicitly be 0, that is, the first action on the given run level to be undertaken. If several plugins share the same sequence within the same run level, the sequence between them is unspecified. A 0 means it is the chronologically first action to be undertaken both on increasing changes and on decreasing ones.
  • the onFail attribute defines which exception to throw if the specified action fails, i.e. if an exception is thrown and the plugin could not be loaded. The value of this attribute is the error code of the exception to be thrown. If nothing (or empty) is specified, then the exception is catched, a warn or error is logged (error if runtime exception or xmlBlaster internal error) and the normal flow of the program is continued. If the error code is unknown a resource.configuration error is thrown and the runlevel flow is interrupted.
  • the create attribute wether this plugin has to be created or not. It defaults to 'true'. If you set it to false its configuration will be loaded but the plugin itself will not be created. This is a way to inhibit a plugin without the need of deleting its configuration.
The replacement for '${...}' is supported. Note that the assignment of a '$' variable can only be done in global scope, that is in the xmlBlaster.properties or command line, and JVM properties but not in the xmlBlasterPlugins.xml. This means that if you define 
 someName=someValue
and in the xmlBlasterPlugins.xml: 
    
   ...

      <attribute id='furtherAttribute'>${someName}</attribute>
   ...
then the attribute of 'furtheAttribute' will be 'someValue'.
Example
any

You can play with the run levels interactive on command line, start the server and type '?' when it is up to get the usage: 

java org.xmlBlaster.Main
...

----------------------------------------------------------
Following interactive keyboard input is recognized:
Key:
   g             Popup the control panel GUI.
   r <run level> Change to run level (0,3,6,9).
   d <file name> Dump internal state of xmlBlaster to file.
   q             Quit xmlBlaster.
----------------------------------------------------------

r 3

[RunlevelManager] Change request from run level RUNNING to run level STANDBY ...
[RunlevelManager] Successful shutdown to run level=CLEANUP.
[CorbaDriver] POA and ORB are down, CORBA resources released.
[RunlevelManager] Successful shutdown to run level=STANDBY.
Configure
Property Default Description Implemented
-pluginsFile /tmp/xmlBlasterPlugins.xml Specify an other plugin configuration file yes
runlevel 9 Choose run level on xmlBlaster server startup, e.g. 
java org.xmlBlaster.Main -runlevel 6
 yes

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

See API org.xmlBlaster.engine.runlevel.RunlevelManager
See API org.xmlBlaster.engine.runlevel.I_RunlevelListener
See REQ engine.runlevel.howto
See REQ admin

This page is generated from the requirement XML file xmlBlaster/doc/requirements/engine.runlevel.xml

Back to overview