JarCastingSession Couchbase Spring Boot Starter
The project is based on:
Spring Session
Spring Data Couchbase
The project supports only Couchbase 4 and higher versions. For more information about Couchbase click here.
Migrating from 1.x.x to 2.x.x
- remove
@EnableCouchbaseHttpSessionannotation - replace
session-couchbase.persistent.couchbaseproperties withspring.couchbasein the application.yml file
Migrating from 2.x.x to 3.x.x
session-couchbase.timeout-in-secondsintproperty in the application.yml file is replaced bysession-couchbase.timeoutDurationproperty
Installing
repositories {
mavenCentral()
}
dependencies {
compile group: 'com.github.mkopylec', name: 'session-couchbase-spring-boot-starter', version: '3.1.1'
}
How to use
Create a Spring Boot web application:
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
Simply use HttpSession interface to control HTTP session. For example:
@Controller
public class SessionController {
@GetMapping("/uri")
public void doSomething(HttpSession session) {
...
}
}
The starter can be used in 2 different modes:
Couchbase backed persistence usage
Configure Couchbase connection in application.yml file using Spring Data Couchbase properties:
spring.couchbase:
bootstrap-hosts: <list_of_couchbase_cluster_hosts>
bucket:
name: <couchbase_bucket_name>
password: <couchbase_bucket_password>
For full list of supported Spring Data Couchbase properties see here.
Using Couchbase backed HTTP session you can share session among multiple web applications in a distributed system. The session will not be destroyed when the web applications will be shut down.
Retrying
By default there is only one attempt to query Couchbase. It is possible to retry the query operation when an error occurs. The number of retries can be controlled in application.yml file:
session-couchbase.persistent.retry.max-attempts: <number of attempts>
The concurrent modification errors: DML Error, possible causes include CAS mismatch or concurrent modificationFailed to perform update can be avoided by increasing the number of maximum attempts.
In-memory usage
Enable in-memory mode in application.yml file:
session-couchbase.in-memory.enabled: true
Using in-memory HTTP session you can not share session among multiple web applications in a distributed. The session is visible only within a single web application instance and will be destroyed when the web application will be shut down.
The mode is useful for integration tests when you don't want to communicate with the real Couchbase server instance.
Namespaces
The starter supports HTTP session namespaces to prevent session attribute's names conflicts in a distributed systems like platforms composed with micro-services. The name of the namespace can be set in application.yml file:
session-couchbase.application-namespace: <application_namespace>
Each web application in a distributed system can have one application namespace under which the application's session attributes are stored. Every web application can also access global session attributes which are visible across the whole distributed system. Two web applications can have the same namespace and therefore access the same session attributes. If two web applications have different namespaces they cannot access each others session attributes.
You can access session attributes in 2 ways, using:
- application namespace - attributes are visible only to instances of the same web application within a distributed system
- global namespace - attributes are visible to all instances of all web applications within a distributed system
To access application namespace attribute just pass an attribute name:
...
@GetMapping("uri")
public void doSomething(HttpSession session) {
String attributeName = "name";
session.setAttribute(attributeName, "value");
session.getAttribute(attributeName);
...
}
To access global attribute create an attribute name using CouchbaseSession.globalAttributeName(...) method:
...
@GetMapping("uri")
public void doSomething(HttpSession session) {
String attributeName = CouchbaseSession.globalAttributeName("name");
session.setAttribute(attributeName, "value");
session.getAttribute(attributeName);
...
}
When changing HTTP session ID every attribute is copied to the new session, no matter what namespace it belongs.
Metrics
By default no metrics are collected. It can be enabled in application.yml file:
session-couchbase.metrics.enabled: true
Metrics are collected using Micrometer. When collecting metrics is enabled a MeterRegistry Spring bean must be created.
Configuration properties list
session-couchbase:
timeout: 30m # HTTP session timeout.
application-namespace: default # HTTP session application namespace under which session data must be stored.
principal-sessions:
enabled: false # Flag for enabling and disabling finding HTTP sessions by principal. Can significantly decrease application performance when enabled.
persistent:
query-consistency: REQUEST_PLUS # N1QL query scan consistency.
retry:
max-attempts: 1 # Maximum number of attempts to repeat a query to Couchbase when an error occurs.
in-memory:
enabled: false # Flag for enabling and disabling in-memory mode.
metrics:
enabled: false # Flag for enabling and disabling metrics collecting.
Examples
Go to sample controller to see more examples.
License
Session Couchbase Spring Boot Starter is published under Apache License 2.0.