Overview

In a load balanced environment the default singleton implementation doesnt work out of the box.

There is two solution in order to achieve captcha validation throught load-balancing

Use a "distributed singleton" implemented with an distributed cache CaptchaStore (like JBossCache)
Use sticky session

The JBossCacheStore allows JCaptcha to be used in a clustered environment, generated captchas are stored in a distributed Cache. A user can now retrieve a captcha from a node and validate it on another node.

This tutorial shows how to set up the JCaptcha extension and configure JBossCache

Add project dependencies

jcaptcha-extension-jbosscache-store v1.0 supports JBossCache 2.x
jcaptcha-extension-jbosscache-store v2.x supports JBossCache 3.x

Maven2 users

Add the following dependency to your project POM

<dependency>
	<groupId>com.octo.captcha</groupId>
	<artifactId>jcaptcha-extension-jbosscache-store</artifactId>
	<version> </version>
</dependency>

Without Maven2

Add the following libraries to your project classpath.

The JCaptcha extension
- jcaptcha-extension-jbosscache-store-1.0.jar
JBossCache dependencies
- The JCaptcha extension POM contains names, versions and repository URL to download them.

Configure your CaptchaService with the JBossCacheCaptchaStore

Use for example the GenericManageableCaptchaService and provide a JBossCacheCaptchaStore for the first argument of the constructor.

CaptchaService service = new GenericManageableCaptchaService(
		new JBossCacheCaptchaStore(),
		new GenericCaptchaEngine( /* engine configuration */ ),
		180, // minGuarantedStorageDelayInSeconds
		180000, // maxCaptchaStoreSize
		180000 // captchaStoreLoadBeforeGarbageCollection
	)

The three last arguments are related to the JCaptcha garbage collector. They must be set carefully in order to avoid overhead with JBossCache eviction policy. See the last section for more explanations.

Configure the JBoss Cache

Set the configuration filename

You must provide the JBossCache configuration filename to the JBossCacheCaptchaStore in order to initialize the Cache.

This can be done by adding the jcaptcha.jbosscache.config system property to the JVM.

Add the following argument to the JVM command line or in the JAVA_OPTS environment variable.

-Djcaptcha.jbosscache.config=myCaptchaStoreJBossCacheConfig.xml

Modify the XML configuration file

This configuration is a proposal and has to be adapted to your project requirements. Please refers to the JBossCache reference documentation for further details.

You could find a sample in the extention test resources

The configurations attributes are divided in two main parts, the first one define the cache behavior (transaction, synchronisation, eviction policy) and the second one defines the deployment scheme.

Cache general behavior

The main attributes have to be set with the following values:

<attribute name="NodeLockingScheme">PESSIMISTIC</attribute>
<attribute name="IsolationLevel">REPEATABLE_READ</attribute>
<attribute name="LockParentForChildInsertRemove">false</attribute>
<attribute name="CacheMode">REPL_SYNC</attribute>

In the EvictionPolicyConfig XML node :

<attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute>

Add the captcharegion configuration in the EvictionPolicyConfig XML node

<region name="/captcha">
         <attribute name="maxNodes">5000</attribute>
         <attribute name="timeToLiveSeconds">0</attribute>
         <attribute name="maxAgeSeconds">120</attribute>
       </region>

Parameter coherency guidelines

Follow these rules in order to let JBossCache manage the size of the cache (instead of JCaptcha garbage collector) and use efficiently JBossCache for managing captchas.

Disable JCaptcha garbage collector
- JCaptcha maxCaptchaStoreSize must be set to zero
- JCaptcha minGuarantedStorageDelayInSeconds must be set to zero
- JCaptcha captchaStoreLoadBeforeGarbageCollection must be bigger than JBossCache maxNodes
Disable captchas TimeToLive
- JBossCache timeToLiveSeconds must be set to zero
Configure resolution max time (usually two minutes)
- JBossCache maxAgeSeconds must be less than ten minutes
Manage the CaptchaStore memory size
- JBossCache maxNodes must be set in relation to the JVM memory size parameter (ex : -Xmx256m)

Deployment scheme

Please refers to the JGroups reference documentation for detailed explanations.

Browser not supported