Jaffa Packaging Conventions

1. Overview
2. Java Packaging
3. Web App Packaging
4. General Packaging Notes
   1. For Non-EJB Applications
   2. For EJB Applications

This is a guide to the packaging structures used throughout Jaffa, and applications based on Jaffa. This covers how the different objects both in Java, HTML and various other files are laid out

It is recommended that you allow read the following documents in conjunction with this

• Naming Standards
• Recommended Project Directory Structure

We have two proposed structures, short and long.

The Long: <com/org>.<company/project>.applications.<app name>.modules.<module name>
The Short: <com/org>.<company/project>.<app name>.<module name>

Note: All package names in Java should be lower case.

Long Format Examples

org.jaffa.applications.sample.modules.core
org.jaffa.applications.sample.modules.admin

com.mycompany.myapp.invoicemanagement
com.mycompany.myapp.purchaseordering

Within a module we then have three groups of classes

• components - this are the components based on the Jaffa component architecture
  
  
• domain - These are the domain objects that model the business, typically these are persistent objects that implement the base persistent object, but any object related to the domain objects can be placed in here.
  
  
• services - This are common classes that contain business logic that may be re-used across multiple components. The aim is for high re-use for these service. It is better to have more business logic here, then in the specific component's transaction controllers.

Within the components package is a package for each individual component. Each individual component is then split into the following sub packages

• ui - This is where all the user interface classes go. Typically these will be
  • FormBeans
  • Action classes
  • Component Controller
  
  
  
• dto - This is where the data transfer object will live. These package the data that moves between the Transaction Controller and the calling classes (typically the Component Controller or Action classes)
  
  
• tx - This is where the Transaction Controller lives. This is the class (or classes) that perform all of the business functions for the component. Typically this utilize the helper classes in the 'service' packages of the various modules to keep the code as light weight as possible.
  
  
• ejb - This is the package where all the EJB and other middleware proxies go. For a non-EJB implementation, this can be omitted; otherwise this will hold the Home, Remote and Bean class of the EJB. It will also have a proxy class for calling the bean. The proxy class implements the same interface as the underlying Transaction Controller. In other cases where you want to make a Servlet wrapper or even classes to support SOAP or Web Service wrappers, this package can also be used. Any properties files or deployment descriptor fragments would also be placed in here.

In the root package of a given component we typically put the following

• The transaction controller's interface
• A Component Definition XML fragment
• Struts-config XML fragments
• Other fragments if required (like ApplicationResources)

com\mycompany\applications\myapp\modules\user
\components
   \createnewuseraccount
       \ComponentDefinition.xml
       \ICreateNewUserAccount.java
       \StrutsConfigAction.xml
       \StrutsConfigFormBean.xml
       \StrutsConfigGlobalForward.xml
       \tx
           \CreateNewUserAccountTx.java
       \ui
           \CreateNewUserAccountAction.java
           \CreateNewUserAccountComponent.java
           \CreateNewUserAccountForm.java
   \employeeclasslookup
       \ComponentDefinition.xml
       \IEmployeeClassLookup.java
       \StrutsConfigAction.xml
       \StrutsConfigFormBean.xml
       \StrutsConfigGlobalForward.xml
       \dto
           \EmployeeClassLookupInDto.java
           \EmployeeClassLookupOutDto.java
           \EmployeeClassLookupOutRowDto.java
       \tx
           \EmployeeClassLookupTx.java
       \ui
           \EmployeeClassLookupComponent.java
           \EmployeeClassLookupCriteriaAction.java
           \EmployeeClassLookupCriteriaForm.java
           \EmployeeClassLookupResultsAction.java
           \EmployeeClassLookupResultsForm.java
   \logon
       \ * ommitted *
   \userdetailfinder
       \ * ommitted *
   \userdetaillookup
       \ * ommitted *
   \userdetailviewer
       \ * ommitted *
\domain
   \EmployeeClass.java
   \EmployeeClassMeta.java
   \EmployeeClassResources.properties
   \TimeZone.java
   \TimeZoneMeta.java
   \TimeZoneResources.properties
   \UserDetail.java
   \UserDetailMeta.java
   \UserDetailResources.properties
\services
   \CustomAuthenticationManager.java
   \Encryption.java
   \UserHelper.java
   \UserInfo.java

The general structure for the web application follows the format <app name>/<module name>/<component name>. Below each one of these folders, we have another layer that splits up the different type of files. These packages are typically imgs, js, jsp, css, and html.

With most web applications there is a degree of commonality among all the pages, for this we create a common module with the various files in here. In the example below, for the above java source examples, we have a complementary set of web components

Note: Our standard is to make all folder names lower case.

myapp
   \common
       \imgs
           \arrowexpand.gif
           \arrowminimize.gif
       \buttons
               \backd.gif
               \backu.gif
           \guards
       \css
           \main.css
       \js
           \reset.js
   \user\
       \createnewuseraccount
           \jsp
               \default.jsp
       \employeeclasslookup
           \imgs
               \header.gif
           \js
               \clear.js
           \jsp
               \criteria.jsp
               \results.jsp
       \logon
           \ * ommitted *
       \userdetailfinder
           \ * ommitted *
       \userdetaillookup
           \ * ommitted *
       \userdetailviewer
           \ * ommitted *

When building and packaging this application there are some basic guidelines. The basic granularity we have build into this process is that all of the business logic is deployed, with all of the domain objects, but only a given set of modules may be deployed. Without the components in a given module the underlying business capability is not available, but some components use capability across modules, and the underlying database may need all whole schema for integrity.

If you plan to segregate the deployment by module the following guidelines below will help, but it is important to understand your specific application and realize there may be some obvious inter-dependencies between various modules.

1. For an non-EJB application
   1. All of the service and domain packages should be included for all modules
   2. For a deployment of a subset of the application, only deploy the component packages of the desired modules (make sure you cover any inter module dependencies)
   3. In each of the component packages, exclude the ejb package. (If you are putting special stuff here for Servlet wrappers or similar, you must include these, use a naming convention that makes this easy)
   4. All the base html contents, the common html content, the module folders for any of the modules being deployed
   5. When building the components and struts descriptors include all the xml fragments from all the components of the modules being deployed.
2. For an EJB based application

   On the EJB Server you need the following

   1. All of the service and domain packages for all the modules
   2. For all of the modules being deployed for each component in that module you need to include the contents of the tx package, and the contents of the ejb package, excluding the proxy class and any other Servlet wrapper classes that may be in there.
   3. Any EJB deployment descriptor fragments in the ejb package must be included in the build.

   On the web server

   4. This is the same as for a non-EJB deployment (steps 2-5) except the following differences
   5. In the components ejb package we will need the Home interface and the Proxy class
   6. Depending on you container, you'll need to build the ejb-client jar and include that (Unless it uses dynamic proxying like JBoss!)