XmlBlaster Logo

REQUIREMENT

protocol.socket

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic XmlBlaster supports a bidirectional native communication protocol using exactly one socket connection
Des
cription

RPC (remote procedure call) based frameworks like CORBA, RMI and XmlRpc require the client to set up a callback server for asynchronous callbacks. This causes problems if the client is behind a firewall or if the client may not establish a listen socket. Reusing a socket for callbacks solves this problem.

Further this protocol can be used for simple access from other programming languages like C.

Protocol specification

Design decisions:

  • Uses no bit settings to allow simple access with any programming language
  • To avoid bigendian/littleendian problems no netlong etc. are used
  • All numbers are delivered as strings.
  • The fixed size header fields have even boundaries
  • Compact format for good performance

This specifies the raw data format, '*' is used to symbolize null terminated strings: 

msgLen[10] flag[6] requestId methodName secretSessionId lenUnzipped userData checkSum[10]
+---------+-------+------ -*----------*----------------*-----------*--------+-----------+

Description:

Field Description Size [bytes]
msgLen The number of bytes of the message, including itself, the header, the data (and the checksum if appended). Each digit is a single byte with number characters, the numbers are right adjusted with leading blanks (0x20). For example a byte with the integer values 0x34 is meant to be the character number '4'. 10
flag The flag defaults to zero (all bits are '\0', only version is set to one '1'=49 and 'I'=73 for invoke), possible settings of each byte are:
  1. 65 (typically 'A') Adler32 checksum is appended (see java.util.zip) [Currently not supported]
  2. 90 (typically 'Z') The userData is compressed with gzip (see jzlib and zlib). Currently there is support to compress the whole socket stream - in such case this flag makes no sense and is not set
  3. Type of message
    • 73 (typically 'I') for invoke request
    • 82 (typically 'R') for return value
    • 69 (typically 'E') for exception
  4. null ('\0'), Reserved
  5. null ('\0'), Reserved
  6. 49 (typically '1') Version byte for this protocol
 6
requestId An identifier of this request (unique in client scope), the return message will contain this ID. The server bounces this requestId back, it does not use it. This is useful for the client to find out which response belongs to which request.
For callback calls like update() or ping() the client must return this id so xmlBlaster knows to which invocation the response belongs.		 null terminated
methodName The method to invoke, like "publish", "subscribe", "update" null terminated
secretSessionId The secret session ID for authentication, it is empty on first connect and generated by xmlBlaster for the connect return QoS. All other requests then use this secret session ID null terminated
lenUnzipped The length of the uncompressed user data, allows for example in C to simple allocate enough memory. This field has only a value if the flag is set to 'Z' (compressed), otherwise it is just the terminating '\0'. null terminated
userData The arguments of the invoked message (see below) any (0 is allowed as well)
checkSum An optional checksum if the flag field is set 10

The userData has the following typical layout. 

     qos      key    len   content
   +-----*---------*-----*----------+

len (written as a string with a terminating 0) is the length of the content.
This may be repeated multiple times if an array of MsgUnits is sent.
If for example only a qos is transmitted, the key may optionally consist only of the terminating null byte and the content len is set to 0 with a terminating null byte.

The following table lists all allowed methods, with their arguments, return values and exceptions.
Note that all data types are of type string and are terminated with a '\0'.
Only the content is of type 'binary' which length can be calculated by the len field. Binary data is not zero terminated.

Method Arguments Return value Excep
tion		 Comment
connect QoS{string} QoS{string} yes The secretSessionId field is an empty string (just the '\0'), the server generates and returns it.
disconnect QoS{string} QoS{string} yes The server sends the response (ACK) immediately from the SOCKET layer. It can't send it later because the socket is shutdown during server side disconnect
ping QoS{string} QoS{string} no The QoS can be an empty string ""
{exception} errorCode{string}, message{string}, byteDump of exception - no Exception return messages are named similar to the invoked method but are marked with an 'E' flag.
See XmlBlasterException.java toByteArr() for the syntax of the binary message content.
update [QoS{string}, key{string}, content{binary}]* [QoS{string}]* yes This is a callback message to the client, the message unit (QoS, key, content) may be specified multiple times. Every message unit has a corresponding return QoS.
updateOneway [QoS{string}, key{string}, content{binary}]* - no This is a callback message to the client, the message unit (QoS, key, content) may be specified multiple times. There is no return value and no exception which can be thrown for maximum performance.
This call can be configured to use UDP instead of TCP, note however that UDP has a limited datagram size.
publish [QoS{string}, key{string}, content{binary}]* [QoS{string}]* yes The message unit [QoS, key, content] may be specified multiple times. Every message unit has a corresponding return QoS. This publish covers the CORBA publish() and the CORBA publishArr().
publishOneway [QoS{string}, key{string}, content{binary}]* - no The message unit [QoS, key, content] may be specified multiple times. There is no return value and no exception which can be thrown for maximum performance.
This call can be configured to use UDP instead of TCP, note however that UDP has a limited datagram size.
get QoS{string}, key{string} [QoS{string}, key{string}, content{binary}]* yes The returned QoS, key, content may be zero to multiple items
subscribe QoS{string}, key{string} QoS string yes subscribe for messages
unSubscribe QoS{string}, key{string} [QoS{string}]* yes cancel subscriptions
erase QoS{string}, key{string} [QoS{string}]* yes erase messages

NOTE:

The raw SOCKET address transferred in the connect QoS markup is of the form 

socket://host:port

for example: 

socket://127.168.1.2:7607

Example
any 
      
      
Example of a publish() invocation with qos/key/content

   "        83**I**17711*publish*oxf6hZs**<qos></qos>*<key oid='hello'/>*11*Hello world"

Example of a get() invocation with qos/key

   "        70**I**17711*get*oxf6hZs**<qos></qos>*<key oid='ooo'></key>*0*"

Example of a publish() return with qos

   "        48**R**17711*publish*oxf6hZs**<qos/>**0*"

Example of an empty get()

   "        34**I**17711*get*oxf6hZs**"

Example of a ping() (with an empty qos):

   "        25**I**11*ping***"

Example of an XmlBlasterException as a response on a publish() (a content is not shown):

   "        84**E**17711*publish*oxf6hZs**QueueOverflow*The destination queue is full*0*"

Example of a qos/key/content return value of a get()

   "        81**R**17711*get***<qos></qos>*<key oid='hello'/>*20*Hello world response"

Example of a QoS return value of erase()

   "        60**R**17711*erase***<qos><state id='OK'/></qos>**0*"

Example of publish() with two qos/key/content (split to two lines)

   "       100**I**17711*publish*oxf6hZs**<qos/>*<key oid='x1'/>*6*Hello1<qos/>
    *<key oid='x2'/>*6*Hello2"


The '*' is used as a symbol for a '\0' character (all zero bits) which terminates strings.

The content of a message, here for example 'Hello world' is binary data and has no '\0',
it is determined by len.

The '"' is just to show the boundary, '"' is not part of the message.
      

      You can switch on dumping of such SOCKET messages with following command line argument (all in one line):
      
      
java -Dcom.sun.management.jmxremote org.xmlBlaster.Main
     -logging/org.xmlBlaster.util.protocol.RequestReplyExecutor FINEST 
     -logging/org.xmlBlaster.util.protocol.socket.SocketExecutor FINEST
     -logging/org.xmlBlaster.util.xbformat.XbfParser FINEST
Example
Java

Java command line examples

You can switch on nice debugging output with these options: 

java -jar lib/xmlBlaster.jar -dump[socket] true -trace[socket] true

Here we start the xmlBlaster server and it will offer its SOCKET service on host myHost.com and on port 7766: 

java -jar lib/xmlBlaster.jar -plugin/socket/hostname myHost.com
                             -plugin/socket/port 7766

This client tries to find an xmlBlaster server instance at host myHost.com and on port 7766: 

java HelloWorld3 -protocol SOCKET -dispatch/connection/plugin/socket/hostname myHost.com
                                  -dispatch/connection/plugin/socket/port 7766

Here we do the same hard coded in Java: 

...

String[] args = { "-protocol", "SOCKET",
                "-dispatch/connection/plugin/socket/hostname", "myHost.com",
                "-dispatch/connection/plugin/socket/port", "7766",
                "-dispatch/connection/plugin/socket/localHostname", "myHost.com",
                "-dispatch/connection/plugin/socket/localPort", "8888" };
glob.init(args);

ConnectQos qos = new ConnectQos(glob);

...
Example
Java

Using SSL communication

To establish a SSL connection you need to set some configuration properties on command line or in xmlBlaster.properties. This works out of the box for JDK 1.4 and above. For JDK 1.3 you need to install the SSL support separately. SSL is available with IBM JDK 1.4 as well, using for example a client running with SUN JDK 1.4 or 1.5 to communicate with a xmlBlaster server running with IBM JDK 1.4 (even if compiled with SUN JDK 1.3) works fine.

The first step is to generate a certificate with the keytool program that comes with the SDK. Issue the keytool command with the -genkey option to generate a keypair, the -keystore option to specify the key store file, and the -keyalg options to specify the encryption algorithm, read the SSL tutorial and the SSL reference guide for more details: 

keytool -genkey -dname "cn=xmlBlaster, ou=server, o=xmlBlaster, c=org" -alias xmlBlaster
        --keypass testtest -keystore testStore -storepass testtest -keyalg RSA

Now you are ready to start the xmlBlaster server with enabled SSL (all in one line): 

java -jar lib/xmlBlaster.jar -plugin/socket/SSL true -plugin/socket/keyStore testStore
                                                     -plugin/socket/keyStorePassword testtest

and finally we start a client to test it (Note: Under real conditions never pass the 'testStore' file itself to the client, for more details read the next section about certificates): 

java HelloWorld3 -protocol SOCKET -plugin/socket/SSL true -plugin/socket/trustStore testStore

To check the encryption dump the TCP/IP packages for example with tcpdump: 

tcpdump -i lo -A -vvv dst port 7607

If you encounter problems you can switch on SSL debugging with 

java -Djavax.net.debug=all ...

These are the benefits of the above connection:

  • Integrity Protection. SSL protects against modification of messages by an active wiretapper.
  • Authentication. Here xmlBlaster is authenticated, the client knows to which xmlBlaster it talks, but xmlBlaster does not assure on this SSL layer who the client is.
  • Confidentiality (Privacy Protection). In most modes, SSL encrypts data being sent between client and server. This protects the confidentiality of data, so that passive wiretappers won't see sensitive data such as financial information or personal information of many kinds.
Example
Java

Using SSL communication with additional client authentication

In the section before we have explained how to establish a SSL connection between a client and xmlBlaster, in that setup xmlBlaster did not authenticate the clients on SSL layer. Let's add additionally client authentication. The following steps create a client private key and than exchange the clients and servers public key so that both sides know the other side.

Create a private key for client joe:

keytool -genkey -dname "cn=joe, ou=client, o=xmlBlaster, c=org" -alias joe --keypass testtest -keystore testStore.joe -storepass testtest -keyalg RSA

Export joe's certificate:

keytool -alias joe -export -keystore testStore.joe -storepass testtest -rfc -file joeTrustStore.Cert

and import it to the servers trust store named testStore:

keytool -import -alias joe -file joeTrustStore.Cert -keystore testStore -storepass testtest

Create a certificate of the xmlBlaster server (the servers private key is in testStore which was created in the example before):

keytool -alias xmlBlaster -export -keystore testStore -storepass testtest -rfc -file xmlBlasterTrustStore.Cert

and import it to joe's trust store:

keytool -import -alias xmlBlaster -file xmlBlasterTrustStore.Cert -keystore testStore.joe -storepass testtest

On problems look into the key store file and verify all is correct:

keytool -list -v -storepass testtest -keystore testStore.joe
keytool -list -v -storepass testtest -keystore testStore
keytool -printcert -file xmlBlasterTrustStore.Cert

Start the server:

java -jar lib/xmlBlaster.jar -plugin/socket/SSL true -plugin/socket/keyStore testStore -plugin/socket/keyStorePassword testtest -plugin/socket/trustStore testStore -plugin/socket/trustStorePassword testtest -plugin/socket/needClientAuth true

and a client to test it:

java HelloWorld3 -protocol SOCKET -plugin/socket/SSL true -plugin/socket/keyStore testStore.joe -plugin/socket/keyStorePassword testtest -plugin/socket/findStoreInXmlBlasterSearchPath true

These are the benefits of the above connection:

  • Integrity Protection. SSL protects against modification of messages by an active wiretapper.
  • Authentication. Here SSL provides peer authentication. The xmlBlaster server is authenticated, and clients need to authenticate themselves.
  • Confidentiality (Privacy Protection). In most modes, SSL encrypts data being sent between client and server. This protects the confidentiality of data, so that passive wiretappers won't see sensitive data such as financial information or personal information of many kinds.

Note: With the setting -plugin/socket/findStoreInXmlBlasterSearchPath true it is for example possible to put the testStore.joe in the xmlBlaster.jar file and it is found over the CLASSPATH.

Note: To simplify the server setup you should add all server settings to the xmlBlasterPlugins.xml file as described in the next example.

Example
Java

Configuring SSL and normal SOCKET communication

If you want to establish a SSL SOCKET server besides a plain text SOCKET server you need to register two SOCKET protocol drivers each listening on a different port. Here is an example of such entries in xmlBlasterPlugins.xml: 

<plugin id='SOCKET' className='org.xmlBlaster.protocol.socket.SocketDriver'>
   <action do='LOAD' onStartupRunlevel='3' sequence='2' 
           onFail='resource.configuration.pluginFailed'/>
   <action do='STOP' onShutdownRunlevel='2' sequence='5'/>   
</plugin>

<plugin id='socket_ssl' className='org.xmlBlaster.protocol.socket.SocketDriver'>
   <action do='LOAD' onStartupRunlevel='3' sequence='2' 
           onFail='resource.configuration.pluginFailed'/>
   <action do='STOP' onShutdownRunlevel='2' sequence='5'/>   
   <attribute id='SSL'>true</attribute>
   <attribute id='trustStore'>testStore</attribute>
   <attribute id='trustStorePassword'>testtest</attribute>
   <attribute id='keyStore'>testStore</attribute>
   <attribute id='keyStorePassword'>testtest</attribute>
   <attribute id='needClientAuth'>false</attribute>
   <attribute id='port'>7609</attribute>
   <attribute id='startUdpListener'>false</attribute>
</plugin>

Now the plain SOCKET is listening on default port 7607 and the SSL SOCKET listens on port 7609. The 'trustStore' settings are need only when you set up clustering with SSL SOCKET cluster internal communication - in this case the xmlBlaster server is a client to another xmlBlaster cluster node and needs the imported certificate of the remote node in 'testStore'.
Additionally we register the socket_ssl plugins in xmlBlaster.properties: 

# Server side:
CbProtocolPlugin[socket_ssl][1.0]=\
       org.xmlBlaster.protocol.socket.CallbackSocketDriver,SSL=true

# Client side:
ClientProtocolPlugin[socket_ssl][1.0]=\
       org.xmlBlaster.client.protocol.socket.SocketConnection,SSL=true

# Client side:
ClientCbServerProtocolPlugin[socket_ssl][1.0]=\
       org.xmlBlaster.client.protocol.socket.SocketCallbackImpl,SSL=true

Starting the server is simple as all configuration is done in the above xmlBlasterPlugins.xml file (please read the previous example on how to initially generate a keystore): 

java -jar lib/xmlBlaster.jar

Here we start a client using the default plain text SOCKET connection: 

java HelloWorld3 -protocol SOCKET

and here we start another client using the secure SSL SOCKET connection: 

java HelloWorld3 -protocol socket_ssl -plugin/socket_ssl/port 7609 -plugin/socket_ssl/SSL true
                 -plugin/socket_ssl/trustStore testStore

The client side xmlBlaster.properties entries 'socket_ssl' are in fact optional, this would work as well: java HelloWorld3 -protocol SOCKET -plugin/socket/port 7609 -plugin/socket/SSL true -plugin/socket/trustStore testStore

Notes

  • An xmlBlaster server instance can have multiple different SSL SOCKET listeners established, all of them reuse the same keystore. You can't use more than one keystore in the same JVM, the first loaded keystore is used even if you specifiy another keystore before creating the second socket listener.
  • The above examples clients used the server side 'keystore' file which is a bad idea as this file contains besides the certificate the servers private key. To avoid copying the server private key to the clients host you can generate a certificate file which only contains the public certificate:

    Export the certificate

    keytool -alias xmlBlaster -export -keystore testStore -rfc -file xmlBlasterTrustStore.Cert

    Create a 'xmlBlaster.truststore' file to be used by clients

    keytool -import -alias xmlBlasterClient -file xmlBlasterTrustStore.Cert -keystore xmlBlasterClient.truststore

    and start a demo client:

    java HelloWorld3 -protocol SOCKET -plugin/socket/SSL true -plugin/socket/trustStore xmlBlasterClient.truststore -plugin/socket/port 7609

Example
Java

Configuring compression

The xmlBlaster SOCKET protocol supports compression with zlib and jzlib. Compression support is available for C, C++ and Java clients directly and for ActiveX (C#, VisualBasic .net) and Javascript clients via the Java bridge. You can switch on two compression modes with the property plugin/socket/compress/type. If the server side socket plugin has the option zlib:stream enabled (see xmlBlasterPlugins.xml) it won't accept uncompressed clients. If you have both types of clients you need to register two SOCKET protocol driver in xmlBlasterPlugins.xml.

Note that the zlib setting compresses block wise and violates the described SOCKET protocol format, it adds a prefix to the message format. A first byte at the beginning, the compressionFlag, where '1' is zlib compressed and '0' is uncompressed. This is followed by 4 bytes which contain the length of the uncompressed message. If compressionFlag==1, there are another 4 bytes which contain the compressed length. See ZBlockOutputStream.java:86 for more details.

For a simple usage in this test we set following parameters in xmlBlaster.properties 

protocol=SOCKET

# No compression
#plugin/socket/compress/type=

# Compress each message separately (available only for Java clients)
#plugin/socket/compress/type=zlib

# Compress in streaming mode (the preferred way, C, C++, Java ... clients)
plugin/socket/compress/type=zlib:stream

We start now a server and a client instance, the client publishes 10 messages with identical content consisting of one thousand 'X' characters: 

java org.xmlBlaster.Main

java javaclients.HelloWorldPublish -numPublish 10 -contentSize 1000

If we now restart the client and server for each compression mode and add a socket port forwarder which dumps the transferred bytes we get this result:

Compression modeMessage NoSize of published message [bytes]Size of PublishReturnQos (ACK)
no compression11505196
21356196
31356196
zlib1347163
2276172
3275164
4276163
5275163
zlib:stream127676
22817
32117
42217
52216

For no compression you can see that the first message overhead is 505 bytes (1505 bytes - 1000 payload) because we have delivered the topic QoS on first publish. It than reduces to constantly 356 bytes for each published message. The payload (your message content) is 1000 bytes. The 356 bytes are mostly due to the used publish QoS settings.

Compressing each message as a unit with zlib reduces the message size to 276 bytes. The compression header adds overhead for each message.

Compressing messages with mode zlib:stream reduces the transferred size drastically to 22 bytes per message. The compression header is not transferred again.

Note:

This result is a very optimistic case as the message content consisted of one thousand 'X' characters. In your real day messages the compression rate will be less and depends on your payload.

Compression of SSL connections

contentSize=1000

Compression modeMessage NoSize of published message [bytes]Size of PublishReturnQos (ACK)
no compression11526217
21377217
31377217
zlib:stream129496
24938
34337
44338

contentSize=10000

Compression modeMessage NoSize of published message [bytes]Size of PublishReturnQos (ACK)
no compression110527217
210378217
310378217
zlib:stream132197
26938
36036
45937
56037

Again the results for compression of SSL messages are very promising.

Try a C (or C++) client

Download zlib at http://www.gzip.org/zlib/ and edit build.properties to set the zlib pathes, finally compile it with 'build c'. Now you are ready to try: 

  HelloWorld3 -plugin/socket/compress/type zlib:stream -plugin/socket/port 7607

Compile the C++ examples with 'build cpp' and try: 

  PublishDemo -protocol SOCKET -plugin/socket/compress/type zlib:stream 
              -plugin/socket/port 7607 -numPublish 10 -contentSize 10000
Example
Java

Send xmlBlaster scripts over the socket

It is possible to send other formats over the socket connection. The data format described in this requirement is coded in the XbfParser.java class. You can however choose to use the XmlScriptParser.java markup to be send (or any other format which may you code yourself). See the requirement client.script how this markup looks like. It is for example used as the default in the EMAIL protocol plugin.

Here is an example how to switch to scripting markup send over the socket: 

#xmlBlaster.properties (server side)

CbProtocolPlugin[socket_script][1.0]=org.xmlBlaster.protocol.socket.CallbackSocketDriver,\
                             compress/type=,\
                             isNullTerminated=true,\
                             parserClass=org.xmlBlaster.util.xbformat.XmlScriptParser

#xmlBlasterPlugins.xml

<plugin create='true' id='socket_script' className='org.xmlBlaster.protocol.socket.SocketDriver'>
   <action do='LOAD' onStartupRunlevel='4' sequence='20'
            onFail='resource.configuration.pluginFailed'/>
   <action do='STOP' onShutdownRunlevel='3' sequence='50'/>
   <attribute id='compress/type'></attribute>
   <attribute id='isNullTerminated'>true</attribute>
   <attribute id='parserClass'>org.xmlBlaster.util.xbformat.XmlScriptParser</attribute>
   <attribute id='port'>7601</attribute>
</plugin>

and on client side:

#xmlBlaster.properties (client side)

ClientProtocolPlugin[socket_script][1.0]=org.xmlBlaster.client.protocol.socket.SocketConnection,\
                             compress/type=,\
                             isNullTerminated=true,\
                             parserClass=org.xmlBlaster.util.xbformat.XmlScriptParser


ClientCbServerProtocolPlugin[socket_script][1.0]=org.xmlBlaster.client.protocol.socket.SocketCallbackImpl,\
                             compress/type=,\
                             isNullTerminated=true,\
                             parserClass=org.xmlBlaster.util.xbformat.XmlScriptParser

Please note that you have to pass the parserClass (the same used for EMAIL) and additionally the isNullTerminated=true configuration.

To send the script compressed over the wire please use the compress/type=zlib:stream setting.

You can switch on dumping of the send and received messages with the following logging configuration used on command line: 

-logging/org.xmlBlaster.util.xbformat.XmlScriptParser FINEST
-logging/org.xmlBlaster.util.protocol.socket.SocketExecutor FINEST

which results in a typical logging output like:

02.07.2006 22:58:45 FINEST  10-main SocketExecutor sendMessage: Sending TCP data 
[<?xml version='1.0' encoding='UTF-8'?>

<publish sessionId='sessionId:127.0.0.2-null-1151873723867' requestId='name:115187001' type='I'>

 <qos>
  <subscribable/>
  <expiration lifeTime='-1' forceDestroy='false'/>
  <persistent/>
  <forceUpdate/>
  <isPublish/>
 </qos>

 <key oid='Woodlogging' contentMime='text/xml' contentMimeExtended='1.0' domain='greenwood'>
  <org.xmlBlaster><demo-2/></org.xmlBlaster>
 </key>
  <content type='String'>Hi-2</content>
</publish>
]
02.07.2006 22:58:45  FINE   10-main SocketExecutor sendMessage: TCP data is send
02.07.2006 22:58:45 FINEST  11-XmlBlaster.SOCKET XmlScriptParser parse: Got script
[<?xml version='1.0' encoding='UTF-8'?>

<publish sessionId='sessionId:127.0.0.2-null-1151873723867' requestId='name:115187001' type='R'>

 <qos>
  <key oid='Woodlogging'/>
  <rcvTimestamp nanos='1151873925214000000'/>
 <isPublish/>
 </qos>
</publish>
]

With above configuration a typical command line setting to test the setup is:

java org.xmlBlaster.Main -logging/org.xmlBlaster.util.xbformat.XmlScriptParser FINEST -logging/org.xmlBlaster.util.protocol.socket.SocketExecutor FINEST 
java HelloWorld3 -protocol socket_script -plugin/socket_script/port 7601
Configure

Server side configuration

Note: If you have additional SOCKET plugins registered, you need to replace socket with the name you gave to your plugin, for example socket_ssl, and the property would be for example plugin/socket_ssl/compress/type=zlib:stream.

Note: If you configure a property in xmlBlasterPlugins.xml the scope is already inside the specific plugin and you need to leave away the prefix plugin/socket and for example directly write responseTimeout.
On command line or in xmlBlaster.properties however, the scope is global and you need to write the complete name like plugin/socket_ssl/responseTimeout.

Property Default / Example Description Impl
plugin/socket/hostname localhost Specify a hostname where the SOCKET server runs yes
plugin/socket/port 7607 The SOCKET server port yes
plugin/socket/localHostname localhost The local address the socket is bound to. Usually this is dynamically choosen by your operating system and you don't need to specify it. yes
plugin/socket/localPort 8900 The local port the socket is bound to. Default is -1 and the operating system chooses an arbitrary port. yes
plugin/socket/startUdpListener false Start a UDP datagram listener socket on server side yes
plugin/socket/useUdpForOneway false When configured to true the updateOneway() callback will be send as UDP datagram. UDP does not guarantee delivery or correct sequence but has a significant smaller latency. yes
plugin/socket/updateResponseTimeout forever When the update() callback method is invoked we wait the given time [milli-seconds] on a response, the value must be bigger than zero, use Integer.MAX_VALUE for an unlimited setting.
The response is the return value or an exception for method invocations which are not marked oneway.
On timeout an exception is thrown which leads on server side to a dead message (depending on the installed error handler). 		yes
plugin/socket/pingResponseTimeout 60000 When the ping() method is invoked we wait the given time [milli-seconds] on a response, the value must be bigger than zero, it defaults to one minute.
The response is the return value or an exception for method invocations which are not marked oneway.
On timeout an exception is thrown which leads on server side to a dead message (depending on the installed error handler). 		yes
plugin/socket/SoTimeout 0 How long we max. block on InputStream.read(). Please leave this value 0, as we should block on input stream indefinitely to receive a new message. yes
plugin/socket/SoLingerTimeout 0 If the socket is closed, how long shall we try to deliver unsent data from the socket stack. Please leave this value 0, as other settings could block the socket close() operation in the kernel (usually the timeout is 10-20 minutes, and your specific setting is ignored). yes
plugin/socket/backlog 50 Socket queue size for incoming connection request yes
plugin/socket/threadPrio NORM_PRIORITY = 5 The priority 1=min - 10=max of the listener thread yes
plugin/socket/SSL false true enables SSL support on server or client socket. If the server side plugin has switched on SSL it will accept only SSL clients. To have SSL and non-SSL SOCKET connections you need to register two SOCKET plugins in xmlBlasterPlugins.xml which listen on different ports, for details see the example section. yes
plugin/socket/needClientAuth false Set to 'true' if the client needs to be authenticated by the server. In such a case you need to add the clients public key to the servers trustStore. yes
plugin/socket/keyStore '' The path of your SSL keystore file containing the private key. This option is needed for every server or client instance containing its private key. You can specify an absolute path like /tmp/myKeyStore or a relative name like myKeyStore, in the latter example the current directory is checked. yes
plugin/socket/keyStorePassword '' The password of your keystore file. yes
plugin/socket/trustStore '' The path of your SSL truststore or keystore file containing the remote certificate. This option is needed on server side if you want to connect two xmlBlaster cluster nodes via SSL SOCKET. The xmlBlaster server is simultaneously a SLL SOCKET client and connects to the remote node. To do this the certificate of the remote node must be imported to the local keystore file or to a separate certificate store. Add this name here. yes
plugin/socket/trustStorePassword '' The password of your keystore file. If none is found we fall back to the server side plugin/socket/keyStorePassword setting if set. yes
plugin/socket/compress/type '' Valid values are:
  • '' disables compression (default)
  • 'zlib:stream' compresses whole stream
  • 'zlib' only compresses flushed chunks bigger than 'compress/minSize' bytes
 yes
plugin/socket/compress/minSize 0 Compress message bigger than given bytes, see above yes
parserClass org.xmlBlaster.util.xbformat.XbfParser The default chooses the above described formatting over socket. It is however possible to force the xmlBlaster scripting markup to be send directly over the socket wire, each script needs to be ended by one zero byte, please set parserClass=org.xmlBlaster.util.xbformat.XmlScriptParser and isNullTerminated=true in this case. yes
isNullTerminated false This setting is only useful if you switch to xmlBlaster scripting markup (see 'parserClass' setting). In this case you need to set isNullTerminated=true to get a zero byte between the script messages sent over the socket. yes
dump[socket] false true switches message dump on yes

Additional client side configuration

The Java socket implementation on client side supports the same properties as the server (we reuse the same implementation). You need to add the "dispatch/callback/" or "dispatch/connection/" prefix to the property key.
You have these additional features on client side:

Property Default Description Impl
dispatch/callback/plugin/
socket/multiThreaded		 true
  • true: Incoming callback requests (the update() method) are dispatched to one thread per request.
    This avoids deadlocks if you call recursively the server - calling for example in the update() thread a publish() or subscribe() would otherwise deadlock (publishOneway() is OK).
    Note that oneway message updates (method updateOneway()) are not guaranteed to be in sequence, since one thread on client side may overtake another one.
    The update() variant with return value is still guaranteed to keep the sequence since xmlBlaster on server side uses exactly one thread per client to callback.
  • false: There is only one thread for callbacks on client side, this guarantees that even your updateOneway() method receives the messages in strict order.
    On the other hand you can't call any non-oneway xmlBlaster method in the update() body since this would deadlock.
yes
dispatch/callback/plugin/
socket/invokerThreadPrio		 NORM_PRIORITY = 5 The priority of the client side callback thread which calls your update method. yes
dispatch/callback/plugin/
socket/threadPrio		 NORM_PRIORITY = 5 The priority 1=min - 10=max of the client side callback server listener thread yes
plugin/socket/responseTimeout forever When methods like connect(), publish, subscribe etc. is invoked we wait the given time [milli-seconds] on a response, the value must be bigger than zero, use Integer.MAX_VALUE for an unlimited setting.
The response is the return value or an exception for method invocations which are not marked oneway.
On timeout an exception is thrown which is forwarded to your client code. 		yes
plugin/socket/trustStore '' The path of your SSL keystore file. Use the java utility keytool. If none is found we fall back to the server side plugin/socket/keyStore setting if set. yes
plugin/socket/trustStorePassword '' The password of your keystore file. If none is found we fall back to the server side plugin/socket/keyStorePassword setting if set. yes
plugin/socket/findStoreInXmlBlasterSearchPath false The default lookup of the keyStore and trustStore files is directly on the harddisk with the name given. Switching to true enables the xmlBlaster lookup strategy as described in requirement util.property.
Note:This feature is only available for JDK 1.4 and above. The xmlBlaster relase 1.0 has not enabled it since it needs to support JDK 1.3, please recompile xmlBlaster with 'build -Dneed.JDK.14=true clean all' to have this feature.
Note:This flag is currently only available on java client side (for example for WebStart clients containing the keyStore/trustStore in a jar file and accessing it via the CLASSPATH). 		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.

Todo
  1. Currently the server has implemented a one thread/client approach. This doesn't scale very well with thousands of clients - we need to code another SOCKET protocol plugin based on the non-blocking nio framework since JDK 1.4 (http://java.sun.com/developer/technicalArticles/releases/nio/).

Note on UDP datagram usage

Each network in the Internet is characterised by a Maximum Transmission Unit (MTU), which defines the largest datagram which can be sent on that network. Whilst the total length of a datagram can (in theory) be up to 64 KB, "real world" MTU limits usually mean datagrams are smaller 1500 bytes in total length.

Currently we have configured MAX_PACKET_SIZE = 10*1024
See REQ protocol
See REQ client.c.socket
See REQ client.cpp.socket
See API org.xmlBlaster.protocol.util.xbformat.Parser
See API org.xmlBlaster.protocol.socket.SocketDriver
See API org.xmlBlaster.protocol.socket.SocketUrl
See CODE socket/XmlBlasterAccessUnparsed.c
See SSL tutorial
See SSL reference guide
See Java compression jzlib
See C compression zlib
See xmlBlasterPlugins.xml
See xmlBlaster.properties

This page is generated from the requirement XML file xmlBlaster/doc/requirements/protocol.socket.xml

Back to overview