XmlBlaster Logo

REQUIREMENT

engine.persistence.session

XmlBlaster Logo


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">&lt;![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

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

Back to overview