Contents

1. Purpose
2. What's In A JAFFA Release
3. How To Start A Project With JAFFA
4. Building JAFFA From The Source
5. Where To Go Now...

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.

1. jaffa.jar
   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

2. jaffa-tools.jar
   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

3. jaffa-html.zip
   This has the JavaScript, CSS, images, JSPs, Tag Library Descriptors used by the JAFFA widgets. An application will need to extract the contents of this zip file in the appropriate folders, as explained later.

4. jaffa-tomcat.jar
   This is the new security realm for tomcat, developed as an part for the JAFFA project

5. Jaffa-src.zip
   This has the complete source code of the JAFFA project, including unitests

6. Jaffa-docs.zip
   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).

Development JAR's

1. servlet.jar, j2ee.jar - These contain the J2EE API implementations of EJB's, servlets and JSP's. You may use other vendors implementations.
2. webmacro.jar - We use web macro as the templating language in our pattern based code generators
3. jaxb-xjc-1.0-ea.jar - Used for generating binding classes for XML from a DTD
4. junit.jar, httpunit.jar, Tidy.jar - Used for automated unit testing
5. catalina.jar - Only if you want to recompile the tomcat realm!

1. struts.jar - Model-View-Controller presentation architecture
2. jaxb-api.jar, jaxb-libs.jar, jaxb-ri.jar - This are from Sun's Web Services Developers Pack, and are for JAXB Marshalling
3. jdom.jar - Simple XML API
4. log4j.jar - Application error and debug logging service
5. xerces.jar - XML Parser, was used with JDK 1.3 (JDK 1.4 include one, so does Tomcat 3/4)
6. dbConnectionBroker.jar - Used for database connection pooling

In the CVS repository we have a 'Readme.txt' and a '/lib/Readme.txt', we recommend you read them...

JaffaCore/ReadMe.txt

JaffaCore/lib/ReadMe.txt

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.

1. Step 1. Create the suggested directory structure
2. Step 2. Put all 3rd party JAR's in the /lib directory. These can be extracted from the lib folder of jaffa-src.zip
3. 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.

1. Step 4. Put the jaffa.jar, jaffa-tools.jar and jaffa-html.zip in the /lib folder
2. Step 5. Create your ant build script, using the this example

Method 2 - Build And Test Within IDE

1. Step 4. Extract struts*.tld and jaffa-portlet.tld from jaffa-html.zip into the Sandbox\MyProject\source\html\WEB-INF folder
2. Step 5. Extract jaffa/*.* from jaffa-html.zip into the Sandbox\MyProject\source\html\jaffa folder
3. Step 6. Put the jaffa.jar, jaffa-tools.jar in the /lib folder
4. Step 7. Create your ant build script, using the this example

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

1. Unzip Jaffa-src.zip into a suitable folder (or do a checkout from CVS)
2. Ensure that you have the 1.4.1 ANT jars in the classpath
3. Execute the 'all' task of the ant script 'build\build.xml'
4. 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.

1. Ensure that xalan.jar, junit.jar and optional.jar are present in $ANT_HOME/lib or in the classpath

2. 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.

3. 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

4. The HttpUnitTests require the following users defined in %CATALINA_HOME%/conf/tomcat-users.xml

   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" />

5. 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.

Where To Go Now...

1. Architecture Overview
2. Naming Standards