On Java Development

All things related to Java development, from the perspective of a caveman.

WTF is “baseproject”?

without comments

Although baseproject will present a page in a browser it does not do anything constructive as a web application. It simply represents a starting point from which to begin project development. Without this project, a developer could easily spend half a day just getting a project ready for development.

With baseproject a developer can be ready to start on the task of solving the business problem in about 15 to 20 minutes. In addition, every project started this way has a standardized package layout, application startup servlet, resource initialization using Spring, utility and helper classes and page templates for the presentation side.

Project dependancies are managed using Maven with its pom.xml file pre-configured to incorporate jar-files for the following core technologies:

  • JSF 2.2.4
  • RichFaces 4.3.4.Final
  • Spring 3.2.1.RELEASE
  • Hibernate 4.2.6.Final
  • Log4J 1.2.17
  • iText 5.5.0
  • iText-xtra 5.5.0

The sections that follow give details about the major features all of which can be viewed as minimum requirement for any web application. All of them are functional right out of the box without the need for further modification by the developer.

 
 

The Big Picture

The following diagram (click to enlarge) presents the major aspects of baseproject. From the high-level perspective, it’s very basic and it is easy to see just where the developer should focus to begin development.

The details of the startup processing phase and the application’s property management will be presented in the sections that follow.

Additional sections are presented to highlight other features of baseproject not depicted in the diagram.
baseProjectArch03

 
 

Application Startup

A servlet class called StartupServlet exists to pre-initialize the application making it ready for immediate use.

When the server starts each day, StartupServlet is evoked. The first task is to read the runtime environment variable assigned to the server. The servlet then initializes Spring’s context and stores the assigned value for the runtime environment into the ApplicationGlobalProperties , a Spring bean, enabling the application to determine whether or not the server is for “localhost”, “TEST” or “PROD” which is crucial for being able to retrieve the correct Spring bean containing the application’s properties assigned to each of those environments.

After this, Log4J is initialized to provide the application with logging support. baseproject contains classes that extend Log4J classes to intercept the message to be logged so that long entries can be folded at a specific length to facilitate readability. The user id and the server’s runtine environment value is also added to each line.

For the developer using baseproject, StartupServlet won’t need to be changed from project-to-project. Nor will the contents of the Log4J configuration file. However, the Spring configuration file that is used to define the global properties and the properties for each of the three different runtime environments will change from project-to-project. This means the contents of the classes ApplicationGlobalProperties and ApplicationProperties will also change accordingly. Therefore, this makes this area of the application a good place to start for the development process.

Begin by determining what values can be global, meaning they do not change across runtime environments. Examples are email server addresses and ports which the application may need. Values that are determined by the runtime environments are recipients of email sent by the application. During development and testing phases, you don’t want to be sending email to the user community just yet. You get the idea. Next, modify the classes ApplicationGlobalProperties and ApplicationProperties to contain their property fields, declared as private and exposed via mutator and accessor methods (a.k.a. setter and getter methods). For each property added to these classes, modify the bean definition to include the name/value entries for each of those properties.

The ApplicationContextManager class allows static access to Spring context beans as well as a Hibernate session object, an Entity Manager object or a DataSource object for Spring stored procedures. Each of these objects are configured to incorporate libraries related to the test or production database for the iSeries.

One final word on properties. Using Spring in this manner simplifies the definition of property files for an application and provides a way of segregating the values for each of the runtime environments. It does not lend itself well to being able to quickly modify them once the application is deployed. If well written, an application will never need that ability. Also, it precludes the need to segregate the property files away from the application’s project structure on the server to prevent them from being over written when it is redeployed. In that mode, you’re now into property file management.

 
 

Application Properties

As it comes, the file applicationContext.xml defines one Spring bean to contain properties that need to be defined just once because the properties are not dependent upon a specific server environment meaning they are the same for the developer’s machine, the test server and production server. Another Spring bean is provided to contain properties that are specific to each of these runtime server environments. During development, new properties and their values will be added to these beans as required by the application’s design.

Below is a diagram that represents how the application’s properties are defined using Spring. The left side of the diagram show segments of Spring’s configuration file entries that define the application’s global properties as well as the property values needed for each of the three different runtime environments, which are “localhost”, (the developer’s machine), “TEST” (User Acceptance Testing – UAT) and “PROD” (production).

Since Spring is used for the purpose of defining the values, the values are placed into Spring beans the names of which are circled in red. The application will use only 2 of the beans when it is running; the bean containing the global values and the bean holding the values assigned to one of the three runtime environments. The beans are retrieved by name and their values are placed into the assigned Java class, circled in blue. The classes are GlobalApplicationProperties and ApplicationProperties and are depicted on the right of the diagram. Whenever the application needs to refer to one of the property values, the bean is retrieved from Spring’s context and then cast to the assigned class. The application then uses one of the so-called “getter” methods to retrieve the property value.

baseProjectArch01

Since an application is not restricted to having a single Spring configuration file, included in the project is a file called template.xml to be used as the basis for new Spring bean configuration files.

datasourceContext.xml defines datasources in a way that allows the correct DS to be used as determined by current runtime environment. The datasource definitions are used only by Spring based stored procedures. This xml will also hold all DAO and Service beans.

The JPA datasource definitions have been configured so that Hibernate will work with non-journaled files. If the developer needs to use the Hibernate Session instead of the JPA Entity Manager, the configuration can be easily changed.

 
Session Timeout Handling

baseproject provides support for handling session timeouts that occurs when the application is left in an inactive state for more than 30 minutes. When the page enters into a timeout state, the following screen similar to the one below will be presented to the user. If there is no activity for this screen beyond the 30 minute threshold, the screen automatically returns to the menu page.

 
Host Aware

This feature provides the ability to determine the I.P. address of the server and the port number being used by the server without having to hard-code these values into Spring context bean. Hard-coding these values creates a requirement to change their values when servers are changed due to upgrades, which has already occurred in our environment. This feature automatically returns the correct values regardless of installation.

As an example of how this can be used, the server name and port are required when fabricating http URL strings to display PDF documents.

 
LaunchServlet

As the name implies, the LaunchServlet class is the class that launches the application, but there’s more going on than that. When the application is selected from the menu pre-processing may be required such as validating the user, etc. This servlet would be modified to address those issues, if any. Using servlet mapping entries in the application’s web.xml file shown below, the LaunchServlet is evoked.

 
Faces Context Helper Class

The FacesContextHelper class provides helper methods that provides access to the Faces Context object which contains the HTTP session object. User session objects can be stored and retrieved to and from the session using the provided setter/getter methods. This makes it possible to hold user data in their session which can be thought of as a Local Data Area.

 
BaseBean

The BaseBean class is the base class for all Managed Beans and can be enhanced to contain all of the query requests for the application. This does not mean the implementation is to be placed here, just the calls to the service layer methods. In this way, BaseBean saves the developer from the task of peppering each Managed Bean with these methods. With the methods established in this class just once, each Managed Bean that extends this class then has access to them, saving a bit of work and method duplication.

Here’s an example of a method placed in BaseBean ;

Because each of the application’s Managed Beans extend BaseBean, when a Managed Bean needs to acquire a list of records to load a data table, the Java code needed is shown below.

While this class has been designed to hold the methods that are common to all Managed Beans, it should not be used to store data. Instead, use the class SessionBean (see next topic) that is designed to be placed into the session. The method getSessionBean() facilitates this.
BaseBean

 
SessionBean

The SessionBean is designed to hold data that can be accessed across multiple pages of the application. The methods of BaseBean (above) facilitate storage and access to this bean. This class can and should be modified with the appropriate properties and associated setter/getter methods as required.
SessionBean

 
Email
Email is supported using Oracle’s JavaMail API. Server Configuration is contained in the bean “applicationGlobalProperties“. The methods used for constructing an email are contained in mail.jar, found in the project’s lib directory. For JavaDocs, see this link.

 
Date and Time Helper Classes

There are so-called “helper classes” designed to assist in various tasks related to dates and times. For example, the DateTimeHelper class provides the means to acquire new date object using the system’s clock in addition to providing methods designed to format dates and times suitable for display. Other methods assist in calculating the elapsed time between two date objects that can be used to preform aging tasks.

This helper class was built prior to the adoption of Joda-Time provided by joda-time-2.7.jar. Joda-Time is designed to reduce much of the pain associated with date and time problem solving. As a consequence, expect to see this class increasingly rely upon the Joda project.

TimeZoneMap

 
Time Converter

The TimeConverter class is a JSF based converter designed to assist in formatting times in hh:mm:ss format. The converter class is reusable as-is.

 
Social Security Number Converter

For display purposes, the SSNConverter class converts the SSN from “123456789” to “***-**-6789”.

 
Phone Number Converter

For display purposes, the PhoneConverter class converts a phone number from “1234567890” to “(123) 456-7890”.

 
Zip Code Converter

For display purposes, the ZipConverter class converts a Zip code from 123451234 to “12345-1234”.

 
Calendar Managed Bean

The CalendarManagedBean class provides the interface between the web page’s calendar object and the application and is used to define the calendar’s behavior.

 
JSF 2.0 Resource

The project’s Directory hierarchy and naming follow JSF 2.0 resource management conventions. These directories contain page components, cascading style sheets, images and java script files, resources referenced as library names rather than by path names.

 
JSF Facelets

A web page template file, pageTemplate.xhtml, is provided to be used as the basis for new web pages. This template includes the use of header.xhtml so that the page banner design is contained in a single xhtml file. If standards change this makes it possible to quickly change the page heading used across all applications.

 
JSF Date Converters Defaults to Server Timezone

JSF date/time converters, e.g.:

defaults by specification to the UTC timezone (Coordinated Universal Time). If the supplied date for the above is Fri Apr 01 00:00:00 CST 2005 it will be returned to the managed bean as Thu Mar 31 18:00:00 CST 2005.

Modifications to the JSF configuration inside of baseproject ensures the date returned reflects the default timezone of the server in which the application is running. In other words, if the supplied date is Fri Apr 01 00:00:00 CST 2005 it will return Fri Apr 01 00:00:00 CST 2005 to the managed bean instead of Thu Mar 31 18:00:00 CST 2005. This removes the need to hard-code timezone codes on the converter spec, which is never a good idea.

 
For more detail about the topics listed above, use the following links.
The Startup Servlet
Using Java Reflection to call methods of a Java Class
Using baseproject’s ApplicationContextManager class
Managing Session Timeouts
Date and Time Helper Class
Facelet Templating
JSF Resources
RichFaces Wait Dialog
Calling RPG or CL Programs with SETLIBLEXEC

 

Getting Started

This link will let you download the Word document that both illustrates how baseproject was created as well as presenting step-by-step instructions on how to start a new project using baseproject stored in SVN.

The document is divided the following sections;

  1. TOMCAT SERVER CONFIGURATION – Shows how Tomcat was configured for Test and Production runtime environments
  2. STARTING ECLIPSE WITH SPRING TOOLS SUITE – Starting Eclipse
  3. STARTING BY CREATING THE BASE PROJECT – How Base Project was created
  4. STARTING BY GETTING THE BASE PROJECT FROM SUBVERSION – How to checkout baseproject from SVN and begin working
  5. TIPS, TECHNIQUES AND TROUBLE-SHOOTING – Tips and techniques

For the developer who wants to download the project from SVN and begin work right away, begin with the section “STARTING BY GETTING THE BASE PROJECT FROM SUBVERSION“

You will need Tomcat and Eclipse installed on your machine.

Written by admin

April 4th, 2014 at 4:47 am

Posted in

Leave a Reply

You must be logged in to post a comment.