xmlBlaster - Requirement engine.persistence.session

REQUIREMENT

engine.persistence.session

Type NEW

Priority HIGH

Status CLOSED

Topic XmlBlaster supports sessions and subscriptions which persist a server crash.

Des
cription
Persistent sessions will persist a server crash. After such a crash they are reestablished during the recovery process.
Session persistence is handled together with subscription persistence (subscription persistence would not work without session persistence). The SessionPersistencePlugin takes care of that.

The recovery process must happen before the communication plugins are made available. This to ensure that recovery will be accomplished completely before any client can access xmlBlaster. It also must happen after the TopicHandler is resuscitated. How to ensure this is described in the configuration section below.

A session can either be made persistent explicitly by passing the persistent flag in the connectQos or implicitly when a persistent subscription is made on that session.

The benefit of having persistent sessions is that:

it allows persistent subscriptions

PtP messages will still be delivered to the destination session even if the later has not been able to reconnect yet (for example because the client has crashed too, or because the retry delay is high).

Currently there are some requisites which must be fulfilled to allow a session to be made persistent. These are:

a) The session must be assigned by the client (i.e. he must provide a positive sessionId)

b) The callback connection must be configured as failsafe (to avoid disconnection in cases where the client is inaccessible)

Some of the protocols may be less restrictive than others but if you fulfill the mentioned requisites, session persistency will work on all communication protocols.

Persistence of sessions is ensured by a persistent I_Map implementation. Configuration of the storage (for example storage size or cache size) is done on server side, either by passing parameters on the command line or in the xmlBlaster.properties file.

Exceptions:

When connecting persistently and the storage is overflow, an exception is thrown back to the client.

Making a persistent subscription on a transient session implies that the session is made persistent. If the storage for the persistent sessions is overflown, an exception is thrown back to the client.

When using a negative, generated public session id, for example user/-1 you may encounter a resource leak on hard disk. If the server restarts and the client restarts it will connect with a new generated, negative public session id and won't find its old session anymore. With SOCKET or XMLRPC protocol a client could dump the secret session ID and reuse it on client startup - in this case it would work out fine (no resource leak).
Our CORBA protocol plugin can't handle persistent sessions with a generated, negative public session id, as the CORBA layer is the creator of the secret session id and is creating a new one on each startup.
See client.failsafe about the term 'public session id'.

Once you have made a session persistent and you are reconnecting, the new connection will ignore the persistent flag. Once made persistent, the session will remain persistent.

Example
Java
ConnectQos qos = new ConnectQos(global); qos.setSessionName(new SessionName(global, "fritz/1"); /* sets the session to be persistent */ qos.setPersistent(true); /* sets the callback connection to be failsafe */ CallbackAddress cbAddr = new CallbackAddress(global); cbAddr.setRetries(-1); cbAddress.setPingInterval(-1); cbAddress.setDelay(1000L); qos.addCallbackAddress(cbAddress);

Example
XML
<qos> <securityService type="htpasswd" version="1.0"><![CDATA[ <user>happyUser</user> <passwd>secret</passwd> ]]&bt;</securityService> <persistent/>  <session name='yourName/6' /> <queue relating='connection'> <address pingInterval='0' retries='-1' delay='2000' /> </queue> <queue relating='callback' maxEntries='5' maxEntriesCache='2'> <callback pingInterval='0' retries='-1' delay='1000' /> </queue> </qos>

Configure
The configuration of the plugin happens in the xmlBlasterPlugin.xml file.
 .... <plugin id='subPersistence' className='org.xmlBlaster.engine.SessionPersistencePlugin'> <action do='LOAD' onStartupRunlevel='3' sequence='1' /> <action do='STOP' onShutdownRunlevel='2' sequence='6'/> </plugin> ....
It is important that it is started after runlevel 2 in order to assure that the topics are there when sessions and subscriptions are recovered. The logical place where to do it is on runlevel 3. Since this runlevel is the one on which communication plugins are loaded it is important that subPersistence is loaded before the communication plugins are (by choosing a higher sequence number on load for the communication plugins).
The name subPersitence specified as the plugin id is not important since the plugin registers itself as a listener.

The configuration of the size of the storage
All persistent sessions are stored on the same storage which is configurable on server side (the same way as the msgUnitStore). You can either pass the parameters in the xmlBlaster.properties file:
.... persistence/session/maxEntriesCache = 10 persistence/session/maxEntries = 200 ....
or on the command line when starting xmlBlaster:
java org.xmlBlaster.Main \ -persistence/session/maxEntriesCache 10 \ -persistence/session/maxEntries 200

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
A flag to the ConnectQos must be added for the initial status of the DispatcherManager belonging to this session: 'dispatcherActive'. Additionally, everytime an invocation on SessionInfo.setDispatcherActive(boolean) is done, an update on the DB must be done to ensure the status will be correct when reconnecting after a server crash.

See REQ client.failsafe

See REQ engine.persistence.subscription

See API org.xmlBlaster.engine.I_SessionPersistencePlugin

See TEST org.xmlBlaster.test.client.TestPersistentSession

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

Back to overview

Topic	XmlBlaster supports sessions and subscriptions which persist a server crash.
Des cription	Persistent sessions will persist a server crash. After such a crash they are reestablished during the recovery process. Session persistence is handled together with subscription persistence (subscription persistence would not work without session persistence). The SessionPersistencePlugin takes care of that. The recovery process must happen before the communication plugins are made available. This to ensure that recovery will be accomplished completely before any client can access xmlBlaster. It also must happen after the `TopicHandler` is resuscitated. How to ensure this is described in the configuration section below. A session can either be made persistent explicitly by passing the `persistent` flag in the connectQos or implicitly when a persistent subscription is made on that session. The benefit of having persistent sessions is that: it allows persistent subscriptions PtP messages will still be delivered to the destination session even if the later has not been able to reconnect yet (for example because the client has crashed too, or because the retry delay is high). Currently there are some requisites which must be fulfilled to allow a session to be made persistent. These are: a) The session must be assigned by the client (i.e. he must provide a positive sessionId) b) The callback connection must be configured as failsafe (to avoid disconnection in cases where the client is inaccessible) Some of the protocols may be less restrictive than others but if you fulfill the mentioned requisites, session persistency will work on all communication protocols. Persistence of sessions is ensured by a persistent I_Map implementation. Configuration of the storage (for example storage size or cache size) is done on server side, either by passing parameters on the command line or in the xmlBlaster.properties file. Exceptions: When connecting persistently and the storage is overflow, an exception is thrown back to the client. Making a persistent subscription on a transient session implies that the session is made persistent. If the storage for the persistent sessions is overflown, an exception is thrown back to the client. When using a negative, generated public session id, for example `user/-1` you may encounter a resource leak on hard disk. If the server restarts and the client restarts it will connect with a new generated, negative public session id and won't find its old session anymore. With SOCKET or XMLRPC protocol a client could dump the secret session ID and reuse it on client startup - in this case it would work out fine (no resource leak). Our CORBA protocol plugin can't handle persistent sessions with a generated, negative public session id, as the CORBA layer is the creator of the secret session id and is creating a new one on each startup. See client.failsafe about the term '`public session id`'. Once you have made a session persistent and you are reconnecting, the new connection will ignore the persistent flag. Once made persistent, the session will remain persistent.
Example Java	ConnectQos qos = new ConnectQos(global); qos.setSessionName(new SessionName(global, "fritz/1"); /* sets the session to be persistent / qos.setPersistent(true); / sets the callback connection to be failsafe */ CallbackAddress cbAddr = new CallbackAddress(global); cbAddr.setRetries(-1); cbAddress.setPingInterval(-1); cbAddress.setDelay(1000L); qos.addCallbackAddress(cbAddress);
Example XML	<qos> <securityService type="htpasswd" version="1.0"><![CDATA[ <user>happyUser</user> <passwd>secret</passwd> ]]&bt;</securityService> <persistent/> <!-- same as <persistent>true</persistent> --> <session name='yourName/6' /> <queue relating='connection'> <address pingInterval='0' retries='-1' delay='2000' /> </queue> <queue relating='callback' maxEntries='5' maxEntriesCache='2'> <callback pingInterval='0' retries='-1' delay='1000' /> </queue> </qos>
Configure	The configuration of the plugin happens in the xmlBlasterPlugin.xml file. <!--========== SubscriptionPersistencePlugin =============--> .... <plugin id='subPersistence' className='org.xmlBlaster.engine.SessionPersistencePlugin'> <action do='LOAD' onStartupRunlevel='3' sequence='1' /> <action do='STOP' onShutdownRunlevel='2' sequence='6'/> </plugin> .... It is important that it is started after runlevel 2 in order to assure that the topics are there when sessions and subscriptions are recovered. The logical place where to do it is on runlevel 3. Since this runlevel is the one on which communication plugins are loaded it is important that `subPersistence` is loaded before the communication plugins are (by choosing a higher sequence number on load for the communication plugins). The name `subPersitence` specified as the plugin id is not important since the plugin registers itself as a listener. The configuration of the size of the storage All persistent sessions are stored on the same storage which is configurable on server side (the same way as the msgUnitStore). You can either pass the parameters in the `xmlBlaster.properties` file: .... persistence/session/maxEntriesCache = 10 persistence/session/maxEntries = 200 .... or on the command line when starting xmlBlaster: java org.xmlBlaster.Main \ -persistence/session/maxEntriesCache 10 \ -persistence/session/maxEntries 200 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	A flag to the ConnectQos must be added for the initial status of the DispatcherManager belonging to this session: 'dispatcherActive'. Additionally, everytime an invocation on SessionInfo.setDispatcherActive(boolean) is done, an update on the DB must be done to ensure the status will be correct when reconnecting after a server crash.
See REQ	client.failsafe
See REQ	engine.persistence.subscription
See API	org.xmlBlaster.engine.I_SessionPersistencePlugin
See TEST	org.xmlBlaster.test.client.TestPersistentSession