CAPTCHA Integration

Introduction

This document provides instructions on adding CAPTCHA support to an AppFuse project. It is based on AppFuse 2.0-M4 which you can find more about by reading the Release Notes 2.0 M4.

Addition of CAPTCHA is as simple as unzipping the appfuse-captcha-2.0-M4.zip file into your "myproject" directory, and editing one pom.xml file.

Here's a screenshot of the final product (click to enlarge):

Versions Used

AppFuse 2.0-M4
Maven 2.0.5
jCaptcha 1.0-RC4

Resources

Download the appfuse-captcha-2.0-M4.zip sources, which includes these instructions.
General AppFuse support is available at the http://appfuse.org/ website. Support for jCaptcha can be found at the http://jcaptcha.sourceforge.net/ website.

Assumptions

This integration guide is based on the AppFuse QuickStart guide, using a Struts 2 Modular project. It's assumed that you will create an AppFuse project called "myproject" with some package "com.mycompany". It's also assumed that you've followed the AppFuse QuickStart guide and are running MySQL already.

This will work for an AppFuse Struts 2 Modular project archetype. Other archetypes aren't supported, but the included files should be easily adaptable based on your requirements. It's assumed that you've just created a new project using Maven, and haven't edited or modified any of the base files. (If you've already started developing your Struts 2 Modular project, check everything into a source control management system to manage changes with this feature.

It's a good idea to check all of your files into source control before unzipping appfuse-captcha-2.0-M4.zip into your project so you can see what files changed, and how they changed. A list of files modified and added can be found below.

Conventions

Change these mnemonics based on your needs:
DEV_HOME = your base development directory, where all of your projects live
com.mycompany = your package name
myproject = your project name

Verifying your Build

Create a modular Struts2 based AppFuse project using:

cd $DEV_HOME
mvn archetype:create -DarchetypeGroupId=org.appfuse \
    -DarchetypeArtifactId=appfuse-modular-struts \
    -DremoteRepositories=http://static.appfuse.org/repository \
    -DarchetypeVersion=2.0-m4 \
    -DgroupId=com.mycompany \
    -DartifactId=myproject

Test that your project builds using:

cd $DEV_HOME/myproject
mvn install

Unpack the AppFuse war into your new project, and test that the webapp runs:

cd $DEV_HOME/myproject/web
mvn war:inplace
mvn jetty:run-war

Open a web browser and use the Signup page to create a new user account. Everything should work at this point, use Ctrl-C to stop Jetty. If everything builds correctly, you can continue, otherwise, consult the http://www.appfuse.org website for how to fix it.

Clean things up before adding CAPTCHA support:

cd $DEV_HOME/myproject/web
mvn clean

Note: it is important to run the "maven clean" goal, otherwise the web app will use the old files in the /target directory without picking up the changes you are about to make.

Adding CAPTCHA

Add a new dependency in the pom.xml file for jCaptcha. Edit the $DEV_HOME/myproject/web/pom.xml file, adding (at about line 200):

<dependency>
    <groupId>com.octo.captcha</groupId>
    <artifactId>jcaptcha-all</artifactId>
    <version>1.0-RC4</version>
    <scope>compile</scope>
</dependency>

Unpack this zip file's contents into your Struts 2 Modular base directory.

cd $DEV_HOME/myproject
unzip appfuse-captcha-2.0-M4.zip

Run Jetty again:

cd $DEV_HOME/myproject/web
mvn clean jetty:run-war

Open firefox and browse to the signup page again: http://127.0.0.1:8080/signup.html You should be greeted with a CAPTCHA challenge. If so, congratulations, CAPTCHA has been added to your project!

Known Issues

The Canoo Webtest for the Signup page fails. Running the web integration-tests using Maven will fail because the Signup page is made inaccessable due to the addition of the CAPTCHA. Is this a feature, or a bug? It's an excereise for the reader to fix this webtest by editing the $DEV_HOME/web/src/test/resources/web-tests.xml file. Maven will result in errors when these commands are run:
```
cd $DEV_HOME/myproject/web
mvn integration-test
#or simply:
mvn
```

Appendix

Here are the details of the changes that are made, excluding pom.xml modifications:

These files are modified:
M web/src/main/resources/ApplicationResources.properties
M web/src/main/resources/struts.xml
M web/src/main/webapp/WEB-INF/applicationContext-struts.xml
M web/src/main/webapp/WEB-INF/security.xml
M web/src/main/webapp/WEB-INF/web.xml

These files are added:
A web/src/main/java/org/appfuse/webapp/JCaptchaServiceProxyImpl.java
A web/src/main/java/org/appfuse/webapp/action/CaptchaAction.java
A web/src/main/java/org/appfuse/webapp/servlet/ImageCaptchaServlet.java
A web/src/main/resources/org/appfuse/webapp/action/CaptchaAction-validation.xml
A web/src/main/webapp/WEB-INF/applicationContext-captcha.xml
A web/src/main/webapp/WEB-INF/pages/captcha.jsp