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
com.captcha.botdetect.jsf.JsfCaptcha
com.captcha.botdetect.CaptchaUrls

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 String captchaId ICaptchaConfiguration captchaConfiguration CaptchaPersistence captchaPersistence	The Captcha constructor takes the Captcha identifier (e.g. "registrationCaptcha"), ICaptchaConfiguration object, and CaptchaPersistence object as parameters
	boolean validate	Validate the Captcha from a server-side call, using values automatically read from the current request
	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
	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
	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
	boolean ajaxValidate	Validate the Captcha from an Ajax call, using values automatically read from the current request
	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
	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
	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
	static Captcha load ServletRequest request String captchaId	Loads the Captcha instance stored with the given captchaId
	void load Captcha captcha	Updates the Captcha instance according to state persisted for its captchaId value
	void save Captcha captcha	Saves necessary state from the given Captcha instance
	void saveCaptchaCodes Captcha captcha	Saves only updated code information from the given Captcha instance
	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
	int get/set CodeLength	Length (number of characters) of the Captcha code rendered; the default value is between 4 and 6
	CodeStyle get/set CodeStyle	Code style, i.e. the algorithm used to generate Captcha codes; the default value is ALPHANUMERIC
	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.)
	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.)
	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
	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
	ImageStyle set ImageStyle	Sets an Image style used to render Captcha image
	ImageSize get/set ImageSize	Size of the Captcha image rendered; the default size is (250, 50)
	ImageFormat get/set ImageFormat	Image format in which the Captcha image will be rendered; the default format is JPEG
	java.awt.Color get/set CustomDarkColor	Optional custom dark color point, modifies the color palette used for Captcha image drawing
	java.awt.Color get/set CustomLightColor	Optional custom light color point, modifies the color palette used for Captcha image drawing
	boolean is/set SoundEnabled	Is Captcha sound enabled
	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
	SoundStyle set SoundStyle	Sets a Sound style used to generate Captcha sound
	SoundFormat get/set SoundFormat	Audio format in which the Captcha sound will be generated; the default format is WAV_PCM_16BIT_8KHZ_MONO
	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`
	String get/set Locale	Locale string, affects the character set used for Captcha code generation and the pronunciation language used for Captcha sound generation
	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
	String get/set SoundTooltip	Tooltip of the Captcha sound icon
	String get/set ReloadTooltip	Tooltip of the Captcha reload icon
	String get/set HelpLinkText	Text or tooltip of the Captcha help link, depending on help link mode
	String get/set HelpLinkUrl	Url of the localized Captcha help page the help link points to
	boolean is/set ReloadEnabled	Is Captcha reloading (changing the Captcha code because the current one is too hard to read) enabled
	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
	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
	String get/set SoundIconUrl	Url of the optional custom Captcha sound icon that will be used instead of the default one
	String get/set ReloadIconUrl	Url of the optional custom Captcha reload icon that will be used instead of the default one
	int get/set IconsDivWidth	Calculated width of the Captcha icons <div>, can be user-set to create custom icon layouts
	boolean is/set HelpLinkEnabled	Will Captcha markup include a link to a Captcha help page providing Captcha instructions and explanations for form users
	HelpLinkMode get/set HelpLinkMode	How will the Captcha help link be displayed. The default value is TEXT
	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
	String get/set AdditionalCssClasses	User-defined CSS classes that will be added to the BotDetect CAPTCHA container
	String get/set AdditionalInlineCss	User-defined CSS style declarations that will be added as inline style of the BotDetect CAPTCHA container
	boolean is/set AddCssInclude	Should the BotDetect layout stylesheet be included by the generated Captcha container markup
	boolean is/set AddScriptInclude	Should the BotDetect JavaScript client-side script code be included by the generated Captcha container markup
	boolean is/set AutoUppercaseInput	Should user Captcha code input be automatically uppercased on the fly
	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
	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
	boolean is/set AutoReloadExpiredCaptchas	Should Captcha challenges automatically be reloaded when the Captcha code expires (controlled by the CodeTimeout property)
	int get/set AutoReloadTimeout	Time period in seconds after which automatic reloading of expired Captcha challenges will cease
	int get/set SoundStartDelay	Starting delay (in milliseconds) of Captcha audio JavaScript playback. The default value is 0 (no delay)
	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)
	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)
	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
	boolean isCaptchaSoundAvailable	Are Captcha sounds for the current Locale available
	boolean isSoundPackageMissing	Is the BotDetect pronunciation sound package for the current Locale missing
	boolean isRenderIcons	Should the icons be rendered (true if at least one of the icons will be rendered)
	int getTotalWidth	Calculated width of the Captcha container <div>, based on Captcha image width and should the icons be rendered or not
	int getTotalHeight	Calculated height of the Captcha container <div>, based on Captcha image height
	String getScriptIncludeMarkup	BotDetect script include fragment, including script tags
	String getInitScriptMarkup	BotDetect client-side initialization function
	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
	String getCaptchaImageUrl	Url of Captcha image generated for the current control instance
	String getCaptchaSoundUrl	Url of Captcha sound generated for the current control instance
	String getImageClientId	Client-side ID of the <img> element used for Captcha images
	String getAudioPlaceholderClientId	Client-side ID of the empty placeholder <div> used for Captcha sound playback
	String getValidatingInstanceKey	Name of the hidden field used to pass InstanceId between postbacks
	String getValidatingInstanceId	InstanceId of the previous Captcha instance that is being submitted, set only if IsSubmit is true
	String getHtml	Creates the Html markup that serves as a container for Captcha challenges (images and sounds)
	String getLibInfo	Debug function for getting current BotDetect version and running Java version

[back to the top of the page]

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	The `JsfCaptcha` constructor has no parameters because `id` is assigned through attribute value on the page
	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
	void setCodeLength int length	Length (number of characters) of the Captcha code rendered; the default value is between 4 and 6
	void setUserInputID String inputID	Captcha user input textbox identifier used for all server-side and client-side user input processing
	void setCodeStyle String style	Code style, i.e. the algorithm used to generate Captcha codes; the default value is ALPHANUMERIC
	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
	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.)
	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.
	void setImageFormat String format	Image format in which the Captcha image will be rendered; the default format is JPEG.
	void setImageWidth int width	Width of the Captcha image rendered; the default width is 250 pixels.
	void setImageHeight int height	Height of the Captcha image rendered; the default height is 50 pixels.
	void setCustomLightColor String color	Optional custom light color point, modifies the color palette used for Captcha image drawing
	void setCustomDarkColor String color	Optional custom dark color point, modifies the color palette used for Captcha image drawing
	void setSoundEnabled boolean enabled	Sets whether Captcha sound is enabled is the sound icon and related code added to Captcha markup). Default is `true`.
	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.
	void setSoundFormat String format	Sound format in which the Captcha image will be rendered; the default format is JPEG.
	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`
	void setSoundStartDelay int millis	Starting delay (in milliseconds) of Captcha audio JavaScript playback. The default value is 0 (no delay)
	void setLocale String locale	Locale string, affects the character set used for Captcha code generation and the pronunciation language used for Captcha sound generation
	void setHelpLinkEnabled boolean enabled	Will Captcha markup include a link to a Captcha help page providing Captcha instructions and explanations for form users
	void setHelpLinkMode String mode	How will the Captcha help link be displayed. The default value is TEXT
	void setTabIndex int index	Starting tabindex for the Captcha container Html markup elements
	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
	void setSoundTooltip String tooltip	Tooltip of the Captcha sound icon
	void setReloadTooltip String tooltip	Tooltip of the Captcha reload icon
	void setHelpLinkText String text	Text or tooltip of the Captcha help link, depending on help link mode
	void setHelpLinkUrl String url	Url of the localized Captcha help page the help link points to
	void setReloadEnabled boolean enabled	Is Captcha reloading (changing the Captcha code because the current one is too hard to read) enabled
	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
	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
	void setSoundIconUrl String url	Url of the optional custom Captcha sound icon that will be used instead of the default one
	void setReloadIconUrl String url	Url of the optional custom Captcha reload icon that will be used instead of the default one
	void setIconsDivWidth int width	Calculated width of the Captcha icons <div>, can be user-set to create custom icon layouts
	void setAdditionalCssClasses String cssClasses	User-defined CSS classes that will be added to the BotDetect CAPTCHA container
	void setAdditionalInlineCss String inlineCss	User-defined CSS style declarations that will be added as inline style of the BotDetect CAPTCHA container
	void setAddCssInclude boolean added	Should the BotDetect layout stylesheet be included by the generated Captcha container markup
	void setAddScriptInclude boolean added	Should the BotDetect JavaScript client-side script code be included by the generated Captcha container markup
	void setAddInitScriptInclude boolean added	Should the JavaScript code for BotDetect client-side object creation be included in the generated Captcha container markup
	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
	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
	void setAutoUppercaseInput boolean uppercased	Should user Captcha code input be automatically uppercased on the fly
	void setAutoReloadExpiredCaptchas boolean autoReload	Should Captcha challenges automatically be reloaded when the Captcha code expires (controlled by the CodeTimeout property)
	void setAutoReloadTimeout int seconds	Time period in seconds after which automatic reloading of expired Captcha challenges will cease
	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)

[back to the top of the page]

com.captcha.botdetect.web.CaptchaUrls

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

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

[back to the top of the page]

Please Note

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