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:
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 1000For 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 Parameters | ported to new syntax |
---|---|
Choice of Connection Protocol | |
Security Features | |
Security Plugin Specific Properties | |
Session Settings | |
Failsafe Connection to XmlBlaster Server | |
Server Side Callback (in case we install a local callback server) | |
Queue ClientSide Storage Properties | |
Queue Callback Storage Properties | |
Specific Communication Protocol Options | |
Logging Options | |
Properties Framework |
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 line | Comment 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 line | Comment 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 line | Comment 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 line | Comment and [default] |
---|---|
-queue/connection/maxEntries | The maximum allowed number of messages [1000]. |
-queue/connection/maxEntriesCache | The maximum allowed number of messages in the cache [1000]. |
-queue/connection/maxBytes | The maximum size in bytes of the storage [10485760]. |
-queue/connection/maxBytesCache | The maximum size in bytes in the cache [2097152]. |
-queue/connection/onOverflow | What happens if storage is full [deadMessage] |
-queue/connection/onFailure | Error handling when storage failed [deadMessage] |
-queue/connection/type | The plugin type [RAM] |
-queue/connection/version | The plugin version [1.0] |
-queue/connection/defaultPlugin | The plugin type,version (short form) [RAM,1.0] |
Queue Callback Storage Properties
Command line | Comment and [default] |
---|---|
-queue/callback/maxEntries | The maximum allowed number of messages [1000]. |
-queue/callback/maxEntriesCache | The maximum allowed number of messages in the cache [1000]. |
-queue/callback/maxBytes | The maximum size in bytes of the storage [10485760]. |
-queue/callback/maxBytesCache | The maximum size in bytes in the cache [2097152]. |
-queue/callback/onOverflow | What happens if storage is full [deadMessage] |
-queue/callback/onFailure | Error handling when storage failed [deadMessage] |
-queue/callback/type | The plugin type [RAM] |
-queue/callback/version | The plugin version [1.0] |
-queue/callback/defaultPlugin | The plugin type,version (short form) [RAM,1.0] |
-maxBytes 10000then 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.
|
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 20000The 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 SOCKETThe -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.
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); callback.setPingInterval(1000); qos.addCallbackAddress(callback); SessionQos sessionQos = qos.getSessionQos(); sessionQos.setMaxSessions(1); sessionQos.setReconnectSameClientOnly(true); this.con.connect(qos, this); ...