BotDetect Java CAPTCHA Web API Reference

To make Captcha integration into Java websites easy, the BotDetect Java CAPTCHA Library exposes a public API focused on ease of use from JSP forms.

com.captcha.botdetect.servlet.Captcha

Instances of Captcha type can be created on your forms and will take care of Captcha display and validation. Captcha object is also implicitly created by BotDetect Captcha Custom Tag.

Captcha Class Reference
Captcha public method Captcha
  • String captchaId
  • ICaptchaConfiguration captchaConfiguration
  • CaptchaPersistence captchaPersistence
The Captcha constructor takes the Captcha identifier (e.g. "registrationCaptcha"), ICaptchaConfiguration object, and CaptchaPersistence object as parameters
Captcha public method boolean validate Validate the Captcha from a server-side call, using values automatically read from the current request
Captcha public method boolean validate
  • String userInput
Validate the Captcha from a server-side call, using the specified user input and the instanceId automatically propagated using a hidden field
Captcha public method boolean validate
  • String userInput
  • String instanceId
Validate the Captcha from a server-side call, using the specified user input and instanceId. Used when automatic hidden field propagation doesn't work
Captcha public method static boolean validate
  • ServletRequest request
  • String captchaId
  • String userInput
  • String instanceId
Validate the Captcha from a server-side call, specifying all validation parameters. Used in cases when a Captcha object instance is not available
Captcha public method boolean ajaxValidate Validate the Captcha from an Ajax call, using values automatically read from the current request
Captcha public method boolean ajaxValidate
  • String userInput
Validate the Captcha from an Ajax call, using the specified user input and the instanceId automatically propagated using a hidden field
Captcha public method boolean ajaxValidate
  • String userInput
  • String instanceId
Validate the Captcha from an Ajax call, using the specified user input and instanceId. Used when automatic hidden field propagation doesn't work
Captcha public method static boolean ajaxValidate
  • ServletRequest request
  • String captchaId
  • String userInput
  • String instanceId
Validate the Captcha from an Ajax call, specifying all validation parameters. Used in cases when a Captcha object instance is not available
Captcha public method static Captcha load
  • ServletRequest reqeust
  • String captchaId
Loads the Captcha instance stored with the given captchaId
Captcha public method void load
  • Captcha captcha
Updates the Captcha instance according to state persisted for its captchaId value
Captcha public method void save
  • Captcha captcha
Saves necessary state from the given Captcha instance
Captcha public method void saveCaptchaCodes
  • Captcha captcha
Saves only updated code information from the given Captcha instance
Captcha public property string get/set UserInputID Captcha user input textbox identifier used for all server-side and client-side user input processing. The default value is empty (must be set for each Captcha individually). Valid user Captcha user input id setting values are strings corresponding to the Html identifier of the Captcha code input control on the form. Each Captcha instance should have an associated user input control
Captcha public property int get/set CodeLength Length (number of characters) of the Captcha code rendered; the default value is between 4 and 6
Captcha public property CodeStyle get/set CodeStyle Code style, i.e. the algorithm used to generate Captcha codes; the default value is ALPHANUMERIC
Captcha public method void setDisallowedCodeSubstringsCsv
  • String disallowedCodeSubstrings
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.)
Captcha public method void setDisallowedCodeSubstringsList
  • List<String> disallowedCodeSubstrings
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.)
Captcha 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
Captcha public property List<ImageStyle> get/set ImageStyle Image style, i.e. the algorithm used to render Captcha codes in images; if no image style is set, it is randomized by default
Captcha public property ImageStyle set ImageStyle Sets an Image style used to render Captcha image
Captcha public property ImageSize get/set ImageSize Size of the Captcha image rendered; the default size is (250, 50)
Captcha public property ImageFormat get/set ImageFormat Image format in which the Captcha image will be rendered; the default format is JPEG
Captcha public property java.awt.Color get/set CustomDarkColor Optional custom dark color point, modifies the color palette used for Captcha image drawing
Captcha public property java.awt.Color get/set CustomLightColor Optional custom light color point, modifies the color palette used for Captcha image drawing
Captcha public property boolean is/set SoundEnabled Is Captcha sound enabled
Captcha public property List<SoundStyle> get/set SoundStyle Sound style, i.e. the algorithm used to pronounce Captcha codes in sounds; if no sound style is set, it is randomized by default
Captcha public property SoundStyle set SoundStyle Sets a Sound style used to generate Captcha sound
Captcha public property SoundFormat get/set SoundFormat Audio format in which the Captcha sound will be generated; the default format is WAV_PCM_16BIT_8KHZ_MONO
Captcha public property SoundRegenerationMode get/set SoundRegenerationMode Sound regeneration mode determining how will multiple consecutive requests for audio Captcha with the same Captcha code be handled by BotDetect; the default mode is LIMITED
Captcha public property String get/set Locale Locale string, affects the character set used for Captcha code generation and the pronunciation language used for Captcha sound generation
Captcha public property String get/set ImageTooltip The Captcha image tooltip can be set for the entire application using web.xml settings; this instance property allows overriding those values dynamically
Captcha public property String get/set SoundTooltip Tooltip of the Captcha sound icon
Captcha public property String get/set ReloadTooltip Tooltip of the Captcha reload icon
Captcha public property String get/set HelpLinkText Text or tooltip of the Captcha help link, depending on help link mode
Captcha public property String get/set HelpLinkUrl Url of the localized Captcha help page the help link points to
Captcha public property boolean is/set ReloadEnabled Is Captcha reloading (changing the Captcha code because the current one is too hard to read) enabled
Captcha public property boolean is/set UseSmallIcons By default, tells is the selected Captcha image height so low that we should switch to smaller icons; can be user-specified to always (or never) use small icons
Captcha public property boolean is/set UseHorizontalIcons By default, tells is the selected Captcha image height so low that we should switch to horizontal icon rendering; can be user-specified to always (or never) switch to the horizontal icon layout
Captcha public property String get/set SoundIconUrl Url of the optional custom Captcha sound icon that will be used instead of the default one
Captcha public property String get/set ReloadIconUrl Url of the optional custom Captcha reload icon that will be used instead of the default one
Captcha public property int get/set IconsDivWidth Calculated width of the Captcha icons <div>, can be user-set to create custom icon layouts
Captcha 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
Captcha public property HelpLinkMode get/set HelpLinkMode How will the Captcha help link be displayed. The default value is TEXT
Captcha public property int get/set TabIndex

Starting tabindex for the Captcha container Html markup elements

There are three keyboard-selectable Captcha markup elements: the Captcha help link, the Captcha sound icon and the Captcha reload icon

Depending on your settings (whether the Captcha help link is enabled, are Captcha sounds enabled, is Captcha reloading enabled), the next available tabindex on the page can be from 0 to 3 greater than this value
Captcha public property String get/set AdditionalCssClasses User-defined CSS classes that will be added to the BotDetect CAPTCHA container
Captcha public property String get/set AdditionalInlineCss User-defined CSS style declarations that will be added as inline style of the BotDetect CAPTCHA container
Captcha public property boolean is/set AddCssInclude Should the BotDetect layout stylesheet be included by the generated Captcha container markup
Captcha public property boolean is/set AddScriptInclude Should the BotDetect JavaScript client-side script code be included by the generated Captcha container markup
Captcha public property boolean is/set AddInitScript Should the JavaScript code for BotDetect client-side object creation be included in the generated Captcha container markup
Captcha public property boolean is/set AutoUppercaseInput Should user Captcha code input be automatically uppercased on the fly
Captcha public property boolean is/set AutoFocusInput Should the Captcha code input textbox automatically be assigned focus on all Captcha sound and Captcha reload icon clicks, allowing the users to more easily type in the code as they hear it or as the new image loads
Captcha public property boolean is/set AutoClearInput Should the Captcha user input textbox automatically be cleared on all reload icon clicks and auto-reloads of expired Captcha codes
Captcha public property boolean is/set AutoReloadExpiredCaptchas Should Captcha challenges automatically be reloaded when the Captcha code expires (controlled by the CodeTimeout property)
Captcha public property int get/set AutoReloadTimeout Time period in seconds after which automatic reloading of expired Captcha challenges will cease
Captcha public property int get/set SoundStartDelay Starting delay (in milliseconds) of Captcha audio JavaScript playback. The default value is 0 (no delay)
Captcha public property int get/set RemoteScriptEnabled Should BotDetect also add a remote JavaScript include (remote.captcha.com/include.js) loaded from the captcha.com server (which is currently used only for stats, but is planned to develop into additional Captcha functionality)
Captcha public property String get CaptchaId Unique identifier of the Captcha within the application (for example, if you placed one Captcha on the Registration form and another on the Contact Us form, they would have distinct CaptchaId values)
Captcha public property String get CurrentInstanceId Globally unique identifier of the current Captcha object instance, used to ensure each page load keeps separate Captcha codes, for example when opening the same form in multiple browser tabs
Captcha public method boolean isCaptchaSoundAvailable Are Captcha sounds for the current Locale available
Captcha public method boolean isSoundPackageMissing Is the BotDetect pronunciation sound package for the current Locale missing
Captcha public method boolean isRenderIcons Should the icons be rendered (true if at least one of the icons will be rendered)
Captcha public method int getTotalWidth Calculated width of the Captcha container <div>, based on Captcha image width and should the icons be rendered or not
Captcha public method int getTotalHeight Calculated height of the Captcha container <div>, based on Captcha image height
Captcha public method String getScriptIncludeMarkup BotDetect script include fragment, including script tags
Captcha public method String getInitScriptMarkup BotDetect client-side initialization function
Captcha public property ICaptchaUrlGenerator get/set UrlGenerator Instead of accessing the CaptchaUrls helper directly, we encapsulate the access through a field, so switching between relative and absolute urls can be done per Captcha instance
Captcha public method String getCaptchaImageUrl Url of Captcha image generated for the current control instance
Captcha public method String getCaptchaSoundUrl Url of Captcha sound generated for the current control instance
Captcha public method String getImageClientId Client-side ID of the <img> element used for Captcha images
Captcha public method String getAudioPlaceholderClientId Client-side ID of the empty placeholder <div> used for Captcha sound playback
Captcha public method String getValidatingInstanceKey Name of the hidden field used to pass InstanceId between postbacks
Captcha public method String getValidatingInstanceId InstanceId of the previous Captcha instance that is being submitted, set only if IsSubmit is true
Captcha public method String getHtml Creates the Html markup that serves as a container for Captcha challenges (images and sounds)
Captcha public method String getLibInfo Debug function for getting current BotDetect version and running Java version

com.captcha.botdetect.jsf.JsfCaptcha

Intended to be used with JavaServer Faces. Extends UIComponentBase so it is easy to add it to your form while binding with JSF managed bean's property allows more dynamic control of Captcha object.

JsfCaptcha Class Reference
JsfCaptcha class public constructor JsfCaptcha The JsfCaptcha constructor has no parameters because id is assigned through attribute value on the page
JsfCaptcha class public method boolean validate
  • String userInput
Validates the Captcha, comparing the user input to the Captcha code stored on the server. Each randomly generated Captcha code can only be validated once, regardless of the validation result
JsfCaptcha public method void setCodeLength
  • int length
Length (number of characters) of the Captcha code rendered; the default value is between 4 and 6
JsfCaptcha public method void setUserInputID
  • String inputID
Captcha user input textbox identifier used for all server-side and client-side user input processing
JsfCaptcha public method void setCodeStyle
  • String style
Code style, i.e. the algorithm used to generate Captcha codes; the default value is ALPHANUMERIC
JsfCaptcha public method void setCodeTimeout
  • int seconds
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
JsfCaptcha public method void setDisallowedCodeSubstrings
  • String disallowedCodeSubstrings
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.)
JsfCaptcha public method void setImageStyle
  • String style
Image style, i.e. the algorithm used to render Captcha codes in images; if no image style is set, it is randomized by default.
JsfCaptcha public method void setImageFormat
  • String format
Image format in which the Captcha image will be rendered; the default format is JPEG.
JsfCaptcha public method void setImageWidth
  • int width
Width of the Captcha image rendered; the default width is 250 pixels.
JsfCaptcha public method void setImageHeight
  • int height
Height of the Captcha image rendered; the default height is 50 pixels.
JsfCaptcha public method void setCustomLightColor
  • String color
Optional custom light color point, modifies the color palette used for Captcha image drawing
JsfCaptcha public method void setCustomDarkColor
  • String color
Optional custom dark color point, modifies the color palette used for Captcha image drawing
JsfCaptcha public method void setSoundEnabled
  • boolean enabled
Sets whether Captcha sound is enabled is the sound icon and related code added to Captcha markup). Default is true.
JsfCaptcha public method void setSoundStyle
  • String style
Sound style, i.e. the algorithm used to generate sound; if no image style is set, it is randomized by default.
JsfCaptcha public method void setSoundFormat
  • String format
Sound format in which the Captcha image will be rendered; the default format is JPEG.
JsfCaptcha public method void setSoundRegenerationMode
  • String mode
Sound regeneration mode determining how will multiple consecutive requests for audio Captcha with the same Captcha code be handled by BotDetect; the default mode is LIMITED
JsfCaptcha public method void setSoundStartDelay
  • int millis
Starting delay (in milliseconds) of Captcha audio JavaScript playback. The default value is 0 (no delay)
JsfCaptcha public method void setLocale
  • String locale
Locale string, affects the character set used for Captcha code generation and the pronunciation language used for Captcha sound generation
JsfCaptcha public method void setHelpLinkEnabled
  • boolean enabled
Will Captcha markup include a link to a Captcha help page providing Captcha instructions and explanations for form users
JsfCaptcha public method void setHelpLinkMode
  • String mode
How will the Captcha help link be displayed. The default value is TEXT
JsfCaptcha public method void setTabIndex
  • int index
Starting tabindex for the Captcha container Html markup elements
JsfCaptcha public method void setImageTooltip
  • String tooltip
The Captcha image tooltip can be set for the entire application using web.xml settings; this instance property allows overriding those values dynamically
JsfCaptcha public method void setSoundTooltip
  • String tooltip
Tooltip of the Captcha sound icon
JsfCaptcha public method void setReloadTooltip
  • String tooltip
Tooltip of the Captcha reload icon
JsfCaptcha public method void setHelpLinkText
  • String text
Text or tooltip of the Captcha help link, depending on help link mode
JsfCaptcha public method void setHelpLinkUrl
  • String url
Url of the localized Captcha help page the help link points to
JsfCaptcha public method void setReloadEnabled
  • boolean enabled
Is Captcha reloading (changing the Captcha code because the current one is too hard to read) enabled
JsfCaptcha public method void setUseSmallIcons
  • boolean enabled
By default, tells is the selected Captcha image height so low that we should switch to smaller icons; can be user-specified to always (or never) use small icons
JsfCaptcha public method void setUseHorizontalIcons
  • boolean enabled
By default, tells is the selected Captcha image height so low that we should switch to horizontal icon rendering; can be user-specified to always (or never) switch to the horizontal icon layout
JsfCaptcha public method void setSoundIconUrl
  • String url
Url of the optional custom Captcha sound icon that will be used instead of the default one
JsfCaptcha public method void setReloadIconUrl
  • String url
Url of the optional custom Captcha reload icon that will be used instead of the default one
JsfCaptcha public method void setIconsDivWidth
  • int width
Calculated width of the Captcha icons <div>, can be user-set to create custom icon layouts
JsfCaptcha public method void setAdditionalCssClasses
  • String cssClasses
User-defined CSS classes that will be added to the BotDetect CAPTCHA container
JsfCaptcha public method void setAdditionalInlineCss
  • String inlineCss
User-defined CSS style declarations that will be added as inline style of the BotDetect CAPTCHA container
JsfCaptcha public method void setAddCssInclude
  • boolean added
Should the BotDetect layout stylesheet be included by the generated Captcha container markup
JsfCaptcha public method void setAddScriptInclude
  • boolean added
Should the BotDetect JavaScript client-side script code be included by the generated Captcha container markup
JsfCaptcha public method void setAddInitScript
  • boolean added
Should the JavaScript code for BotDetect client-side object creation be included in the generated Captcha container markup
JsfCaptcha public method void setAutoFocusInput
  • boolean autoFocus
Should the Captcha code input textbox automatically be assigned focus on all Captcha sound and Captcha reload icon clicks, allowing the users to more easily type in the code as they hear it or as the new image loads
JsfCaptcha public method void setAutoClearInput
  • boolean autoClear
Should the Captcha user input textbox automatically be cleared on all reload icon clicks and auto-reloads of expired Captcha codes
JsfCaptcha public method void setAutoUppercaseInput
  • boolean uppercased
Should user Captcha code input be automatically uppercased on the fly
JsfCaptcha public method void setAutoReloadExpiredCaptchas
  • boolean autoReload
Should Captcha challenges automatically be reloaded when the Captcha code expires (controlled by the CodeTimeout property)
JsfCaptcha public method void setAutoReloadTimeout
  • int seconds
Time period in seconds after which automatic reloading of expired Captcha challenges will cease
JsfCaptcha public method void setRemoteScriptEnabled
  • boolean enabled
Should BotDetect also add a remote JavaScript include (remote.captcha.com/include.js) loaded from the captcha.com server (which is currently used only for stats, but is planned to develop into additional Captcha functionality)

com.captcha.botdetect.web.CaptchaUrls

Encapsulates Captcha Url generation according to current state and configured BotDetect options.

CaptchaUrls Class Reference
CaptchaUrls public method static String getCaptchaImageUrl
  • String captchaId
  • String instanceId
Generates the Captcha image Url with the given parameter values
CaptchaUrls public method static String getCaptchaSoundUrl
  • String captchaId
  • String instanceId
Generates the Captcha sound Url with the given parameter values
CaptchaUrls public method static String getCaptchaValidationResultUrl
  • String captchaId
  • String instanceId
Generates the Captcha Ajax validation result Url with the given parameter values
CaptchaUrls public property static String getDefaultSoundIconUrl Gets the BotDetect sound icon Url
CaptchaUrls public property static String getDefaultReloadIconUrl Gets the BotDetect reload icon Url
CaptchaUrls public method String getSmallIconUrl
  • String iconUrl
Gets the BotDetect small icon Url
CaptchaUrls public method String getDisabledIconUrl
  • String iconUrl
Gets the BotDetect disabled icon Url
CaptchaUrls public property static String getScriptIncludeUrl Gets the BotDetect client-side include Url
CaptchaUrls public property static String getLayoutStyleSheetUrl Gets the BotDetect layout stylesheet Url

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.