You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.

Introduction

The Session Manager is responsible for storing Blueriq Runtime (a.k.a. Aquima) session instances. Blueriq uses a specific session manager depending on the properties that are set. By default there are two types of Blueriq session managers, named "memory" and "external".

In order to run the Blueriq Runtime in a clustered environment, the "external" session manager must be used.

Configure Session Manager

The Session Manager can be configured by placing a property in the application.properties file. The following values may be used for this property:

Memory

The default implementation, which stores Blueriq Runtime sessions only inside the HTTP session that lives inside the application server that Blueriq Runtime is deployed on.

blueriq.session.session-manager=memory

If the property is not set, this implementation is used by default.

External

An implementation which stores Blueriq Runtime sessions in a key-value store using the available IKeyValueStore implementation.

blueriq.session.session-manager=external

 An Key-Value Store Component must be available/enabled in Blueriq Runtime. Look at Key-value store API and default component for more information on how to configure this.

Best practices for creating a custom IKeyValueStore implementation

When creating/using a custom implementation to store the Blueriq Runtime session, it is best to keep in mind some best practices:

  • chain passivation and activation (an object may reference other objects that must also be passivated and activated)
  • when activation occurs, it is best to restore the internal state of an object first and then call activate(ActivationContext) to restore its dependencies
  • always store the minimal needed data only - AquimaSession is passivated and activated per request, a high amount of data transfer can negatively impact general application performance
  • it must be possible to restore the dependencies by calling getters in the ActivationContext parameter

Activate/passivate pattern

Activate/passivate pattern was introduced as a means of enabling the Session Manager to store its AquimaSessions instances in an external key-value store in order to use the Blueriq Runtime in a clustered environment.

The main pattern used is inspired by Enterprise Java Beans. Before the object is serialized, it is notified of this fact by calling its passivate() method. The object then has a chance to do any cleanup before serialization. After the object is deserialized its activate(ActivationContext) method is called. The object then has the chance to restore its dependencies.

passivation
  • occurs before serialization
  • objects have a chance to do any cleanup before serialization
activation
  • occurs after deserialization
  • objects have a chance to restore their transitive dependencies
  • must be possible to restore the dependencies by calling getters in the ActivationContext parameter


Custom Session Manager

Custom implementations of the Session Manager are possible by implementing the IAquimaSessionsMap interface. First, set the blueriq.session.session-manager property to a new value:

blueriq.session.session-manager=example

Then, expose your IAquimaSessionsMap implementation as a conditional Spring bean in the application context:

@Bean
@ConditionalOnProperty(name = BlueriqSessionProperties.SESSION_MANAGER, havingValue = "example")
public IAquimaSessionsMap exampleSessionManager() {
  return new ExampleSessionManager()
}


The Blueriq Runtime will automatically disable the other/default Session Manager implementations and use your custom Session Manager instead.