Documentation

Quick install

With Maven

Add repository and dependencies on stateless filter :

<repository>
	<id>statelessfilter-repository</id>
	<name>Stateless Filter repository</name>
	<url>http://statelessfilter.sourceforge.net/maven2/repository</url>
</repository>

(...)

<dependency>
	<groupId>net.sourceforge.statelessfilter</groupId>
	<artifactId>stateless-core</artifactId>
	<version>0.4</version>
	<type>jar</type>
	<scope>compile</scope>
</dependency>
<dependency>
	<groupId>net.sourceforge.statelessfilter</groupId>
	<artifactId>stateless-cookie-plain</artifactId>
	<version>0.4</version>
	<type>jar</type>
	<scope>compile</scope>
</dependency>

SLF4J is used for logging. If you don't already use it, add slf4j-simple for console output.

<dependency>
	<groupId>org.slf4j</groupId>
	<artifactId>slf4j-simple</artifactId>
	<version>1.5.8</version>
	<type>jar</type>
	<scope>compile</scope>
</dependency>

Add the filter as the FIRST filter of your application in WEB-INF/web.xml

<filter>
    <filter-name>session</filter-name>
    <filter-class>net.sourceforge.statelessfilter.filter.StatelessFilter</filter-class>
</filter>
    
(...)
    
<filter-mapping>
    <filter-name>session</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Done. Just restart and test your application

Without Maven

Drop stateless filter jars and dependencies in WEB-INF/lib :

  • stateless-core-0.4.jar
  • stateless-plaincookie-0.4.jar
  • slf4j-api-1.5.8.jar
  • commons-lang-2.4.jar
  • commons-codec-1.4.jar
  • commons-collections-3.2.1.jar
  • commons-io-1.4.jar

SLF4J is used for logging. If you don't already use it, drop slf4j-simple in WEB-INF/lib for console output.

  • slf4j-simple-1.5.8.jar

Add the filter as the FIRST filter of your application in WEB-INF/web.xml

<filter>
    <filter-name>session</filter-name>
    <filter-class>net.sourceforge.statelessfilter.filter.StatelessFilter</filter-class>
</filter>
    
(...)
    
<filter-mapping>
    <filter-name>session</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Done. Just restart and test your application

Configuration

The stateless filter can use one are several backends for session storage. Select the ones you need (and only these) and add them to your project. On application startup, you should see the initialization of each backend. Most backends need additional configuration and will fail on startup if unconfigured. See bellow.

Backend Id
stateless-session session
stateless-memcache memcache
stateless-cookie-plain plaincookie
stateless-cookie-aes aescookie
stateless-cookie-aes-json jsonaescookie

Configuration used a file named stateless.properties which must be located at the root of the classpath.

		# Sample configuration
		default=memcache
		dirtycheck=true

		#Attribute mappings
		attribute.userid=memcache
		attribute.basket=aescookie

		#Memcache configuration
		memcache.server1=localhost:11211

		#AEScookie configuration
		aescookie.cookiename=es
		aescookie.compress=true
		aescookie.key=bW9uc3VwZXJwYXNzd29yZA==
		aescookie.iv=emVhdWdyZXppcnnpInDnIXJ5YmZ6IuchJybnISc=

		#Plain cookie configuration
		plaincookie.compress=true
Component Attribute Value Default Description
Core default <backend-id> First detected backend Set the default backend for session attributes. For each attribute, if no specific mapping is defined, this backend will be used.
Core dirtycheck true/false false Only process the session if the data was updated (Major performance boost). Updates are only detected if a WRITE operation was used on the session object. You MUST call setAttribute each time an object is updated or changes will be ignored.
Core attribute.<attribute-name> <backend-id> none Maps a specific attribute to a backend. Allows to split the session into several stores.
Plain cookie plaincookie.cookiename <cookie-name> s Set the name of the cookie
Plain cookie plaincookie.cookiepath <cookie-path> Use application default Set the path of the cookie
Plain cookie plaincookie.cookiedomain <cookie-domain> Use application default Set the domain of the cookie
Plain cookie plaincookie.cookiemaxage <cookie-max-age-integer> -1 Set the max age of a cookie. -1 = session cookie.
Plain cookie plaincookie.compress true/false true Enables data compression
AES cookie aescookie.cookiename <cookie-name> es Set the name of the cookie
AES cookie aescookie.cookiepath <cookie-path> Use application default Set the path of the cookie
AES cookie aescookie.cookiedomain <cookie-domain> Use application default Set the domain of the cookie
AES cookie aescookie.cookiemaxage <cookie-max-age-integer> -1 Set the max age of a cookie. -1 = session cookie.
AES cookie aescookie.compress true/false true Enables data compression
AES cookie aescookie.key <secret-key-base64> none The secret key used for encryption, Base64 encoded. Only the first 16 chars are used (128bit).
AES cookie aescookie.iv <iv-base64> none The initialization vector used for encryption, Base64 encoded. Only the first 16 chars are used (128bit).
Memcache memcache.cookiename <cookie-name> mid Set the name of the cookie used to track session id.
Memcache memcache.cookiepath <cookie-path> Use application default Set the path of the cookie
Memcache memcache.cookiedomain <cookie-domain> Use application default Set the domain of the cookie
Memcache memcache.cookiemaxage <cookie-max-age-integer> -1 Set the max age of a cookie. -1 = session cookie.
Memcache memcache.serverN <host:port> localhost:11211 Register a memcache server. N from 1 to X

You can avoid filtering for specific request path by adding a set of regular expression in the filter's init parameter section. For instance, if you want to avoid static resources filtering. The init parameter name should be : excludePatternList.

<filter>
    <filter-name>session</filter-name>
    <filter-class>net.sourceforge.statelessfilter.filter.StatelessFilter</filter-class>
    <init-param>
	    <param-name>excludePatternList</param-name>
	    <param-value>^/.*\.js$,^/.*\.css$</param-value>
    </init-param>
</filter>
    
(...)
    
<filter-mapping>
    <filter-name>session</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>