001/*
002 * Shredzone Commons
003 *
004 * Copyright (C) 2012 Richard "Shred" Körber
005 *   http://commons.shredzone.org
006 *
007 * This program is free software: you can redistribute it and/or modify
008 * it under the terms of the GNU Library General Public License as
009 * published by the Free Software Foundation, either version 3 of the
010 * License, or (at your option) any later version.
011 *
012 * This program is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
015 * GNU General Public License for more details.
016 *
017 * You should have received a copy of the GNU Library General Public License
018 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
019 */
020package org.shredzone.commons.captcha;
021
022import java.awt.image.BufferedImage;
023
024import javax.servlet.http.HttpSession;
025
026/**
027 * Service for handling click based captchas.
028 * <p>
029 * In a first step, the captcha is created, and the correct answer is stored in the http
030 * session.
031 * <p>
032 * In a second step, the coordinates of the user's click within the captcha is evaluated.
033 *
034 * @author Richard "Shred" Körber
035 */
036public interface CaptchaService {
037
038    /**
039     * Creates a random captcha. The correct answer is stored in the session.
040     *
041     * @param session
042     *            {@link HttpSession} to store the answer in
043     * @return {@link BufferedImage} generated captcha
044     */
045    BufferedImage createCaptcha(HttpSession session);
046
047    /**
048     * Checks if the captcha answer is valid.
049     *
050     * @param session
051     *            {@link HttpSession} that contains the correct answer
052     * @param x
053     *            x position of the mouse click
054     * @param y
055     *            y position of the mouse click
056     * @return {@code true} if the captcha has been correctly answered
057     */
058    boolean isValidCaptcha(HttpSession session, int x, int y);
059
060}