XmlBlaster Logo



XmlBlaster Logo

Type NEW
Priority MEDIUM
Topic Description of the available commands for remote administration of xmlBlaster

XmlBlaster has an internal command interface which allows to monitor and control the server. You can connect to this command interface with arbitrary administration protocols like SNMP, telnet, JMX or xmlBlaster-command-messages.

What data can we monitor and control?

To understand the command syntax imagine a simple xml representation of xmlBlaster nodes (an xmlBlaster node is an xmlBlaster server instance in a cluster environment, read the cluster requirement for more informations). You can zoom into the server structure to examine any detailed data, some of the settings are changeable in hot operation:

   <node id='heron'>
      <startupDate>2005-03-20 11:19:12.322</startupDate>
      <uptime>34000</uptime>      <!-- sec -->
      <!-- runLevel=0 HALTED -->
      <!-- runLevel=3 ADMIN -->
      <!-- runLevel=6 CLEANUP -->
      <!-- runLevel=9 RUNNING -->

      <usedMem>6200000</usedMem> <!-- [bytes] -->
      <freeMem>1900000</freeMem> <!-- currently free in JVM [bytes] -->
      <maxFreeMem>13000000</maxFreeMem> <!-- free, totally allocatable by JVM [bytes] -->

      <hostname>server.mycomp.com</hostname> <!-- bootstrap -->

      <buildTimestamp>06/17/2002 01:59 PM</buildTimestamp>
      <buildJavaVendor>Sun Microsystems Inc.</buildJavaVendor>

      <serverTimestamp>2005-03-21 11:31:35.044</serverTimestamp>

      <lastWarning>&lt;![CDATA[JdbcDriver-/node/heron] Couldn't initialize driver 'org.firebirdsql.jdbc.FBDriver',
                   please check your CLASSPATH]]&gt;</lastWarning>
      <versionInfo>&lt;![CDATA[os.name=Linux, os.version=2.6.13-15-default, java.vm.vendor=Sun Microsystems Inc.,
                   java.vm.version=1.5.0_05-b05, os.arch=i386], ...&gt;</versionInfo>

      <gc/>   <!-- run garbage collector in xmlBlaster JVM -->
      <exit/> <!-- exit xmlBlaster server -->

      <!-- dump internal state (similar to this markup) -->

      <plugin id='SOCKET-admin' 

      <!-- A typical plugin which is loaded by client request -->
      <plugin id='dispatchPriority'
         <attribute id='config'>
            <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 oid='_bandwidth.status' content='2M'>
               <action do='send'  ifPriority='0-9'/>

      <!-- /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'/>  <!-- 0 first -->
         <action do='STOP' onShutdownRunlevel='2' sequence='4'/> <!-- 0 first -->

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

      <plugin id='queueRAM' className='org.xmlBlaster.util.queue.ram.RamQueuePlugin'/>

      <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 id='storageCACHE' className='org.xmlBlaster.engine.msgstore.cache.PersistenceCachePlugin'>
         <attribute id='transientQueue'>storage:RAM</attribute>
         <attribute id='persistentQueue'>storage:JDBC</attribute>

      <plugin id='storageRAM' className='org.xmlBlaster.engine.msgstore.ram.MapPlugin'/>

      <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>

      <clientThresholdOverflow type='event'/>

      <client id='joe'>

         <queue id='subject'> <!-- PtP queue -->
            <plugin refid='queueCACHE'/>

         <sessionThresholdOverflow type='event'/>

         <session id='-3'>


            <dispatch id='callback' sessionId='4e56890ghdFzj0'
                  pingInterval='10000' retries='-1' delay='10000'
               <plugin refid='dispatchPriority'/>
               <burstMode collectTime='400' />
               <compress type='gzip' minSize='3000'/>
               <queue id='callback'>
                  <plugin refid='queueCACHE'/>
                  <threshold>80</threshold>  <!-- 80% -->
                  <thresholdOverflow type='event'/> <!-- a trap -->
                  <clearAction>DEAD_MESSAGE | DISCARD</clearAction>
                  <entry id='556643'>
                     <topic refid='hello'>
                        <entry refid='1046976320144000020'/>
                  <plugin refid='SOCKET'/>

            <subscriptionDump>[The XML dump of all subscription informations]</subscriptionDump>
         </session> <!-- -3 -->

         <session id='17'>
      </client> <!-- joe -->

      <client id='jack'>

      <!-- System properties, xmlBlaster.properties and
           command line arguments -->
      <sysprop id='java.io.tmpdir'>/tmp</sysprop>
      <sysprop id='java.vm.version'>1.3.1</sysprop>
      <sysprop id='user.language'>es</sysprop>
      <sysprop id='Persistence.Path'>/home/mom/data</sysprop>
      <sysprop id='logFile'>/var/log/xmlBlaster-heron.log</sysprop>

      <!-- xmlBlaster messages -->

      <topic id='hello' contentMime='text/plain'>
         <persistence id='msgUnitStore'>
            <plugin refid='${QueuePluginCache}'/>
            <entry id='1046976320144000000'>  <!-- history entries -->
               <key oid='hello' contentMime='text/plain'/>
               <content>Hi world</content>
                  <expiration lifeTime='-1'/>
                  <rcvTimestamp nanos='1046976320144000000'/>
            <entry id='1046976320144000020'>
               <key oid='hello' contentMime='text/plain'/>
               <content>Bye world </content>
                  <expiration lifeTime='-1'/>
                  <rcvTimestamp nanos='1046976320144000020'/>
         <queue id='history'>
            <plugin refid='${QueuePluginCache}'/>
            <entry id='34455'>
               <topic refid='hello'>
                  <entry refid='1046976320144000000'/>
            <entry id='6643'>
               <topic refid='hello'>
                  <entry refid='1046976320144000020'/>
         <subscriptionList id='__subId:3'/> 

      <topic id='radar.track'>

      <subscription id='__subId:3'
                  creationTime='Mar 7, 2003 6:33:14 PM'/>
      <subscription id='__subId:XPATH2' oid='//key//sport'
                  creationTime='Mar 12, 2003 10:53:27 AM'>
         <subscription id='__subId:XPATH2:3' topicId='soccer'/>
         <subscription id='__subId:XPATH2:4' topicId='tennis'/>
         <subscription id='__subId:XPATH2:5' topicId='admiral cup'/>

   </node> <!-- heron -->

   <node id='avalon'>

As you have probably noticed, the tree syntax has class names like node or client and identifier which are instance names like heron or joe.

Lets have a look at the xmlBlaster cluster node heron. This is an xmlBlaster server running somewhere on the net (server.mycomp.com:3412).
heron has its own attributes like uptime and freeMem which are leafs in the tree. In addition heron has tags which have children themselves, more exact the tags:

  1. client Allows you to survey the logged in clients
  2. sysprop Inspect the system properties, xmlBlaster.properties and command line arguments
  3. topic Examine or manipulate the messages in xmlBlaster

The cb in for example cbSessionId is the abbreviation for callback.

What is allowed to do with these attributes?

Command Description MOM telnet SNMP JMX Impl
GET We can read all attributes get() get get getAttributes() yes
SET We can write/change selective attributes publish() set set setAttributes() yes
SUBSCRIBE We can subscribe for change events on selective attributes subscribe() - trap Notification yes*
POLL We can ask xmlBlaster to send us the current value of an attribute for example every 10 seconds (every specified amount of cycle time) subscribe() poll trap Notification yes*
SCHEDULE We can ask xmlBlaster to send us the current value of an attribute on fixed times, for example always at midnight subscribe() - trap Notification yes*

The column Impl states if the feature is implemented.

For JMX the DynamicMBean and Notification interface is used.

This feature is supported by the EventPlugin, please read the requirement admin.events for details on how to activate and configure it.

How can we query these attributes?

The following table gives an overview of the query syntax, it is URL conforming to allow direct queries from a browser and it is simple to allow typing it into a telnet terminal.

Command Description Impl
/node/?numNodes Query the number of xmlBlaster cluster nodes (running xmlBlaster instances) yes
/node/heron/?freeMem Query the free memory in bytes yes
/node/heron/?runlevel=3 Switch run level of heron to 3 (STANDBY) yes
/node/heron/?numClients How many clients are logged in to heron yes
set ?dump=ServerDump.xml Create a server dump yes
/node/heron/client/joe/?sessionList Retrieve the public session IDs of joe (if joe is logged in three times, there will be three entries) yes
client/joe/?sessionList Same as above but relative addressed yes
client/joe/session/1/?uptime How long is session ID 17 logged in (in seconds) yes
client/*/?uptime The uptime of all users (in seconds). Wildcards are not implemented yet. no
client/joe/session/1/?cbQueueMaxMsgs=30000 Change max. callback queue size of client joe with login session ID 17 to 30 thousand messages yes
client/joe/session/1/?cbQueueNumMsgs Access the current number of messages in joe's callback queue waiting to be delivered yes
client/joe/session/-5/?subscriptionList Show all subscriptions 'joe' has made (with his login session '-5') yes
client/joe/session/-5/?numUpdate How many update messages were delivered to joe's session '-5' since server startup? yes
/node/heron/sysprop/?java.vm.version Access the JDK version yes
sysprop/?user.language=es Change the language to spanish (relative addressed) yes
logging/?org.xmlBlaster=WARNING Switch off INFO level logging yes
logging/?org.xmlBlaster.engine.RequestBroker=FINE Switch on trace mode for the xmlBlaster core class yes
/node/heron/?numTopics How many messages are currently in heron yes
/node/heron/topic/?Hello Return the complete message (oid=Hello) yes
topic/Hello/?peekHistoryMessages=2 Access max. two messages with key-oid="Hello" yes
/node/heron/topic/Hello/?content=How are you Change the message content of the message with key-oid="Hello" to "How are you" no
/node/heron/topic/Hello/?toXml Returns the topic dump yes
/node/heron/topic/Hello/?key.contentMime Return the MIME type of this message no
client/joe/session/1/?killSession Kills the first session of joe (force logout) no
client/joe/session/1/?dispatcherActive tells if the DispatchManager of the specified session is active for asynchronous dispatch no
client/joe/session/1/?dispatcherActive=true tells the DispatchManager of the specified session to become active no
?serverTimestamp The current time of the server, for example "2005-03-21 11:18:12.622" no

You can address an attribute with global scope /node/heron/client/joe/?uptime or with relative scope client/joe/?uptime. The relative query assumes the current xmlBlaster node you are connected to.

How does the return value look like?

Responses for telnet clients are described in the requirement admin.telnet.

Mom clients receive messages with the value in the message content, see requirement admin.messages.

How can we use these commands?

Here are example invocations from different clients:

Protocol Example Description Impl
MoM clients
"<key oid='__cmd:?freeMem'/>",
The token __cmd: marks the oid to be used as a command.
Here we have used relative addressing, absolute __cmd:/node/heron/?freeMem would be identical.

For example try (in one line)
java org.xmlBlaster.client.reader.GetMessage
-oid __cmd:?clientList
Here we change the logging level of the corba plugin:
java org.xmlBlaster.client.feeder.PublishFile
-xmlKey "<key oid='__cmd:logging/?org.xmlBlaster.util=FINER'/>"
Exit xmlBlaster with exit value 9:
java org.xmlBlaster.client.feeder.PublishFile
-xmlKey "<key oid='__cmd:?exit=9'/>"
get ?runlevel
set /node/heron/?runlevel=3
set logging/?org.xmlBlaster=WARNING
With telnet you give the command get or set followed by the query (separated with a blank) yes
snmpget -v 1 -c public
-c is community password, usually 'public', the IP is where the master agent runs   xmlBlaster objects traps 
 objects momTable momEntry uptime
j org.xmlBlaster:nodeClass=node,
On the command line of a running server you can use the shown command. Alternatively you can use any other GUI JMX tool as described in requirement admin.jmx, typically you will use jconsole. yes

How does authentication work?

  • For MoM clients the usual authentication applies.
  • For telnet clients you have to use the
    connect <loginName> <password>
    command on startup.
  • For SNMP access the authentication is done in SNMP
  • For JMX we have not investigated yet


Here is an example of a complete and valid URI, we should try not to break this syntax with our query language. You can use the similar syntax for building administrative html pages as described in requirement admin.http.


Protocol: http
Host:     www.xmlBlaster.org
Port:     3412
File:     /myPath/?key.oid=MyMessage
Path:     /myPath/
Query:    key.oid=MyMessage
Ref:      myFragment
UserInfo: joe:mypasswd

The problem is that the UserInfo is cut away from the browser, we need to pass it somewhere in the path.


Example for activating or prohibiting message delivery to a subscriber

Here is a command line example of controlling message delivery to a subscriber joe/1, open three console windows and start the server, a publisher and a subscriber:

java org.xmlBlaster.Main

java javaclients.HelloWorldSubscribe -session.name joe/1
 (hit a key to subscribe ...)

java javaclients.HelloWorldPublish -numPublish 100

Publish some messages to see them arriving at the subscriber, now we deactivate the delivery of messages using telnet:

telnet localhost 2702 : eecchhoo  ooffff : connect jack secret : set client/joe/session/1/?dispatcherActive=false

If you now publish more messsages they won't arrive at the subscriber, now activate delivery again: : set client/joe/session/1/?dispatcherActive=true

and all missing messages will arrive.

The same you can do over the jconsole GUI or by publishing the administrative command from command line:

java javaclients.HelloWorldPublish -oid __cmd:client/joe/session/1/?dispatcherActive=true

The available commands are marked as R=readable, W=writable, S=subscribable T=schedulable, P=pollable

If you want to change a value, you need to use a publish() message, or with telnet you would use set, for SNMP you use a set command as well.

Command Type Read/Write Description Implemented
client/joe/?uptime int R Get the number of seconds the user is logged in yes
logging/?org.xmlBlaster.util.queue=FINE boolean R/W Monitor or change the log level, but only for queuing issues yes

See the API links of I_AdminNode, I_AdminSubject, I_AdminSession below of the available core properties to monitor or configure

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.

  • SNMP (SnmpGateway.java) support is missing.
  • Wildcard queries are only supported by EventPlugin, others are not implemented.
  • XPath queries with JXPath
See API org.xmlBlaster.engine.admin.I_AdminNode
See API org.xmlBlaster.engine.admin.I_AdminSubject
See API org.xmlBlaster.engine.admin.I_AdminSession
See API org.xmlBlaster.engine.admin.extern.TelnetGateway
See REQ admin
See REQ admin.telnet
See REQ admin.messages
See REQ engine.runlevel
See REQ engine.qos.queryspec.QueueQuery

This page is generated from the requirement XML file xmlBlaster/doc/requirements/admin.commands.xml

Back to overview