This document covers the basics of the JAFFA project. It explains what files are available within
a release of the framework and how to use them. As with all frameworks there is an initial
overhead of learning the framework before you become productive at producing code with it.
With the JAFFA project we are providing design documentation to help you understand the
architecture and its features. We are providing extensive 'how-to' guides to explain what
different parts of the architecture do, with examples of how to use them. In addition to this,
we have unit tests that test aspects of the architecture so you can see examples that work.
Finally we are in the process of producing a sample application
(probably not a Pet Store!) as a case study of an implementation using this architecture.
This first document is intended to position you such that you can download the runtime libraries
and understand what each one is for. The section after that explains how you would set up a
project to efficiently use the architecture.
Although we are not in a position to dictate to you how to structure your project, we will make
recommendations based on our experiences with the architecture. Most of the other documents are
based on these assumptions, so it's worth understanding it, even if you wish to deviate from it.
|What's In A JAFFA Release?
This consists of the presentation layer, custom tag libraries, the middleware layer, the persistence engine, among other things
An application based on the JAFFA framework will require this jar at runtime
This is a development aide and has utilities for code generation
It has patterns for generating domain classes, creators, finders, viewers, deletors
This jar file will not be required at runtime
An application will need to extract the contents of this zip file in the appropriate folders, as explained later.
This is the new security realm for tomcat, developed as an part for the JAFFA project
This has the complete source code of the JAFFA project, including unitests
This has the javadoc for the JAFFA project
What Supporting JAR Files Do We Use?
If you look at the source code distribution (jaffa-src.zip) you will see a /lib folder in there.
This contains all the 3rd party JAR files that this project uses. Some of these are used a development
time for code-generation, build routines, the others are used at runtime.
We do not include any database drivers in this /lib folder due to licensing, so if your using something
like Oracle 8i, you'll need to get a copy of classes12.zip (or whatever package contains the JDBC 2.0 drivers).
- servlet.jar, j2ee.jar - These contain the J2EE API implementations of EJB's, servlets and JSP's. You may use other
- webmacro.jar - We use web macro as the templating language in our pattern based code generators
- jaxb-xjc-1.0-ea.jar - Used for generating binding classes for XML from a DTD
- junit.jar, httpunit.jar, Tidy.jar - Used for automated unit testing
- catalina.jar - Only if you want to recompile the tomcat realm!
- struts.jar - Model-View-Controller presentation architecture
- jaxb-api.jar, jaxb-libs.jar, jaxb-ri.jar - This are from Sun's Web Services Developers Pack, and are for JAXB Marshalling
- jdom.jar - Simple XML API
- log4j.jar - Application error and debug logging service
- xerces.jar - XML Parser, was used with JDK 1.3 (JDK 1.4 include one, so does Tomcat 3/4)
- dbConnectionBroker.jar - Used for database connection pooling
|Read Me files
In the CVS repository we have a 'Readme.txt' and a '/lib/Readme.txt', we recommend you read them...
|How To Start A Project With JAFFA
Depending on how you want to test and run your application as you are developing it in you 'sandbox',
it impacts how you use the Jaffa binaries.
- Step 1. Create the suggested directory structure
- Step 2. Put all 3rd party JAR's in the /lib directory. These can be
extracted from the lib folder of jaffa-src.zip
- Step 3. Locate any required database drivers and put in the /lib directory.
Method 1 - Automated Build And Deploy
This is where you have an Ant build routine (or some other make tool) build the WAR
(Web Application Archive) file, you then deploy this to your web server and test it from there.
To achive this the build script must have access to the jaffa.jar for inclusion in the *.war/META-INF/lib path,
and must have access to the jaffa-html.zip file which will be included at the root of the *.war file.
- Step 4. Put the jaffa.jar, jaffa-tools.jar and jaffa-html.zip in the /lib folder
- Step 5. Create your ant build script, using the this example
Method 2 - Build And Test Within IDE
This is where you are using an IDE like Netbeans or Forte, where you can
create a web application with a /WEB-INF folder with a web.xml entry. In this tool you can run the
webserver from within the tool. This assumes that in the same directory as the WEB-INF folder, are
all the files normally in the jaffa-html.zip.
Note: You can combine both of these concepts for maximum flexibility. If you want this use the Method 1 build script
- Step 4. Extract struts*.tld and jaffa-portlet.tld from jaffa-html.zip into the Sandbox\MyProject\source\html\WEB-INF folder
- Step 5. Extract jaffa/*.* from jaffa-html.zip into the Sandbox\MyProject\source\html\jaffa folder
- Step 6. Put the jaffa.jar, jaffa-tools.jar in the /lib folder
- Step 7. Create your ant build script, using the this example
|Building JAFFA From The Source
Even though we have distributed the files need in a development and deployment environment, you
may decide you want to build them yourself from the source. If you do, then see on to see how simple
it is. If you start modifying the code, make sure you stay in compliance with our license.
Here are the steps to build the JAFFA deliverables from the source code
- Unzip Jaffa-src.zip into a suitable folder (or do a checkout from CVS)
- Ensure that you have the 1.4.1 ANT jars in the classpath
- Execute the 'all' task of the ant script 'build\build.xml'
- This will create the 5 JAFFA deliverables in the 'dist' folder
Note: Within the IDE (Netbeans/Forte), to compile the jaffa source you'll
need to mount all the 3rd party jar files in the /lib of the project. This includes
the j2ee.jar, needed for the EJBContext references. If you leave this mounted
an attempt to test run the web app from within the IDE you will have errors
starting the web server.
|Notes on running Unit Tests ...
- Ensure that xalan.jar, junit.jar and optional.jar are present in $ANT_HOME/lib
or in the classpath
- The HttpUnitTests assume a Tomcat 4.0.4 server running on localhost:8080. If you are not
using this port, or want to change it, look for all occurences of 'localhost:8080' in
/source/httpunittest/tests/**/*.java, and change them.
- The Unit tests and HttpUnitTest require access to the database. You must make sure that
jdbcengine\init.xml is configured correctly in both source/unittest and source/httpunittest/java
- The HttpUnitTests require the following users defined in %CATALINA_HOME%/conf/tomcat-users.xml
<user name="PAUL" password="dummy" roles="MANAGER,SUPERVISOR,CLERK" />
<user name="MAHESH" password="dummy" roles="SUPERVISOR,CLERK" />
<user name="GAUTAM" password="dummy" roles="CLERK" />
- If you want to run the Data Security Http Unit Tests, there is a document that outlines
the additional steps needed to get the database set up for running these tests. If you don't
do this then expect the data security tests to fail.
- Architecture Overview
- Naming Standards