Home

This is the main page for Open J2EE Session Cluster, an open source Java filter that will cluster J2EE sessions. At the University of Pennsylvania we are using this to store sessions in AWS (S3 or elasticache), so when auto-scaling occurs, the user will not lose the session. This filter is fail-safe, so if there is a problem persisting the session, or restoring the session, it will catch and log that exception, so the user can just start their session over.

Here is a demo.

OJSC filter flow

Pres

Installation

1. Copy the ojsc.jar and all dependent jars (e.g. AWS client, etc), to WEB-INF/lib
2. Copy the config files (openJ2eeSessionCluster.base.properties, openJ2eeSessionCluster.properties, log4j.properties) to the classpath (e.g. WEB-INF/classes)
3. Configure the config file (new encryption key or file location, AWS credentials, etc)
4. Configure the web.xml filter, e.g.

  <filter>
    <filter-name>OJSC Filter</filter-name>
    <filter-class>org.openJ2eeSessionCluster.filter.OjscFilter</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>OJSC Filter</filter-name>
    <url-pattern>/whatever/servlet</url-pattern>
  </filter-mapping>

TODO

1. Setup the app with autoscaling at AWS and test there
2. Implement Elasticache storage if that is what we want to use
3. Have a daemon that clears up old sessions if S3 (currently it deletes files after a day, maybe that is good enough for now)
4. Limit on how many sessions a user can have? Or how many sessions an application can have?
5. Delete the session information and cookie on logout

Configuration

1. The openJ2eeSessionCluster.base.properties file has all the default config settings
2. The openJ2eeSessionCluster.properties file has all the overlay config information specific to your application and environment. Note, you can have more overlays if you like (e.g. one for application, and one for environment)

# The ojsc config uses Grouper Configuration Overlays (documented on wiki)
# By default the configuration is read from openJ2eeSessionCluster.base.properties
# (which should not be edited), and the openJ2eeSessionCluster.properties overlays
# the base settings.  See the openJ2eeSessionCluster.base.properties for the possible
# settings that can be applied to the openJ2eeSessionCluster.properties

########################################
## Config chaining hierarchy
########################################

# comma separated config files that override each other (files on the right override the left)
# each should start with file: or classpath:
# e.g. classpath:twoFactor.hibernate.base.properties, file:c:/temp/myFile.properties
ojsc.config.hierarchy = classpath:openJ2eeSessionCluster.base.properties, classpath:openJ2eeSessionCluster.properties

# seconds between checking to see if the config files are updated
ojsc.config.secondsBetweenUpdateChecks = 60

########################################
## Security
########################################

# cipher to use for symmetic encryption
ojsc.encryptionCipher = AES/CBC/PKCS5Padding

# secret to use for symmetic encryption, should be length at least 16, and if has slashes,
# it is assumed to be a file name where it should be read from file contents
ojsc.encryptionKey = 

# implement the encryption interface: org.openJ2eeSessionCluster.interfaces.OjscEncryption
ojsc.ojscEncryptionImplementation = org.openJ2eeSessionCluster.logic.OjscDefaultEncryption

# if the secure flag should be set on cookies.  Note, this is an option since there could be SSL off-loading
ojsc.secureCookieFlag = true

#########################################
## Serialization
#########################################

# implement the serialization interface: org.openJ2eeSessionCluster.interfaces.OjscSerialization
# ojsc.ojscSerializationImplementation = org.openJ2eeSessionCluster.logic.OjscJsonSerialization
ojsc.ojscSerializationImplementation = org.openJ2eeSessionCluster.logic.OjscJavaSerialization


#########################################
## Logic
#########################################

# if we should cluster sessions
ojsc.enable = true

# implement the session interface: org.openJ2eeSessionCluster.interfaces.OjscSession
ojsc.ojscSessionImplementation = org.openJ2eeSessionCluster.logic.OjscCookieSession


# implement the session storage interface: org.openJ2eeSessionCluster.interfaces.OjscSessionStorage
ojsc.ojscSessionStorageImplementation = org.openJ2eeSessionCluster.logic.OjscS3SessionStorage

# if the session is older than so many minutes, then dont recover
ojsc.requireSessionPersistedInMinutes = 60

# 1 meg is the largest a session can be
ojsc.maxSessionSizeToPersist = 1000000

# if this many consecutive sessions serialized are too large, then stop storing session altogether for this session
ojsc.maxSessionsTooLarge = 5

#########################################
## S3 settings
#########################################

# bucket name if using S3
ojsc.s3.bucketName = 

# user and pass file for S3
# e.g.
# accessKey=XXXXX
# secretKey=XXXX/XXXXXXX
ojsc.s3.accountFileName = 

Install at Penn

We needed to add the ojsc.jar (and googleDiffMatchPatch.jar), update the aws jar and commons-codec jar.

Setup the configs (3 properties files in hierarchy, base, penn, and localEnv). Add log4j.properties. Add filter in web.xml