BotDetect JSF CAPTCHA Integration Quickstart

Unlike Recaptcha the Stalker -- BotDetect CAPTCHA works in China! Licensable source-code; self-hosted -- doesn't stalk -- nor does it slurp your form-data! Think: GDPR & LGPD!

1. Add BotDetect Java CAPTCHA Library Dependency

To manually add BotDetect Captcha library to classpath, copy the following jar files from BotDetect Java download package to application's WEB-INF/lib folder:

  • botdetect-4.0.beta3.5.jar
  • botdetect-servlet-4.0.beta3.5.jar
  • botdetect-jsp20-4.0.beta3.5.jar
  • botdetect-jsf20-4.0.beta3.5.jar
  • hsqldb.jar

In case your application uses JSF 1.2 you will need to copy the botdetect-jsf12-4.0.beta3.5.jar

To share BotDetect Captcha among multiple applications, these BotDetect jar files above should be copied into 'lib' directory of web container or application server's domain.

2. Show a CAPTCHA Challenge on the Form

To protect your JSF form use dedicated simpleJsfCaptcha tag.
Adding simpleJsfCaptcha tag to JSF form is pretty straightforward but there are some differences between standard JSF (.jsp) and Facelets (.xhtml) presentation techologies:

  • declare taglib at the begining of the .jsp file:
  • <%@taglib prefix="botDetect" uri=""%>
  • add attribute prependId="false" to <h:form> opening tag
    this is not mandatory but enables some added functionality to simpleJsfCaptcha tag
  • within the form insert:
  • <h:outputLabel for="captchaCode" 
      value="Retype the characters from the picture:"/>
    <botDetect:simpleJsfCaptcha id="exampleCaptcha" 
    <h:inputText id="captchaCode" value="#{captchaExampleBean.captchaCode}"/>

3. Check User Input During Form Submission

In order to perform CAPTCHA validation simpleJsfCaptcha tag must be bound with the corresponding property of the backing bean. This backing bean property should be of the SimpleJsfCaptcha type, and include both getter and setter access:


import com.captcha.botdetect.web.jsf.SimpleJsfCaptcha;

public class ExampleCaptcha {

  private String captchaCode;
  private SimpleJsfCaptcha captcha;

  public ExampleCaptcha() {

  public String getCaptchaCode() {
    return captchaCode;

  public void setCaptchaCode(String captchaCode) {
    this.captchaCode = captchaCode;

  public SimpleJsfCaptcha getCaptcha() {
    return captcha;

  public void setCaptcha(SimpleJsfCaptcha captcha) {
    this.captcha = captcha;

  public void validate() {
    // validate the Captcha to check we're not dealing with a bot
    boolean isHuman = captcha.validate(captchaCode);

    if (isHuman) {
      // TODO: Captcha validation passed, perform protected action
    } else {
      // TODO: Captcha validation failed, show error message

    this.captchaCode = "";

4. Configure your Application

Update your application configuration (web.xml) file.

  <servlet-name>BotDetect Captcha</servlet-name>
  <servlet-name>BotDetect Captcha</servlet-name>

5. Configure Captcha options

Configure captcha options in WEB-INF/botdetect.xml configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<botdetect xmlns="" 



In-Depth JSF CAPTCHA Instructions and Explanations

Detailed JSF Captcha instructions and explanations can be found in the JSF Captcha integration how to guide.

Please Note

BotDetect Java Captcha Library v4.0.Beta3.5 is an in-progress port of BotDetect 4 Captcha, and we need you to guide our efforts towards a polished product. Please let us know if you encounter any bugs, implementation issues, or a usage scenario you would like to discuss.