DRAFT

ETF Development Guidelines01/11/2005

The ETF Java Standards Summary Document intended to summarize the Java Standards used by ETF. More detail documents are covered under the following:

State of Wisconsin Department of Employee Trust Funds Development StandardsConfiguring a JDBC Provider in WSADETF Struts Development GuideSetting up WSAD 5 for using CVSWorking with CVS from WSAD

ETF Development Environment

ETF takes full advantage of the Java Technology primarily to build J2EE Web Applications. ETF J2EE applications primarily accesses DB2 Data on IBM’s zOS System using JDBC. In some specialized cases in which it makes sense, ETF J2EE Applications will access DB2 Stored Procedures primarily when business logic is shared between the J2EE environment and the ETF legacy COBOL environment. Here is a quick summary of the ETF key standard development environments items:

ETF uses IBM WebSphere Studio Application Developer (WSAD) IDE tool for developing ETF’s Java Applications. Currently, ETF is using WSAD 5.1.0. In addition, ETF uses CVS as it source code repository all artifacts built in WSAD.

ETF developers will develop and perform first level unit testing using WSAD and utilizing WebSphere Application Server built into WSAD.

ETF currently develops mainly Java Web Applications and a few Java Applications (main method running in a batchable script file). ETF does not currently develop Web Services applications nor does it develop EJB. ETF does not have 2-phase commit needs across more than 1 instance of a Database and/or Transaction Server.

ETF currently uses DB2 on zOS and developers have access to either individual DB2 Databases on zOS or they have access to an Acceptance DB2 Database on zOS. ETF does not use any other Database Manager at this time.

ETF has two additional test environments – Test and Acceptance test. See section on Testing Environments for more information.

DRAFT

ETF Common Project

ETFDAOCommon is a common project that contains many of the Data Access Objects (DAO) for ETF DB2 Database Tables. The DAO are built in this project and then packaged with other projects. When developing in WSAD, ETFDAOCommon can be link with any other projects. When building a deployable ear, the ETFDAOCommon needs to be built as a jar file and included as part of the deployable ear. In order to link ETFDAOCommon with in WSAD, two steps need to be performed.

(1) The Project’s build path needs to point to the ETFDAOCommon Project. Right click on the desire project and click on properties.

DRAFT

Next, click on the project tab.

DRAFT

Next check ETFDAOCommon and click on ok.

(2) The test WebSphere Server’s class path in WSAD needs to point to the ETFDAOCommon Project. From the server configuration

DRAFT

Next, click on the environment tab.

DRAFT

Next click on Add Folder and add ETFDAOCommon.

DRAFT

Drill down and highlight “classes” under ETFDAOCommon/Webcontent/WEB-INF/classes. Click on OK.

DRAFT

Next, you will need to Add External Jar for the Log4j Jar file. You will need to get a copy of the log4j jar file and store it on your C drive and then point the External Jar to it.

Finally Save the configuration and restart the server.

DRAFT

ETF Package Naming Standards

ETF Java package name standard is as follows:

gov.wi.etf.xxxxxxxx.bo Business Objects

gov.wi.etf.xxxxxxxx.bs Business Service

gov.wi.etf.xxxxxxxx.util Utility Classes for the project

gov.wi.etf.xxxxxxxx.dao.util Utility Classes for Data Access Objects such as converting to/from ETF Date Integer

gov.wi.etf.xxxxxxxx.bo.util Utility Classes for business such as business calculations

gov.wi.etf.xxxxxxxx.dao Data Access Object Interfaces

gov.wi.etf.xxxxxxxx.dao.db2 Data Access Object DB2 Implementation

gov.wi.etf.xxxxxxxx.dao.hibernate Data Access Object Hibernate Implementation

gov.wi.etf.xxxxxxxx.web.action Struts Action Classes

gov.wi.etf.xxxxxxxx.web.form Struts Form Classes

gov.wi.etf.xxxxxxxx.assembled.vo Value Objects (getter/setter) that are assembly of other Value Objects

gov.wi.etf.xxxxxxxx.vo Value Objects (getter/setter) to/from a database

xxxxxxxx is can be any name representing some meaningful name of the application. ETF in most cases would use the project name and the project name as well as this name would represent a meaningful name of the application.

DRAFT

1. JNDI Schema Lookup

ETF takes advantage of Schema names in DB2. In order to reference a table in DB2, the DB2 table name must be prefixed with a Schema name. The Schema name can be different in our different DB2 environments. Production tables usually prefixed with a Schema name of ETFWDBA. Our Acceptance tables are usually prefixed with a Schema name of TNT171UP. Each developer has its own sets of tables prefixed with a Schema name of TNT171xx were xx is a unique qualifier for each developer.

In order to make our application more portable between environments, the Schema name is externalized from the application either as a JNDI reference or as a reference in a .properties file.

We will create a unique JNDI lookup for each J2EE project’s database scheme name. The actual JNDI lookup name will be stored in the database.properties file. A getSchemaName method will be built to first look for the JNDI Scheme name, do a JNDI lookup for the scheme name, and if the JNDI name does not exist, use schema property value in database.properties. For example:

Database.properties

DB2DAOFactory.userid=ETFUDMSDB2DAOFactory.password=UNLOCKDB2DAOFactory.datasource=java:comp/env/ETF/DB2DB2DAOFactory.database.schema.name=TNT171UP.DB2DAOFactory.database.schema.JNDI.name=java:comp/env/ETF/DB2/Schema/

myProj

getSchemaName

1. “getSchemaName” will return the database schema name to be used for every SQL call within myProject

2. “getSchemaName” will do a property lookup in database.properties for DB2DAOFactory.database.schema.JNDI.name to retrieve JNDI lookup name.

3. In WAS Test, Acceptance, and Production server, these schema JNDI names will be defined under the “NAMING” configuration for each myProj Schema names.

4. “getSchemaName” make a JNDI lookup call to “java:comp/env/ETF/DB2/Schema/myProj” (or whatever JNDI name specified in the database.properties file and return the schema lookup name.

5. If JNDI lookup name does not exist, then “getSchemaName” will perform a properties lookup in database.properties for DB2DAOFactory.database.schema.name and return its value as the schema name. This will be a likely scenario for WSAD Development Environment.

DRAFT

Log4j

ETF has standardized on the use of log4j. Log4J provides the means of inserting log statements into your code in order to provide a low-tech method for debugging it. Log4j is an Apache open source project used by many companies. At this time, ETF does not support the built in logging package in JDK 1.4. To convert to JDK 1.4 version would be pretty easy – simply changing the package name in each class, but the actual configurable options in Log4j seems to be more robust at this time. ETF will continue to evaluate the JDK 1.4 version. More information on log4j can be found at http://logging.apache.org/log4j/docs/.

Here is an example on how to use log4j..

package gov.wi.etf.myProject.whatever;

import org.apache.log4j.Logger;

public class MyClass {

final Logger log = Logger.getLogger(this.getClass());

public void myMethod {log.debug("Entered into: "+this.getClass());

my code

log.debug("Exiting: "+this.getClass());} }

ETF Standards on Log4j usage within our applications.

1. The package org.apache.log4j.Logger must be imported.

import org.apache.log4j.Logger;

2. At the beginning of each class, the following statement must be setup as private variables to the class.

private final Logger log = Logger.getLogger(this.getClass());

3. At the beginning of each method, the following statement must be setup.

log.debug("Entered into: "+this.getClass()); Note: JDK 1.4 has a way to get a method name executing. Also there is a log4j option that get this. For now, we will turn on the log4j option of getting the method name if needed.

4. At the ending of each method, the following statement must be setup.

log.debug("Exiting: "+this.getClass());

DRAFT

5. If a given method truly ends with a final finally block, the Exiting statement needs to be placed as the last statement in the finally block.

6. In any DAO classes, all SQLException must be catched and a log.error must be used. For example:

A catch(SQLException e) {

Your code.

log.error("database error in class: "+this.getClass()+" had the following SQLException reported: " + e); }

7. Developers are encourage to use log.error,log.warning, log.info in other areas of there code that they judge to be relevant.

Value Objects (VO)

ETF uses the term Value Objects(VO) which is more commonly identified as getter/setter classes or sometime referred to as Accessor classes. More information on Accessor classes can be found in section 3.4 under the ETF Development Standards. ETF uses VO classes to pass data to/from Data Access Objects (DAO) and pass data to/from presentation layer (usually

JSP). Here is a quick summary of our key standard development environments items:

1. In respect to VO for DAO, a VO will represent a row of a table or a row of a collection of normalized tables. There will be one getter/setter method for each Database column.

2. The getter/setter type in a VO representing data in a database should have the same type or similar type as the underline column type in the database. For example, a CHAR column should be represented by a Java String Type. A Date Column should be represented by java.util.Date Type. A Decimal Column should be represented by BigDecimal Type.

3. The getter/setter type in a VO representing data to the presentation layer should use a String Java Type.

4. If data being presented back to the presentation layer is a Date or BigDecimal Type, the VO class needs to represent the private class variable as Date or BigDecimal, offer both a getter/setter String representation and a getter/setter for the Date or BigDecimal Type. The String method version needs to be suffixed with “Display”. For example:

private BigDecimal MonthlyAmount = BigDecimal.valueOf(0);

public BigDecimal getTotalGenMonthlyAmount() { return totalGenMonthlyAmount; }

public String getTotalGenMonthlyAmountDisplay() {if (totalGenMonthlyAmount.doubleValue() == 0)

return new String();else return totalGenMonthlyAmount.toString(); }