BotDetect Struts CAPTCHA Integration Quickstart

BotDetect CAPTCHA works in China -- and it does not stalk you around! Read more...

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.4.jar
  • botdetect-servlet-4.0.beta3.4.jar
  • botdetect-jsp20-4.0.beta3.4.jar
  • hsqldb.jar

The hsqldb.jar above is HyperSQL Database library, you can download it at its site.

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

On the very top of the source file for the web form you want to protect against bots, put BotDetect taglib declaration:

<%@taglib prefix="botDetect" uri="https://captcha.com/java/jsp/simple-api"%>

To render Captcha in the form, add the following within <form> you want to protect against bots:

<!-- Adding BotDetect Captcha to the page -->
<botDetect:simpleCaptcha id="exampleCaptcha"/>

<s:textfield name="captchaCode" id="captchaCode"/>
<s:submit name="submit" label="Submit" id="submit"/>

And you also need to add exclude directive for SimpleCaptchaServlet to Struts 2 filter by adding the following in your struts.xml configuration file:

<constant name="struts.action.excludePattern" value="/botdetectcaptcha"/>

3. Check User Input During Form Submission

When the form is submitted, the Captcha validation result must be checked in Struts Action:

[...]
public class BasicCaptchaAction extends ActionSupport {
  
  private String captchaCode;

  public String getCaptchaCode() {
    return captchaCode;
  }

  public void setCaptchaCode(String captchaCode) {
    this.captchaCode = captchaCode;
  }
  
  public String execute() {
    return SUCCESS;
  }
  
  public void validate() {
    SimpleCaptcha captcha = SimpleCaptcha.load(ServletActionContext.getRequest());
    boolean isHuman = captcha.validate(captchaCode);
    if (!isHuman) {
      addFieldError("captchaCode", "Incorrect code");
    }
  }
}

4. Configure your Application

Update your application configuration (web.xml) file.

<servlet>
  <servlet-name>BotDetect Captcha</servlet-name>
  <servlet-class>com.captcha.botdetect.web.servlet.SimpleCaptchaServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>BotDetect Captcha</servlet-name>
  <url-pattern>/botdetectcaptcha</url-pattern>
</servlet-mapping>

5. Configure Captcha options

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

<?xml version="1.0" encoding="UTF-8"?>
<botdetect xmlns="https://captcha.com/schema/java" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://captcha.com/schema/java 
      https://captcha.com/schema/java/botdetect-4.0.beta3.4.xsd">

  <captchaStyles>
    <captchaStyle>
      <name>exampleCaptcha</name>
      <userInputID>captchaCode</userInputID>
      <codeLength>3-5</codeLength>
    </captchaStyle>
  </captchaStyles>

</botdetect>

In-Depth Struts CAPTCHA Instructions and Explanations

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


Please Note

BotDetect Java Captcha Library v4.0.Beta3.4 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.