SDLC STANDARDS

JAVA WEB DEVELOPMENT STANDARDS

Version 2.4.1    July 18, 2008

This page contains the Ministry's published standards for Java Web Development.

Table of Contents 

VERSION CONTROL

1.      INTRODUCTION
1.1    Purpose
1.2    Audience
1.3    Scope/Exclusions
1.4    Assumptions
1.5    Definitions
1.6    Other Standards
1.7    Contacts
 
2.      Deliverables
2.1    Data Model
2.2    Executable Software
2.3    Source Code
2.4    Build Scripts
2.5    Development Tools
2.6    Documentation
 
3.      Development Rules and Guidelines
3.1    Development Process
3.2    Data Source Configuration
3.3    Coding Style
3.5    Source File Layout
3.6    Programming Techniques
3.7    Internal Documentation
3.8    Error Handling
3.9    Logging
3.10  User Interface Standards
3.11  XML Compressors & Accelerators
3.12  Naming & Versioning Conventions
3.13  Ministry Database Object Naming

4.      Application Design
4.1    Architecture Overview
4.2    Deployment Pattern
4.3    Struts Framework
4.4    Java Server Pages
4.5    Persistence Layer

5.      Application Environment
5.1    Client Tier
5.2    Middle Tier
5.3    Data Tier

6.      Security
6.1    Authentication
6.2    Authorization
6.3    Database Access
6.4    Ministry Database Role Naming
6.5    Enforcing Application Flow
6.6    Forbidden Characters in URLs

7.      Reports
7.1    Designing Reports
7.2    Charting

8.      Email

9.      Common components
9.1    Mandatory common components
9.2    Additional Java Libraries

10.      Documentation
10.1    Release Notes
10.2    Application Use
10.3    Help
10.4    Application Configuration
10.5    Instructions for Compilations
10.5    Design Revisions to As-Built

VERSION CONTROL

This section of the document records the various versions or releases of this document

Table 1: Version Control

[TOC]

1.     INTRODUCTION

The intent of this document is to describe the guidelines and standards to be followed when developing web applications using the Java programming language for the Ministry. This document is not intended to be a general guide to Java programming but rather will focus on development standards specific to the Ministry. For detailed specifications concerning the Java programming language, refer to the Sun Microsystems website.

1.1     Purpose

This document outlines the standards that must be followed when building application systems for the Ministry using the Java programming language.

1.2     Audience

This document is directed at those who will be designing, developing and maintaining Java based application systems for the Ministry. This includes external contractors, consultants, and business partners, as well as Ministry employees.

1.3     Scope/Exclusions

The scope of this document covers all Java application development but is primarily focused on web-based deployments.  The document does not address the low-level design of an application, but rather provides high level considerations for a starting point for detailed design.  Application delivery standards are mentioned but the details are documented within other standards documents. 

Where conflicts, if any, are perceived between this document and other standards, the Ministry Business Analyst must be consulted.

1.4     Assumptions

It is assumed that the audience has a working knowledge of the Java programming language, J2EE, Oracle's Designer (CASE) product, and Oracle relational database technology.

1.5     Definitions

The following definitions apply throughout this document.

1.5.1 Standards

A standard is a specific statement of the rules and constraints governing the naming, contents, and operations of software. A standard must be followed. There is a contractual obligation on the part of the vendor/developer to adhere to all relevant standards.

1.5.2 Guidelines

A guideline is a method or custom, which through common usage has become an accepted method of work. A guideline is not enforced, and is not a standard.

1.5.3 Ministry

Unless otherwise specified, "Ministry" is taken to collectively mean the Ministry of Agriculture and Lands and the Ministry of Environment. Both Ministries are served by a common Information Management Branch (IMB) with the mandate to formulate and maintain application development standards.

1.6     Other Standards

The Ministry has a number of standards pertaining to application development and the System Development Life Cycle (SLDC).  Below are the standards documents referenced in this document as well as a link to a listing of all Ministry standards.

1.7     Contacts

All inquiries regarding these standards should be directed to the Ministry Business Analyst assigned to the project.

[TOC]

2.     DELIVERABLES

The following subsections describe the core types of deliverable components expected for each release of any application (as applicable). Additional deliverables may be specified for any application and will normally be indicated in the RFP.

For more detailed specifications regarding this topic refer to the Application Delivery Standards and the Java Delivery Standards ; please note that these documents are available only on the Ministry’s Intranet web server -- developers will require a VPN account to access these documents.

2.1     Data Model

Before any release of a WebADE application can be delivered, the data model for the application must be approved by the Data Administration team. Every project will have a member of this team assigned to it and developers should keep in regular contact with this person while establishing, updating, and extending the data model.  

For more detailed specifications regarding this topic refer to the Oracle Designer Standards and Guidelines.

2.2      Executable Software

All deliveries of Java based applications must be in Enterprise Archive (EAR) format. A separate EAR file is required for each application. EAR files will be deployed in the J2EE server under separate context roots, thus leveraging the Java Virtual Machine (JVM) as a mechanism for ensuring that each application is functionally isolated from other applications sharing the same JVM.

All components that are required by the application to execute to its specification, excluding generally available standard software of the WebADE, must be provided to the Ministry. This includes binary code and support files such as images, configuration files, etc.

For more detailed specifications regarding this topic refer to the Application Delivery Standards and the Java Delivery Standards.

2.3     Source Code

Source code for all software not included in the standard WebADE components must be provided as part of the project deliverables. This software will become the property of the Province of BC. All of the Java code must be compiled at the Ministry site to ensure that there are no syntax errors and that it compiles in the Ministry's environment.

For more detailed specifications regarding this topic refer to the Application Delivery Standards and the Java Delivery Standards.

2.4     Build Scripts

All of the Java deployable components must be compiled at the Ministry's environment. It is not acceptable to skip the compilation step. The public domain tool Ant, available from the Jakarta project, must be used for component compilation. 

The current Ant version is listed in the Systems and Application Technology Standards Summary.

2.5     Development Tools

The term 'IDE' refers to an integrated development environment tool for writing standalone Java classes, HTML pages, Java servlets, and Java Server Pages. Such a tool can assist with the graphical layout of the user interface of a Java-based application, with writing Java code, and with running, testing and debugging the application.

The Ministry will permit application developers to use any IDE that generates J2EE 1.4 (or above) compliant code; proprietary code and extensions must not be used in the development of an application (e.g. use of Oracle's Business Components for Java (BC4J) will not be permitted).

2.6     Documentation

See Section 10 for standards concerning required documentation associated with an application.

[TOC]

3.     DEVELOPMENT RULES & GUIDELINES

This section describes the Ministry's expectations of how applications will be developed from both macroscopic and microscopic perspectives.  These expectations are illustrated in terms of rules, which specify what must be done, and guidelines, which explain how things should be done.

3.1     Development Process

The application development and delivery process is described in Java Delivery Standards.

3.1.1. Quality Assurance (Source Code Reviews)

The Ministry has defined formal quality assurance guidelines that will apply to each phase of the System Development Life Cycle (SDLC).

The Ministry's Information Management Branch (IMB) will review all Java source code as part of the Ministry's Quality Assurance process associated with the delivery of Java based applications to the Ministry. Java source code delivered to the Ministry must conform to Sun's Code Conventions for the Java Programming Language.

Java code delivered to the Ministry that does not conform to Sun's Code Conventions for the Java Programming Language will not be accepted. Vendors will be required to modify their code to conform to Sun's Code Conventions before the application will be accepted by the Ministry. Specifically, the code must pass an automated audit process without generating any errors or warnings.

The Ministry employs the CheckStyle utility to analyze compliance of Java source code to Sun's Java Coding Standards. The Ministry's CheckStyle configuration file contains a customized sub-set of the rules included in the sun_checks.xml file that is included with the standard SourceForge CheckStyle distribution. See in-line comments in env_checkstyle.xml for a explanation of the checks, cross-referencing CheckStyle reference documents where necessary.

CheckStyle plug-ins are available on the SourceForge CheckStyle web site for many popular Java Integrated Development Environments (e.g. Eclipse, JBuilder, NetBeans, etc.). Vendors are expected to use CheckStyle within their development environment in order to ensure that Java code is consistent, well structured, and properly documented.

CheckStyle can also be run interactively from the command line or integrated in an Ant build script. The Ministry provides a sample Ant build script along with the Ministry's CheckStyle configuration file, all packaged in the zipfile env_checkstyle.zip (updated 2008-MAY-26).

The ministry may also perform review source code for such things as:

• structure in accordance to commonly accepted programming practices;
• complete and meaningful documentation;
• portability and reusability

3.1.3 Exemption from Standards

Any exemption from Ministry system and application technology standards must be approved in writing by the Head of Architecture, IMB. Any such approval must be in place before development. This includes use of components that are outside ministry standards (including third-party java libraries), technology dependencies, failure to use mandatory security components, failure to use common components for common functions (such ENCC for email), use of unsupported component versions, requirement for components not within standard deployment patterns, or any other deviation from standards.

See Other Standards in this document for a list of Ministry standards.

3.2     Data Source Configuration

Developers will need to replicate the data sources that the application will use in production. This involves (i) establishing the structure of the data sources, (ii) replicating those sources in the development environment (i.e. the vendor's environment), and (iii) populating the data tables appropriately for development.

In projects where the data sources already exist the data source structure can be taken directly from them.  In most projects, however, some data modeling will be required.  In this case the data sources will be established as defined by the data model.

In some situations, the Ministry may provide development-level data sources for developers to use. The Ministry will generally supply developers with sample data.

Any vendor to whom data sources are provided must comply with the British Columbia Freedom of Information and Protection of Privacy Act. Attention is particularly drawn to section 30.1, which specifies that "A public body must ensure that personal information in its custody or under its control is stored only in Canada and accessed only in Canada."

Please contact the Ministry Business Analyst for assistance.

3.3     Coding Style

The Ministry bases its Java programming style on Sun's Code Conventions for the Java Programming Language, as found at the locations:

Code Conventions for the Java Programming Language 
Code Conventions for the JavaServer Pages

These conventions include basic guidelines for naming (files and code), code layout, comments, and general programming practices.

Vendors should include JavaDoc style comments in their code as per Sun's Javadoc Standards; each source file should begin with a file header level standard Javadoc comment as shown below.

/* 

  $Id: java_standards_23.html,v 1.1 2006/03/31 01:07:06 teglover Exp $

  Copyright (c) 2006, 
  Government of British Columbia, 
  Canada

  All rights reserved. 
  This information contained herein may not be used in whole or in part
  without the express written consent of the Government of British
  Columbia, Canada.

*/

3.5     Source File Layout 

Java source files must have a specific layout, as described in the following subsections. 

For more detailed specifications regarding this topic refer to the How to Write Doc Comments for the Javadoc Tool document.

3.5.1 Header block 

Every source file should begin with a simple Javadoc style header block that identifies the file and provides a copyright disclaimer. The "header" comment block should appear as in the following example:

/** 
 * @(#)MyClass.java 
 * Copyright (c) 2005, Province of British Columbia. 
 * All rights reserved. 
 */

3.5.2 Class Definition 

The code defining the class should be immediately preceded by a Javadoc comment describing the class. This comment provides general information about the class and references to related items. A brief explanation or example of how the class can be used is encouraged but not required. 

The class definition comment must contain complete Javadoc @author tags and a @version tag near the end. 

Contributors should be listed in order of the date of their first contribution, with the original author listed first.  

The Javadoc block for the class should end with @author and @version tags, as shown:

/** 
 * This class is used to ... 
 * ... etc ... 
 * 
 * @author Jane Doe 
 * @author John Doe 
 * @version 2.3 
 */

Use of other tags, such as @see and @link is encouraged to improve navigation in the generated Javadoc. 

3.5.3 Methods, Initialisation Blocks, Variables, and Constants 

The Javadoc blocks for each constructor and method, as well as non-private instance variables, must contain @param, @return, @throws Javadoc tags as appropriate. Also, each such block must end with the @since tag, as shown, if the product release currently under development is newer than the original version (e.g., not version 1.0):

/**
 * Verifies the name against a database of known champions ...
 * ... etc ...
 *
 * @param name
 * the name of the person to verify.
 * @param dbURI
 * the URI of the file containing the database of champions.
 *
 * This is used to obtain a reference in the file system relative
 * to the root location of the application.
 *
 * @return
 * <CODE>true</CODE> if found, </CODE>false</CODE> otherwise.
 *
 * @throws FileNotFoundException
 * if a file corresponding to <CODE>dbURI</CODE> cannot be found.
 *
 * @since 1.0
 */

3.5.4 JSP Documentation

A JSP file or fragment file must begin with a server side style comment: 

<%-- 
  - Author(s): 
  - Date: 
  - Copyright Notice: 
  - @(#) 
  - Description: 
--%> 

This comment is visible only on the server side because it is removed during JSP page translation. Within this comment are the author(s), the date, and the copyright notice of the revision, an identifier and a description about the JSP page for web developers

3.6     Programming Techniques 

For details regarding programming techniques, please refer to the Code Conventions for the Java Programming Language. 

3.7     Internal Documentation

Source for WebADE applications must be thoroughly commented, as described below.

Use Javadoc-style comments for all classes, methods, and class & instance variables, for all access levels.  Use "//" syntax for local variables in methods and for large blocks of code, whenever their purpose or behaviour is contextually unclear from the perspective of an experienced programmer who is otherwise uninvolved with the source code. Local variables in methods need not be commented if their scope is narrow and if their use is readily deduced from the context.

Comment lines should not extend beyond the 72nd character position of a page (assuming fixed-width font).

For more detailed specifications regarding this topic refer to the How to Write Doc Comments for the Javadoc Tool document.

3.7.1 Methods and Instance Variables

A multi-line Javadoc style comment that describes the purpose and/or behaviour of the method, its arguments, its return type, and any exceptions thrown explicitly within the method should precede each method.

Non-private class & instance variables should also be preceded by a Javadoc comment, which may be a single-line comment if brief enough, as in:

/** Holds the unprocessed input string */ 
public String rawInputString;

3.7.2 Code within methods 

Provide regular comments for all major subsections of code, using white space liberally, but not excessively, to distinguish these sections. The major subsections in a typical source file include the overall class declaration, the class and instance variables, the constructors, and the methods.

Comments are not required for obvious items, such as simple "getter" and "setter" bean pattern methods.

3.7.3 Custom Tags 

The Javadoc comment for a custom tag class should include a description on how to use the tag in a JSP, including the syntax, parameters, and where specifically the tag should be used within a JSP. An example is desirable.

3.8     Error Handling 

Applications should track errors, reporting internal problems to the log(s) using Commons Logging and reporting usage errors to the user.

Internal problems usually manifest themselves as Java exceptions and those can usually be handled within the code; otherwise, the problem is normally severe and requires operator intervention to correct.

Interaction errors occur when users attempt to perform an action incorrectly with respect to the "normal" flow of the application, such as entering invalid input into a form or attempting to access a page out of sequence. There are three main issues with either type of error handling:

• How to identify them 
• Where to respond to them. 
• How to display them.

3.8.1 Exception handling

When preparing to handle an exception, consider if it can be prevented. The following may provide some ideas:

• Provide default values for anticipated data when their availability and validity cannot be guaranteed.
• Make sure that input fields are trimmed of excess spaces.
• Use defaults to avoid null values unless specifically anticipated.

The sections below provide information on the how to identify the exception as well as how to properly react to the exception within your code.

3.8.1.1 Identification

Error handling should use Java exceptions wherever possible to ensure that the occurrence of errors is explicit and that they must be dealt with. This should include class constructors that cannot tolerate certain conditions (e.g., if a constructor must have all non-null arguments, it should throw an IllegalArgumentException so that the caller can abandon the object it attempted to create).

In general, specific exception classes should be defined to handle errors beyond what the standard Java API exception classes are intended for.

The Ministry core components add several exception classes. These are introduced in the technical document that comes with the WebADE components.

3.8.1.2 Response

Exceptions should be handled at the point in the code where it makes most sense to do so. For example, exceptions need not be caught "immediately" in the code when they are generated. Instead, methods that generate exceptions, either locally or through a call to another method, can be declared to throw that exception with the expectation that it will be handled "further down the procedure stack".

Since Java does not require handling of some exceptions, developers should be careful to make sure that they handle all exceptions that could occur. Unfortunately, this can sometimes demand the handling of a large number of exceptions, so grouping their "handler" code is encouraged as long as the granularity of response is sufficient. For example, the Exception type alone might be caught instead of several different types of exceptions individually, as long as it is sufficient to know that an exception occurred.

When an exception is thrown, the application should catch and attempt to process it immediately if the error can be easily handled at that point and if it makes logical sense to do so. An example of an error that would be easy to handle is if an input field in a Web browser form is incorrectly entered and the application specifies to replace erroneous input with default values. This kind of exception may not even be important enough to log.

3.8.1.3 Displaying

This section describes what types of error conditions should be reported upon detection and to who/where. Errors may be reported to application logs so that operators can review them, or to client display pages so that users are notified, or both. For information on how to log errors, see the Logging section. For information on how to display errors for users, see the User Interface Standards section

Errors should be logged if they indicate definite or potential problems with the application or system. They should also be logged if they indicate dangerous actions, whether malicious or not, that could compromise system integrity. Individual applications may call for additional logging of user activity for statistics gathering or monitoring. Critical messages should be sent directly to an operator using e-mail messages (via the ministry standard ENCC component).

Errors should be reported to the user if they indicate incorrect input or an inability by the system to process the current request. Other messages resulting from error conditions, such as temporary limitations on input or an impending system shutdown, should also be delivered to the user if possible. In no case should stack traces or Java-language-specific messages be delivered to users. The Java environment provides the means to capture events that would otherwise result in this kind of message being sent to users so that a more appropriate message can be returned instead.

Note: Developers should refer to the document "Guidelines for designing screens and dialogs for e-service applications" (via Ministry All Standards page) for additional information as to how error messages are to be formatted for display within Java Server Pages (JSP's).

3.8.2 Interactive error handling

3.8.2.1 Identification

Interactive errors are due to incorrect use of the application by users and can be detected during the processing of requests as part of the application's business logic.

3.8.2.2 Response

When interactive errors occur, the flow of the application may be affected depending on (i) the type of error, (ii) the type of request, and (iii) the current state of the user's session (possibly also the current state of the system). For example, a user might enter invalid input into a form, forcing the application to request that the form be resubmitted with corrected input.

3.8.2.3 Displaying

Regardless of how application flow is affected, users should be notified of errors that have occurred due to incorrect use of the application. For example, if a user has entered invalid form input, then that should be pointed out when the user is requested to resubmit the form.

Applications that use Struts can use the Struts error reporting feature. This consists of a list object into which applications can store error messages and a custom tag which inserts the messages into a JSP if the error list object is non-empty. The most common and straightforward approach is to insert the messages near the top of the page that is returned so that users see them before anything else. This is referred to as in-line message display for errors. Struts errors can also be displayed in the proximity of the individual field(s) that caused the error(s).

3.9     Logging 

The activity of applications must be logged so operators can trace errors and can monitor performance/usage issues. Developers must use the Apache group's Jakarta Commons Logging tool (Log4J) for logging in Java code.

Developers may configure Log4J as they see fit to support their own in-house development, but in preparing the delivery release, they must ensure that the logging is re-configured correctly for production. This means:

• sensitive information, such as passwords, are not logged
• logging is set to ERROR in the delivered source tar file. The logging config file must include the WebADE entries:

log4j.category.ca.bc.gov.webade=error
log4j.logger.ca.bc.gov.webade=error

• logging is not, repeat not, sent to standard output (i.e. stdout)
• log files are directed to /apps_ux/logs
• log files follow the format below

Log File Name: <appname>.log
Log File Type: Rolling Log File
Max Backups: 6
Max File Size: 1MB
Log File Format: [date/time] - [priority] - [thread] - [file:line] - message

• This Log File Format implies that

*.layout.ConversionPattern=[%d{ISO8601}] - [%-5p] - [%t] - (%F:%L) - %m%n

Developers may use the basic priorities provided with Commons Logging.  The following is a description of the levels and their uses as specified in the Commons Logging documentation:

• fatal - Severe errors that cause premature termination. Expect these to be immediately visible on a status console.
• error - Other runtime errors or unexpected conditions. Expect these to be immediately visible on a status console.
• warn - Use of deprecated APIs, poor use of API, 'almost' errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". Expect these to be immediately visible on a status console.
• info - Interesting runtime events (startup/shutdown). Expect these to be immediately visible on a console, so be conservative and keep to a minimum.
• debug - detailed information on the flow through the system. Expect these to be written to logs only.
• trace - more detailed information. Expect these to be written to logs only.

Again, ERROR must be set in the delivered source tar file.

 The following example illustrates how to implement Commons Logging in Java code:

... etc ...

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

... etc ...

public class Foo { 
    private static Log log = LogFactory.getLog(Foo.class);

... etc ...

public void doFoo( String msg ) { 
    log.info( "doFoo(String): This is a log statement" ); 
    if ( msg == null ) { 
        log.warn( "doFoo(String): parameter msg is null" );

3.10   User Interface Standards 

The Government of British Columbia has published two documents relating to the development of E-services:

• User Experience and Internet Standards (via Ministry All Standards page)
• Guidelines for designing screens and dialogs for e-service applications (via Ministry All Standards page)

In the context of these documents, E-service" means a transactional web application which delivers a business function for a government program - a program may have multiple e-services. The User Experience and Internet Standards apply to all government web sites that are accessible by the public over the Internet.

All screens and dialogs created for the Ministry must adhere to these standards to ensure a common user interface and common end-user experience for all web pages that are part of the Province of B.C. web presence. Where conflicts, if any, are perceived between the "User Experience and Internet Standards" (accessible via Ministry All Standards page) and this document, the Ministry Business Analyst should be consulted.

3.11   XML Compressors & Accelerators 

In instances where an application is required to perform heavy XML or GML processing, the requirements and the methodology proposed should be discussed with the IMB's Architecture Section before the design is finalized.

3.12     Java Naming Conventions 

3.12.1 Servlets 

The main servlet in a WebADE application must be called ControllerServlet. Any other servlet class must have the Servlet suffix in its name.

3.12.2 JavaBeans 

Each other bean class should have the Bean suffix in its name and should be a valid Java bean (i.e. is serializable, has getter+setter methods, and has a "no-arguments" constructor).

3.12.3 Tags 

Each custom tag class must have the "Tags" suffix in its name. The .tld file must be placed in the application's WEB-INF directory. Also, if the tag classes are contained in a separate library archive (jar) from the main application classes, this archive should be placed in the WEB-INF/lib directory.

Identification of tags to an application within the web.xml configuration file will use the application short name or webade as the prefix, as in: 

<%@ taglib uri="/WEB-INF/xyzTags" prefix="xyz" %> 

<%@ taglib uri="/WEB-INF/webadeTags" prefix="webade" %> 

3.12.4 Other Classes and Components 

Classes that extend other classes from standard WebADE components, including Struts, J2EE, and JDBC drivers, should be named consistently in a manner that reflects their association (and purpose). For example, an extension of the Struts action class org.apache.struts.action.Action should contain the suffix Action.

Other classes, as well as JSP pages and other targets, should be named using general conventions.

3.12.5 Java Package Naming 

Every servlet and accompanying Java class will belong to a Java package. One main package should be defined for an application, with possible sub-packages, containing all of the application-specific classes. The name of the main package should be the same as the short application name.

All WebADE packages must have the following prefix: 

ca.bc.gov.srm.app 

This will be followed by the short name of the specific application, in lower case to conform to package naming conventions. The package for the XYZ application would be:

ca.bc.gov.srm.app.xyz

The fully-qualified package name of a top-level action class in the XYZ application called MyStrutsAction would be: 

ca.bc.gov.srm.app.xyz.MyStrutsAction 

NOTE: Some classes, other than the standard tools, are intended to be common to more than one (and in most cases all) applications. These are the "common" WebADE classes, and those developed specifically for the Ministry will belong in or below the package: 

ca.bc.gov.webade 

3.13 Ministry Database Object Naming

The names of stored procedures and data tables should be prefixed by the application's acronym followed by the underscore character, as in: 

XYZ_getInspectionReport() // sample procedure

XYZ_AvailableReports // sample table name

Reference the Object Naming Conventions section of the Oracle Designer Standards and Guidelines for more detailed information in this area.  Standards for versioning of Data Definition Language (DDL) and database objects may be found in the Application Delivery Standards document.

[TOC]

4.     APPLICATION DESIGN 

4.1     Architecture Overview 

Ministry Web applications follow the Model-View-Controller (MVC) "type 2" design pattern; the MVC architecture was originally developed by Xerox PARC and was used as the framework for developing the GUI interface for Microsoft Windows and Apple's Mac O/S. A schematic representation of the Model-View-Controller scheme is shown in the figure below.

Model-View-Controller Scheme

The MVC "type 2" scheme as applied to Java application development consists of the following:

• A single controller servlet that receives, validates, and directs incoming requests; 
• Action classes that process requests (one class per request type), set data within corresponding state beans, and return results from the processed request; 
• State bean classes that contain state information for requests and/or results; 
• JSPs to present the outcome of a request.

The controller servlet determines which "action" is requested, uses the appropriate action class to process the request, and then uses the result to select the appropriate JSP to generate the presentation of the outcome of the request. The controller servlet provides the action class instance with the user-input data through an instance of the action-specific state bean. This bean is also retained in the user session for future use.

The action class will use data from the action-specific state bean and will perform transactions with the database to process the request. The action class next determines the result of its processing, acquires and populates a state bean instance corresponding to the result, then returns the result to the controller servlet. The state bean instance is retained in the user session for future use.

The JSP selected for output based on the processing result obtains the appropriate state bean instance from the user's session and uses this bean to generate the presentation content. The bean is passed to the JSP as a session attribute.

General JSP's are intended for presentation and therefore should only be used at the end of a chain of processing on the server. For example, an HTTP POST request will initially be processed by a "controller" servlet to make sure it is in the correct sequence. The servlet may use instances of other Java classes to further process the data. Finally, the servlet will hand off presentation processing to a JSP page. A general design goal for JSP's is that they contain no embedded Java code (i.e., Java scriptlets). Java beans and tags (standard and custom) should be employed to acquire the required content and formatting.

Variables should be defined in as narrow a scope as practical so that their purpose and content is easy to determine by a reader unfamiliar with the code. This strategy also minimizes coding errors. For example: Simple "one-off" variables such as loop counters should be defined within the loop structure. Variables needed in multiple locations, such as in a "try" block plus one or more of its corresponding "catch" blocks should be declared in a sufficiently higher level that they are "available" in each location.

4.2    Deployment Pattern

Ministry applications must conform to a standard Oracle/Java deployment pattern; any application components that are not accommodated in the standard pattern require an exemption as described in this document.

The standard Oracle/Java deployment pattern is laid out in an image file available at srmwww.gov.bc.ca/imb/3star/arch/images/TargetOAS.png. Further information on the patterns is available on the Ministry standards page under "Deployment Patterns".

4.3    Struts Framework  

The Ministry standard is to employ the Struts Framework for building web applications with Java Servlet and JavaServer Page (JSP) technology. Struts encourages application architectures based on the Model-View-Controller (MVC) design paradigm.

Struts includes the following primary areas of functionality:

• A controller servlet that dispatches requests to appropriate Action classes provided by the application developer.
• JSP custom tag libraries, and associated support in the controller servlet, that assists developers in creating interactive form-based applications.
• Utility classes to support XML parsing, automatic population of JavaBeans properties based on the Java reflection APIs, and internationalization of prompts and messages.

The Ministry provides a Struts Tile Kit as a common component for developers. The Struts Tile Kit implements the CIO’s “look and feel” standard.

4.4     Java Server Pages  

JSPs are intended for presentation and therefore should only be used at the end of a chain of processing on the server. For example, an HTTP POST request will initially be received and examined by a "controller" servlet. The servlet may use instances of other Java classes to process the request and store results of the processing. Finally, the servlet will hand off presentation processing to a JSP page.

A general design goal for JSPs is that they contain no embedded Java code (i.e., Java scriptlets). The common components of the WebADE include custom tags to help reduce the need for Java scriptlets and to promote a consistent look & feel. Developers should produce a custom tag library for an application and should use state beans to present data from a session or request context in a page to further reduce code.

4.5     Abstract Persistence Layer  - Object Relational Mapping

The Ministry currently permits three data access models for object-relational mapping (ORM):

• the Hibernate Core ORM tool for Java (but without the Automatic Schema Generation functionality);
• a manual mapping of objects to database tables;
• the use of Oracle stored procedures for mapping objects to database tables.

As noted above, the permission to use Hibernate Core does not extend to DDL Generation (i.e. Hibernate's Automatic Schema Generation). Database schemas and their objects are still to be designed and generated out of the Oracle Designer toolset.

The Ministry intends to consoldate these three options into a single standard object-relational mapping tool for Ministry applications. This is dependent on the migration from Java 1.4.x and will incorporate the Java Persistence API industry standard. This will be specified in a future release of the Java Web Development Standards.

[TOC]

5.     APPLICATION ENVIRONMENT 

The Ministry has implemented Java based web applications in a three-tier deployment based upon the Java 2 Platform Enterprise Edition (J2EE) specification. The Ministry standard is to build and deploy Java applications based on server-side processing; use of applets is not permitted in the design or construction of Ministry Java applications.

Component versions are listed in the Systems and Application Technology Standards Summary at http://srmwww.gov.bc.ca/imb/3star/docs/Systems_and_Application_Technology_Standards.pdf.

The Ministry is moving towards a conventional 3-tier deployment to conform to standards defined by the office of the CIO through the Security Enhancement Project.

5.1     Client Tier (Workstation)

J2EE applications use a thin-client interface. A thin-client is the distributed portion of the application where the client program does not process data, but instead passes data to the server for processing. 

All applications must be built using server-side java. No applications shall be built using client-side Java. Applications shall not have any dependency to client-side java runtimes such as JInitiator or JRE.

Operations such as database queries and execution of business rules are off-loaded to servlets or Java Beans (including EJB's) executing on the J2EE server where they can leverage the security, speed, services and reliability of J2EE server-side technologies. 

Developers building public web applications must ensure that their applications work with most common web browsers including Internet Explorer Version 4 and above and Netscape version 4 and above. Generated HTML code must comply with the HTML 4.0.1 Standard and XML should comply with the XML 1.0 Standard. Developers should refer to the BC Government "User Experience and Internet Standards" (accessible via Ministry All Standards page) as definitive source for browser and HTML standards. 

Developers building applications that use the Ministry's Internet Map Framework (IMF) must design their applications to use Microsoft's Internet Explorer (IE) version 6 or above; the IMF has been optimized for IE and will not function correctly when used with other browsers.

Note that e-Service applications may require support for 128-bit encryption.

5.2     Middle Tier (Internet Application Server)

A middle tier application server provides a runtime environment for the application and provides access to business functions and data. The Ministry standard is Oracle Application Server (OAS).

The Ministry is moving to a middle tier architecture in which the web server (Apache) tier is separated from the application tier. In the target model, the web server tier is in the DMZ and the application tier is behind the firewall is a segmented security zone.

5.3     Data Tier (Oracle Database)

Oracle is the chosen database platform of the BC Government and has been adopted as the standard database by most ministries.

[TOC]

6.     SECURITY 

The central component for managing application security is WebADE. For information on WebADE see www.webade.org. The WebADE supplies various API's for use in authorizing a user to an application.  This framework used in conjunction with the government supported global user directories (IDIR, BCeID and MyID) is used to authenticate and authorize all users of an application.

The security framework selected by the Ministry for web-based applications is intended to provide a secure, scalable mechanism for protecting the Ministry's data. The framework can be classified by one of the following categories of access:

• Public Access; no authentication required;
• Basic (a.k.a. Individual); identified but neither trusted nor verified;
• Personal (a.k.a. Verified Individual); Individuals with a confirmed identity; identified and verified
• Business: bodies outside of government that have a business relationship with government; trusted;
• Internal: internal users (e.g. employees); trusted;

These categories of access can be further differentiated as follows:

Public Access - must be query only; access to data is restricted through the use of a generic database account which remains hidden from the end-user at all times.

Basic (a.k.a. Individual, or MyID) - the identity of the party connecting to the Ministry's application server must be determined; the user is challenged to enter a unique username and password; user authentication will be effected against the MyID directory service.  A Secure Socket Layer (SSL) implementation is required to ensure confidential data sent from the client is encrypted. Database connections are to be made using a generic account in order to take advantage of database connection pooling.

Personal (a.k.a. Verified Individual) - the identity of the party connecting to the Ministry's application server must be determined; the user is challenged to enter a unique username and password; user authentication will be effected against the BCeID directory service. Personal is a person who has a personal rather than a business relationship with government (e.g. related to an individual's personal health records). Both query and insert/update operations will be permitted. A Secure Socket Layer (SSL) implementation is required to ensure confidential data sent from the client is encrypted. Database connections are to be made using a generic account in order to take advantage of database connection pooling.

Business - the identity of the party connecting to the Ministry's application server must be determined; the user is challenged to enter a unique username and password; user authentication will be effected against the BCeID directory service. The Business category applies to registered businesses, partnerships, proprietorships, foreign governments, etc. Note that Business may also apply to an individual whose interactions with government are of a business rather than a personal nature (e.g. buying products or services from the province). Both query and insert/update operations will be permitted. A Secure Socket Layer (SSL) implementation is required to ensure confidential data sent from the client is encrypted. Database connections are to be made using a generic account in order to take advantage of database connection pooling.

Internal - the identity of the party connecting to the Ministry's application server must be determined; the user will be challenged to enter a unique username and password; user authentication will be effected against the IDIR directory service. Both query and insert/update operations will be permitted. A Secure Socket Layer (SSL) implementation is required to ensure that confidential data sent from the client is encrypted. Database connections are to be made using a generic account in order to take advantage of database connection pooling.

Note: If the database account used by the application is for a named user (e.g. IDIR or BCeID), the username and IP address should be logged by the application.

6.1     Authentication 

User authentication for applications will be implemented using the BC Government's Enterprise Security Gateway, built on Netegrity SiteMinder.  The service provides the "Common Login Page" (CLP) that must be used by all applications requiring user authentication.  The CLP takes advantage of the Single Sign On (SSO) feature of Siteminder and also provides features such as expired passwords/password change and enforcement of Terms of Use agreements.

The SSO feature of the SiteMinder product allows a user to use multiple government e-services (SiteMinder enabled) while only having to authenticate on the initial request.  WebADE fully supports SiteMinder and its use is transparent to the developer.

Conceptually the Authentication (SSO enabled) process is as follows:

• The client attempts to access a resource within the application (welcome page) that is protected by Netegrity.
• Netegrity checks for SSO secure cookie (user already signed in via another service);
  • if cookie exists and user has access, the user will be granted access to the resource without having to log in again.
  • if cookie does not exist, the user is redirected to the Common Login Page.  Once logged in correctly, the user is then redirected back to the original application request (welcome page).

A "WebADE Developer Module" is available in order to emulate the government Siteminder environment for the purposes of application development. See www.webade.org.

6.2     Authorization 

Ministry standard is to use WebADE for authorization. General introduction and documentation on WebADE is available at http://www.webade.org.

In addition to identifying the client, an application must know whether or not a client is authorized for any request it makes to the application.

The WebADE provides several methods in its API, along with underlying constructs, to support the association of users with actions. The technical documentation provided with the WebADE software describes this through detail and example.

6.3     Database Access 

After a client has been authenticated by the Web server and authorized to the application, processing of the request begins. This might involve any number of transactions with any number of databases (usually just one). Applications access the database through "generic" proxy accounts, rather than through specific accounts corresponding to the client initiating the request. There is a proxy account for each unique level of access needed to the database. For example, there could be an "admin" account, a "power user" account, and a "general user" account.

These proxy accounts correspond to the roles defined for the application. Therefore, in the example just provided, there would be 3 roles: one corresponding to the "admin" account, one corresponding to the "power user" account, and one corresponding to the "general user" account. The names do not have to match, but are typically similar; they are associated by the WebADE configuration for the application. Note that since a 1-to-1 mapping exists between database proxy accounts and roles, any task requiring multiple data sources will have to use multiple roles (with suitably identifying names).

Note that all connections to the database are pooled. Therefore a pool exists for every type of connection (i.e., every proxy account) required by the application to every data source. Developers will not have to establish or manage these pools --- the core WebADE components will do this and will provide a simple interface to allow the application to acquire connections on demand (assuming it is authorized for the current action request).

Database connections are not created in application code; instead, they are acquired from the WebADE, which is responsible for creating and managing them. Therefore, account and database connection information should not appear in an application's code or local configuration.

Developers must contact their Ministry Business Analyst in order to obtain a list of proxy accounts and application roles that will correspond to connection pools to be used by the application. The developer will also need to provide minor configuration information for the development and deployment environments such as # of initial connections, data source URL, id, password, etc. The details on how to do this relatively simple task are provided in the WebADE technical documentation.

6.4     Ministry Database Role Naming

The names of database roles subject to naming standards. Refer to the Oracle Designer Standards and Guidelines for more detailed information in this area.  The Oracle Roles must be reflected in the submitted Oracle Designer data model as defined in those standards.

6.5     Enforcing Application Flow 

Normal flow for application requests that involve processing (i.e. not including fetches of static items such as image files) should follow the Model-View-Controller pipeline as described in the Architecture overview section. The presence of JSPs makes this even more important because they have the capability to acquire or present information intended for a restricted audience. A clever user can directly access a JSP, bypassing the normal pipeline through the controller servlet and the Struts action processing classes.

The WebADE provides a simple means to avoid this problem:

• A custom tag is available to verify that a request has followed the MVC pipeline. 
• If included near the top of a JSP, this tag will perform the verification before allowing the remainder of the JSP to be processed.
• If the verification fails, then the tag will direct the request to a configurable target (e.g. an error page). 
• The tag can be included in any or all JSPs where this check is required.

6.6     Forbidden Characters in URLs 

In order to protect applications from Cross-Site Scripting attacks, the Enterprise Security Gateway (Siteminder) will reject URLs that contain certain characters in either the base URL or the query string (parameters).

Applications must not use any of the following characters in URL or query string (parameters), whether escaped or unescaped:

• single quote ('), character %27
• left angle bracket (<), character %3c
• right angle bracket (>), character %%3e

Note that escaping of the characters does not mask them from detection. Thus, all of the following sequences will be rejected as they all resolve to a single left angle bracket (<): %3c, %253c, %25%33%43, %25%32%35%33%43, etc.

[TOC]

7.     REPORTS 

The Ministry has selected Oracle Reports 10g as the standard tool for report generation.  Developers can develop Oracle Reports using the standard client-side reporting tools (i.e. Oracle Reports Builder 10g) and then deploy the report modules on the Ministry's dedicated reports server.

Standards for developing web based Oracle Reports for the Ministry may be found in the document Oracle Developer Standards and Guidelines. The Ministry has also developed standards for the delivery and deployment of web based Oracle Reports; these Reports Server Delivery Standards are available to authorized users on the Ministry's Intranet server.

7.1     Designing Reports 

Details on designing reports, including Ministry standards, can be found in a separate document on the Application Development Web site.

7.2     Charting 

The Ministry has deployed the JFreeChart library as part of the standard Oracle Application Server 10g (OAS 10g) configuration. This is considered mandatory for charting in Ministry applications. Further information for the product can be found using the link below: 

• JFreeChart 

[TOC]

8.     EMAIL 

The Ministry provides a common component called ENCC (Email Notification Common Component) for Java Applications that wish to send notifications using email. This common component is considered mandatory for sending email. The ENCC package is available (intranet only) at http://srmgww.bcgov/landinfobc/imb/software/apps/encc/.

[TOC]

9.     COMMON COMPONENTS

9.1 Mandatory common components

Any component listed in the Systems and Application Technology Standards Summary document is mandatory when the functionality it provides is a requirement of the application. This includes but is not limited to:

• WebADE for security
• ENCC for email
• JFreeChart for charting
• Log4J for logging (mandatory in all applications)

9.2 Additional Java Libraries

A list of standard java libraries is provided in the Systems and Application Technology Standards Summary. Use of any other third party library, whether commercial, GPL or from any other source, is considered outside of standard and requires an exemption as described in this document.

[TOC]

10.     DOCUMENTATION 

10.1     Release Notes 

A properly constructed, complete, and up-to-date release notes document is vital for every release. Ministry personnel rely on this document to determine what work must be done to ensure successful deployment of a release.

10.2     Application Use 

A single general user guide will be provided for the application. Normally this will be the responsibility of the application custodian to produce in consultation with the developer; however, it may be included in the specific deliverables for the project.

The user guide will be written in Microsoft Word format according to a template, which will be available on the component workbench along with special instructions for creating the document according to Ministry standards.

10.3     Help 

The use of help screens in E-service applications developed for the Ministries should conform to the "CIO Guidelines for designing screens and dialogs for e-service applications" document (accessible via Ministry All Standards page) under the sections "Small Help window" and "Large Help window".

10.4     Application Configuration 

Two types of documentation covering the configuration of the application are required:

• A set of technical instructions for compiling the application, referred to as the Readme in the Java Delivery Standards
• A description of the configuration to assist non-programmers in understanding the functional composition of the application.

10.5     Instructions for Compilation 

The Ministry uses the Apache Jakarta Ant utility to compile and build Web applications. Any special requirements for compiling the application must be clearly documented. This will include:

• A description of the platform requirements
• Environment settings
• Organisation of all software components.

The current Ant version is listed in the Systems and Application Technology Standards Summary at http://srmwww.gov.bc.ca/imb/3star/docs/Systems_and_Application_Technology_Standards.pdf.

10.6     Design Revisions to As-Built

A final deliverable for an application is a revised version of the application's System Design document. If there are any deviations from the System Design document submitted to the Ministry prior to commencement of the system build (e.g. database version), these should be reflected in a re-delivered version of the System Design. This final revision should be versioned as a minor point release - e.g., a final revision of the 3.2.0 design document (for version 3.2.0 of the application) would be versioned as 3.2.1.

[TOC]