XmlBlaster Logo



XmlBlaster Logo

Type NEW
Priority MEDIUM
Topic Description of the available client side configuration

If you want to use the default behavior of xmlBlaster clients you don't need to bother about configuration parameters. For many usages however it is necessary to modify some of the parameters. These can be specified in the following ways:

  • a configuration file (normally xmlBlaster.properties)
  • on the command line
  • via setter methods in the code

The configuration file is the weakest, followed by the command line. The setter methods are the strongest and will overwrite defaults. The configuration file can reside in different directories.

Configuration File
The search path and sequence is described in the util.property requirement. For tips and syntax inside the configuration file have a look at the requirement util.property.env

Command Line
on the command line you can assign values to configuration parameters by prepending a - sign to the name of the parameter, then a space and then the value to be assigned. For example the following is correct syntax:

java HelloWorld2 -dispatch/connection/pingInterval 1000
For a list of all available command line parameters invoke -help on the command line:
java HelloWorld2 -help

Setter Methods
A further alternative (and the strongest one) to assign values to the configuration parameters, is to explicitly set them in the client code you write yourself. Here follows a simple example:

   ConnectQos qos = new ConnectQos(glob);
   Address address = new Address(glob);
   address.setDelay(4000L);      // retry connecting every 4 sec
   address.setRetries(-1);       // -1 == forever
   address.setPingInterval(0L);  // switched off
For a more detailed example have a look at the code for HelloWorld6.

The following is a list of groups of properties used to configure xmlBlaster clients. We are changing the syntax for the properties from the original "dot and bracket" syntax like

  -socket.responseTimeout 1000
  -trace[core] true
to the new "slash" notation which we believe fits better our needs
  -queue/callback/maxEntries 1000   
This is an ongoing process and not all properties have been ported yet. You can read the status of this porting in the right column in the next table.
Groups of Parametersported to new syntax
Choice of Connection Protocolyes
Security Featuresno
Security Plugin Specific Propertiesno
Session Settingsno
Failsafe Connection to XmlBlaster Serveryes
Server Side Callback (in case we install a local callback server)yes
Queue ClientSide Storage Propertiesyes
Queue Callback Storage Propertiesyes
Specific Communication Protocol Optionsno
Logging Optionsno
Properties Frameworkno

Please use the -help option to check the current status:

 java org.xmlBlaster.Main -help     (server side configuration)

 java HelloWorld3 -help             (client side configuration)

Failsafe Connection to XmlBlaster Server
The following parameters control the client side dispatch configuration

Command lineComment and [default]
-dispatch/connection/burstMode/collectTime Number of milliseconds we shall collect publish messages [0]. This allows performance tuning, try set it to 200.
-dispatch/connection/pingInterval Pinging every given milliseconds [10000]
-dispatch/connection/retries How often to retry if connection fails (-1 is forever) [-1]
-dispatch/connection/delay Delay between connection retries in milliseconds [5000] A delay value > 0 switches fails save mode on, 0 switches it off
-dispatch/connection/protocol You can choose another protocol for the communication to xmlBlaster [defaults to -protocol]
-bootstrapPort You can choose another bootstrapPort for the communication to xmlBlaster [3412]
-dispatch/connection/plugin/xmlrpc/port You can choose another XmlRpc port for the communication to xmlBlaster [defaults to -plugin/xmlrpc/port]

Protocol specific configuration
The following parameters control the client side dispatch configuration, in this example we show the options for the SOCKET protocol.

Command lineComment and [default]
-dispatch/connection/plugin/socket/hostname IP or DNS host name where the xmlBlaster server is running [localhost].
-dispatch/connection/plugin/socket/port The port where the server is listening [7607]
-dispatch/connection/plugin/socket/localHostname Usually you don't need to set this parameter. My be useful for example if you are running on a multi homed host having multiple local IP addresses [localhost].
-dispatch/connection/plugin/socket/localPort Usually this is dynamically chosen by your OS. You can configure it for example if you need to force a local port to satisfy a firewall.

Server Side Callback (in case we install a local callback server)
The following parameters control the callback (server side) dispatch configuration. It only makes sense to configure these if you have assigned a callback to this session.

Command lineComment and [default]
-dispatch/callback/sessionId The session ID which is passed to our callback server update() method.
-dispatch/callback/burstMode/collectTime Number of milliseconds xmlBlaster shall collect callback messages [0]. The burst mode allows performance tuning, try set it to 200.
-dispatch/callback/oneway Shall the update() messages be send oneway (no application level ACK) [false]
-dispatch/callback/pingInterval Pinging every given milliseconds the clients callback server [10000]. If the ping fails the server will retry as specified with dispatch/callback/retries or destroy the clients session.
-dispatch/callback/retries How often to retry if callback fails (-1 forever, 0 no retry, > 0 number of retries) [-1]. After the retries have exceeded the clients login session is destroyed.
-dispatch/callback/delay Delay between callback retries in milliseconds [5000]
-dispatch/callback/compress/type With which format message be compressed on callback []
-dispatch/callback/compress/minSize Messages bigger this size in bytes are compressed [0]
-dispatch/callback/ptpAllowed PtP messages wanted? false prevents spamming [true]
-dispatch/callback/protocol You can choose another protocol for the callback server [defaults to -protocol]
-dispatch/callback/plugin/socket/port You can choose another port for the callback server [defaults to the protocol specific default port]

Queue Client Side Storage Properties

Command lineComment and [default]
-queue/connection/maxEntriesThe maximum allowed number of messages [1000].
-queue/connection/maxEntriesCacheThe maximum allowed number of messages in the cache [1000].
-queue/connection/maxBytesThe maximum size in bytes of the storage [10485760].
-queue/connection/maxBytesCacheThe maximum size in bytes in the cache [2097152].
-queue/connection/onOverflowWhat happens if storage is full [deadMessage]
-queue/connection/onFailureError handling when storage failed [deadMessage]
-queue/connection/typeThe plugin type [RAM]
-queue/connection/versionThe plugin version [1.0]
-queue/connection/defaultPluginThe plugin type,version (short form) [RAM,1.0]

Queue Callback Storage Properties

Command lineComment and [default]
-queue/callback/maxEntriesThe maximum allowed number of messages [1000].
-queue/callback/maxEntriesCacheThe maximum allowed number of messages in the cache [1000].
-queue/callback/maxBytesThe maximum size in bytes of the storage [10485760].
-queue/callback/maxBytesCacheThe maximum size in bytes in the cache [2097152].
-queue/callback/onOverflowWhat happens if storage is full [deadMessage]
-queue/callback/onFailureError handling when storage failed [deadMessage]
-queue/callback/typeThe plugin type [RAM]
-queue/callback/versionThe plugin version [1.0]
-queue/callback/defaultPluginThe plugin type,version (short form) [RAM,1.0]

Note that if you omit the prefix, i.e. if you write on the command line
-maxBytes 10000
then you will assign this both to the connection queue and to the callback queue.

To understand the command syntax imagine a simple xml representation of an xmlBlaster client.

  <node id='heron'>
    <plugin id='queueCACHE' 
       <attribute id='transientQueue'>queueRAM</attribute>
       <attribute id='persistentQueue'>queueJDBC</attribute>

    <plugin id='queueRAM' 

    <plugin id='queueJDBC' 
       <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>

    <client id='joe'>
       <session id='-3'>


          <dispatch id='callback' sessionId='4e56890ghdFzj0'
                pingInterval='10000' retries='-1' delay='10000'
                oneway='false' burstModeCollectTime='0' ptpAllowed='true'>
             <plugin refid='dispatchPriority'/>
             <burstMode collectTime='400' />
             <compress type='gzip' minSize='3000'/>
             <plugin refid='queueCACHE'>
                <attribute id='numEntries'>7</attribute>
                <attribute id='numBytes'>90023</attribute>
                <attribute id='onOverflow'>DEAD_MESSAGE</attribute>
             <plugin refid='XMLRPC'>
                <attribute id='hostname'>client.mycomp.com</attribute>
                <attribute id='port'>8080</attribute>

          <!-- The settings used on the client side -->
          <dispatch id='connection'
                    pingInterval='2000' retries='-1' delay='5000'
             <plugin refid='queueCACHE'>
                <attribute id='maxEntries'>200</attribute>
                <attribute id='entry'>
                   <attribute id='id'>1046976320188000000</attribute>
                   <attribute id='type'>publish'</attribute>
                      <!-- client side queued entries -->
                   <attribute id='key'>
                     <attribute id='oid'>hello</attribute>
                     <attribute id='contentMime'>text/plain</attribute>
                   <attribute id='content'>Salute</attribute>
                   <attribute id='qos'>
                     <attribute id='persistent' />
                     <attribute id='sender'>/node/heron/client/joe</attribute>
                     <attribute id='expiration'>
                        <attribute id='lifeTime'>-1</attribute>
             <plugin id='XMLRPC'
                <attribute id='hostname'>server.mycomp.com</attribute>
                <attribute id='port'>6901</attribute>

          <plugin id='XMLRPC-callback'
             <attribute id='hostname'>client.mycomp.com</attribute>
             <attribute id='port'>8080</attribute>

       </session> <!-- -3 -->

    </client> <!-- joe -->

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

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

The following means to set the maximum number of entries in the callback queue to 100. To set the maximum number of entries for the client side queue also to 100 and to put all ping intervals both on client and server side since no prefix is specified) to 20 seconds.

    java HelloWorld2 -queue/callback/maxEntries 100   \
                     -queue/connection/maxEntries 100 \
                     -pingInterval 20000
The following command line has the same effect since it sets the maximum number of entries for all queues (so it automatically sets it for callback and client side queue) to 100 and sets individually the ping interval for the client pinging the server to 3 seconds and the ping interval of the server checking the clients callback listener to 20 seconds.
    java HelloWorld2 -maxEntries 100                        \
                     -dispatch/callback/pingInterval 20000  \
                     -dispatch/connection/pingInterval 3000 \
                     -protocol SOCKET
The -dispatch/callback/pingInterval property is sent to the server with the ConnectQos and configures the server behavior. The -dispatch/connection/pingInterval setting is only evaluated on the client side. -maxEntries 100 is looked at on client and on server side.
We have chosen the SOCKET protocol to talk to xmlBaster.

Assuring a client singleton

If you have to assure that an important client may only connect exactly once you can use xmlBlaster to assure this with following options (try the example on the command line):

java org.xmlBlaster.Main

java HelloWorld4 -protocol SOCKET
                 -session.name Jack/1
                 -session.reconnectSameClientOnly true
                 -session.maxSessions 1
                 -dispatch/callback/pingInterval 1000

java HelloWorld4 -protocol SOCKET
                 -session.name Jack/1
                 -session.reconnectSameClientOnly true
                 -session.maxSessions 1
                 -dispatch/callback/pingInterval 1000
                 -xmlBlaster_uniqueId Jacky

-session.maxSessions 1 assures that max. one session of Jack exists and -session.reconnectSameClientOnly true does only allow the creator of the session to reconnect, the second client using the same public session ID 1 gets no access.
If the first client crashes our frequent callback ping (every second) assures that the session of the crashed client is destroyed latest after one second and the second HelloWorld2 could now connect and take over the task.

The setting -xmlBlaster_uniqueId Jacky we only need if we use HSQLDB as persistent layer to force a different database name of the second client (the database name is generated from the session.name and as this is the same for both clients and both run on the same test machine we need to force another setting).

Hard coded in a Java client it looks something like:


this.con = glob.getXmlBlasterAccess();

ConnectQos qos = new ConnectQos(glob, "JOE/1", "secret");

CallbackAddress callback = new CallbackAddress(glob);

SessionQos sessionQos = qos.getSessionQos();
this.con.connect(qos, this);


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.client.I_XmlBlasterAccess
See REQ util.property.env
See REQ interface
See REQ protocol
See REQ admin.errorcodes
See TEST org.xmlBlaster.test.qos.TestReconnectSameClientOnly

This page is generated from the requirement XML file xmlBlaster/doc/requirements/client.configuration.xml

Back to overview