BotDetect Spring 5 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
  • hsqldb.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

a) If Spring is a backend for your js-based frontend, perhaps you should start with a guide that describes integration from js-framework point of view: jQuery, Angular, AngularJS, or React.

b) If you are using Spring forms, here is how to display Captcha in your Spring 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=""%>

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"/>

<input type="text" name="captchaCode" id="captchaCode"/>
<input type="submit" name="submit" label="Submit" id="submit"/>

3. Check User Input During Form Submission

When the form is submitted, the Captcha validation result can be checked in Spring Controller:

import com.captcha.botdetect.web.servlet.SimpleCaptcha;

public class ExampleController {
    @RequestMapping(value = "/validate", method = RequestMethod.POST)
    public ModelAndView onSubmit(HttpServletRequest request, 
                        @Valid @ModelAttribute("example")BasicExample basicExample) 
        // validate the Captcha to check we're not dealing with a bot
        SimpleCaptcha captcha = SimpleCaptcha.load(request, "exampleCaptcha");
        boolean isHuman = captcha.validate(basicExample.getCaptchaCode());
        if (isHuman) {
          basicExample.setCaptchaCorrect("Correct code");
        } else {
          basicExample.setCaptchaIncorrect("Incorrect code");

        return new ModelAndView("example", "basicExample", basicExample);

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 Spring MVC 5 CAPTCHA Instructions and Explanations

Detailed Spring MVC 5 Captcha instructions and explanations can be found in the Spring 5 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.