com.octo.captcha.service
Interface CaptchaService

All Known Subinterfaces:

AbstractManageableCaptchaServiceMBean, ImageCaptchaService, ManageableCaptchaService, MultiTypeCaptchaService, SoundCaptchaService, TextCaptchaService

All Known Implementing Classes:

AbstractCaptchaService, AbstractManageableCaptchaService, AbstractManageableImageCaptchaService, AbstractManageableSoundCaptchaService, DefaultManageableImageCaptchaService, GenericManageableCaptchaService

public interface CaptchaService

Main interface of the package. Used by client applications to expose Captchas Challenge validate the response in a transparent and easy way. The flow of operations for using this service is :

• Call the getQuestionForID method to retrieve a question concerning a challenge and present it to the final user.(could be localized)
• Call the getChallengeForID method to retrive a challenge and present it to the final user.(could be localized)
• Call the validateResponseForID method to know if the final user is a human or not.

Developpers should implement this interface using the following rules :
When the getChallengeForID method is called, If no captcha exist for this id, create a new captcha return the challenge.

else if the getChallenge method has been called on the stored captcha, generate a new captcha, else return this captcha challenge.
When the getQuestionForId method is called, If no captcha exist for this id, create a new captcha return the challenge.

else if the a captcha with this id exist, verify the locale (if specified). If the locale match return the same question, else regenerate a captcha and returns the corresponding question.

Throw a CaptchaServiceException if the ID is invalid else return a boolean, and free the ID (remove the captcha).
All method may throw a CaptchaException if an error occurs during Captcha Generation.

Method Summary

java.lang.Object	getChallengeForID(java.lang.String ID) Method to retrieve the challenge corresponding to the given ticket.
java.lang.Object	getChallengeForID(java.lang.String ID, java.util.Locale locale) Method to retrieve the challenge corresponding to the given ticket.
java.lang.String	getQuestionForID(java.lang.String ID) Method to retrieve the question corresponding to the given ticket.
java.lang.String	getQuestionForID(java.lang.String ID, java.util.Locale locale) Method to retrieve the question corresponding to the given ticket.
java.lang.Boolean	validateResponseForID(java.lang.String ID, java.lang.Object response) Method to validate a response to the challenge corresponding to the given ticket.

Method Detail

getChallengeForID

java.lang.Object getChallengeForID(java.lang.String ID)
                                   throws CaptchaServiceException

Method to retrieve the challenge corresponding to the given ticket.

Parameters:

ID - ticket

Returns:

the challenge

Throws:

CaptchaServiceException - if the ticket is invalid

getChallengeForID

java.lang.Object getChallengeForID(java.lang.String ID,
                                   java.util.Locale locale)
                                   throws CaptchaServiceException

Method to retrieve the challenge corresponding to the given ticket.

Parameters:

ID - ticket

locale - the desired localized captcha

Returns:

the localized challenge

Throws:

CaptchaServiceException - if the ticket is invalid

getQuestionForID

java.lang.String getQuestionForID(java.lang.String ID)
                                  throws CaptchaServiceException

Method to retrieve the question corresponding to the given ticket.

Parameters:

ID - ticket

Returns:

the question

Throws:

CaptchaServiceException - if the ticket is invalid

getQuestionForID

java.lang.String getQuestionForID(java.lang.String ID,
                                  java.util.Locale locale)
                                  throws CaptchaServiceException

Method to retrieve the question corresponding to the given ticket.

Parameters:

ID - ticket

locale - the desired localized captcha

Returns:

the localized question

Throws:

CaptchaServiceException - if the ticket is invalid

validateResponseForID

java.lang.Boolean validateResponseForID(java.lang.String ID,
                                        java.lang.Object response)
                                        throws CaptchaServiceException

Method to validate a response to the challenge corresponding to the given ticket.

Parameters:

ID - ticket

Returns:

true if the response is correct, false otherwise.

Throws:

CaptchaServiceException - if the ticket is invalid