BotDetect Java CAPTCHA Core API Reference

While the BotDetect Web API members are used for Captcha functionality within a Java web form context (dealing with markup generation and related tasks), the core BotDetect API contains members related to general Captcha functionality, independent of the context it's used for.

com.captcha.botdetect.internal.core.CaptchaBase

A base Captcha object, representing a generic Captcha instance capable of generating Captcha codes, images and sounds + validating user inputs. The Captcha instances tailored for Java form use all delegate core Captcha functionality to a contained CaptchaBase instance.

CaptchaBase Class Reference
CaptchaBase public method CaptchaBase
  • String captchaId
  • ICaptchaConfiguration captchaConfiguration
Captcha identifier, distinguishing multiple Captcha instances within the system. Each Captcha used in a different location must have a unique identifier
CaptchaBase public property String get/set CaptchaId Captcha identifier, distinguishing multiple Captcha instances within the system. Can also be accessed through this property, after being initialized in the constructor
CaptchaBase public property int get/set CodeLength Number of characters in randomly generated Captcha codes (answers to Captcha challenges). The default value is random (4-6 characters)
CaptchaBase public property CodeStyle get/set CodeStyle Character types, used to generate random Captcha codes. The default value is Alphanumeric
CaptchaBase public property String set DisallowedCodeSubstringsCsv Strings that should never occur in randomly generated Captcha codes. Can be both single characters (allows Captcha character set customization) and sequences of two or more characters (useful for swear words filtering, avoiding particular hard-to-read sequences etc.). The default value is empty (Captcha code filtering is optional)
CaptchaBase public property List<String> set DisallowedCodeSubstringsList Strings that should never occur in randomly generated Captcha codes. Can be both single characters (allows Captcha character set customization) and sequences of two or more characters (useful for swear words filtering, avoiding particular hard-to-read sequences etc.). The default value is empty (Captcha code filtering is optional)
CaptchaBase public property int get/set CodeTimeout The time period after random Captcha code generation during which Captcha challenges based on it can be solved: when it expires, even correct inputs will be considered as invalid submissions. The default value is 1200 seconds (20 minutes)
CaptchaBase public property List<ImageStyle> get/set ImageStyle Image style, The BotDetect drawing algorithm used to render Captcha codes in image Captcha challenges. The default value is random (an image style is chosen from all available values for each Captcha image generated)
CaptchaBase public property ImageSize get/set ImageSize Size of Captcha image challenges generated. The default value is 250 x 50 pixels
CaptchaBase public property ImageFormat get/set ImageFormat Image format in which Captcha images will be generated and sent to the client. The default value is Jpeg
CaptchaBase public property java.awt.Color get/set CustomDarkColor Optional custom dark color point, modifies the color palette used for Captcha image drawing
CaptchaBase public property java.awt.Color get/set CustomLightColor Optional custom light color point, modifies the color palette used for Captcha image drawing
CaptchaBase public property boolean is/set SoundEnabled Is Captcha sound enabled. The default value is true
CaptchaBase public property List<SoundStyle>SoundStyle get/set SoundStyle The BotDetect audio generation algorithm used to pronounce Captcha codes in sound Captcha challenges. The default value is random (a sound style is chosen from all available values for each Captcha sound generated)
CaptchaBase public property SoundFormat get/set SoundFormat Audio format Captcha sounds will be generated and sent to the client. The default value is WAV_PCM_16BIT_8KHZ_MONO
CaptchaBase public property SoundRegenerationMode get/set SoundRegenerationMode

How will multiple consecutive requests for audio Captcha with the same Captcha code ('sound regeneration') be handled by BotDetect - a tradeoff of security, usability, and storage requirements. The default value is LIMITED

CaptchaBase public property String get/set Locale Captcha locale string, determining the exact character set used for random Captcha code generation and the pronunciation language used for sound Captcha generation. The default value is en-US
CaptchaBase public property boolean is/set HelpLinkEnabled Will Captcha markup include a link to a Captcha help page providing Captcha instructions and explanations for form users. The default value is true
CaptchaBase public property HelpLinkMode get/set HelpLinkMode How will the Captcha help link be displayed. The default value is TEXT
CaptchaBase public property String get InstanceId Globally unique identifier of the current CaptchaBase object instance
CaptchaBase public property static final String VALID_CAPTCHA_ID The global regular expression object used to validate CaptchaId values and ensure they match the persistence medium key limitations
CaptchaBase public method Code getCode
  • String instanceId
  • CodeGenerationPurpose purpose
Generates a random Captcha code for the given purpose, using settings stored in instance data belonging to the specified instanceId
CaptchaBase public method java.io.ByteArrayOutputStream getImage
  • String instanceId
Generates a Captcha image, using settings stored in instance data belonging to the specified instanceId
CaptchaBase public method java.io.ByteArrayOutputStream getSound
  • String instanceId
Generates a Captcha sound, using settings stored in instance data belonging to the specified instanceId
CaptchaBase public method boolean validate
  • String userInput
  • String instanceId
  • ValidationAttemptOrigin origin
Compares the user input to the Captcha code stored for the given instanceId, using validation rules specified for the current ValidationAttemptOrigin

com.captcha.botdetect.CaptchaRandomization

A helper class used for easy randomization of Captcha parameters.

CaptchaRandomization Class Reference
CaptchaRandomization public method static int getRandomCodeLength Returns a random Captcha code length, using default code length bounds
CaptchaRandomization public method static int getRandomCodeLength
  • int max
Returns a random Captcha code length, using the default minimal value and the specified maximal value
CaptchaRandomization public method static int getRandomCodeLength
  • int min
  • int max
Returns a random Captcha code length, using the specified minimal and maximal values
CaptchaRandomization public method static CodeStyle getRandomCodeStyle
  • CodeStyle... usedValues
Returns a random Captcha code style. Selects from all available styles if no parameter is specified, or from the given value set if specified
CaptchaRandomization public method static ImageStyle getRandomImageStyle Returns a random Captcha image style, using all available styles
CaptchaRandomization public method static ImageStyle getRandomImageStyle
  • List<ImageStyle> usedValues
Returns a random Captcha image style. Selects from the given value set
CaptchaRandomization public method static SoundStyle getRandomSoundStyle Returns a random Captcha sound style, using all available styles
CaptchaRandomization public method static SoundStyle getRandomSoundStyle
  • List<SoundStyle> usedValues
Returns a random Captcha sound style. Selects from the given value set

Please Note

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