Chapter 7

A Model Intranet app


CONTENTS


model \'mäd-l\ n:a pattern of something to be made

Introduction

Intranet apps are like a corporate app suite. These include word processors, project planners, spreadsheets, and many other useful and productive apps. They encompass all departments and touch many types of data. But unlike the business productivity app suites available today, your intranet apps should all share a common foundation. Creating a suite of apps from scratch is tedious and boring. Cutting and pasting code is easy, but that goes against all object-oriented coding practices. What is needed is a basic structure from which to build your apps. This foundation should be flexible, stable, and extensible. This chapter introduces you to four standards that all of our apps share. These standards provide a flexible, stable, and extensible foundation for developing intranet apps. These four standards together produce a prototype or a model app that can be used as a base when developing apps.

A Quick Overview of Intranet apps

On an intranet, the apps that are built share much of the same functionality. Sure they all do different things but they also do a lot of the same things. These commonalties should become the foundation for your intranet app framework. They are the base and are truly your app standards. Our primary design goal is to provide a set of standard app features. These features create a familiar atmosphere for all your intranet apps. Familiarity provides users with a sense of comfort because they don't have to learn an entirely new program. Apple capitalized on this idea years ago when it introduced the Macintosh computer. If you learned how to use the Mac, then you knew how to run almost every Macintosh app written. It was the consistency and adherence to set standards that made this possible. Microsoft Windows has since capitalized on the same concept. The design presented here is not quite a Macintosh but what it provides is something similar: consistency. The following four standard features are what we strive to provide in the model intranet app design:

Let's examine each goal individually, show an example, then point you in the right direction to find more information regarding each particular standard.

Configuration File Processing

Using configuration parameters in coding can be a real hassle unless a stable foundation is in place. Generally you end up coding a new configuration scheme with each app. What we can create is a class that provides a solid method of getting configuration parameters. This method encompasses configuration files on disk and overridden parameters passed in by way of the command line of the app. The configuration file in Listing 7.1 is an example of the kind of configuration files the apps have.


Listing 7.1. A sample configuration file.
# Configuration file for Employee Maintenance
WindowTitle=Employee Maintenance
server=tcp-loopback.world
user=munster
password=

At the start of the app, we read the configuration file into memory. These parameters are merged with any configuration parameters that are passed in by way of the command line. The apps then need a consistent method of retrieving these parameters from the configuration parameter storage area. We should model the retrieval method after the method used in regular Java applets.

Note
, "Utility Classes," discusses the ConfigProperties class which implements these design goals.

Logging to Disk or Screen

For tracking problems during the development cycle and for error logging after your app has been deployed, a log file is just the ticket. A common log file is even better for all of your apps and users. A common log file is easily searched and filtered for errors. This standard logging mechanism is the first standard feature that we need to supply. To facilitate such a log file, we need to create it on disk. The log file is appended to each time; it is never overwritten. If we overwrite the file, then information from a previous session can be lost. You know how annoying that can be. But what if the disk log fails to open, or if it can't be written to? Well, we need a backup log. These failed log entries should go to the screen. This screen logging facility produces the same log information to a window, or using the System.out facility. When an app fails to create a disk log, all log output goes to the screen. Also, this screen log is used automatically if no disk log is specified or if there is an error.

Note
System.out is a Java system object. It is an alias for the console in Windows. In UNIX it is an alias for stdout.

Common Log Entries

The entries in the log file should follow a standard, one that is easy to view and search. This format should be used across all of your intranet apps, and possibly your non-intranet apps as well. This log file format should be simple enough so that other programs might even use it. You might find in the future that you use a third-party network management tool that can monitor your intranet apps and their log files. These tools can be a lifesaver in a pinch, so why not think about their needs as well? Therefore, the following log file format is what to go with as the design. It includes all the information needed in an easy-to-use format: app|user|date|level|entry where

app is the name of the app
user is the user who is running the app
date is the date of the log entry
level indicates the severity of the entry.

Six predefined levels are available: debug, informational, notice, warning, error, and fatal. Each is denoted in the log by the first letter in its name. D for debug, I for information, and so on. Listing 7.2 shows some sample log entries.


Listing 7.2. Sample log entries.
Employee|960609|I|app [Employee] started at Sun Jun 09 22:27:33 1996
Employee|960609|I|Port = 4333
Employee|960609|I|Server = mars.mcs.net
Employee|960609|I|Title = Employee Maintenance
Employee|960609|I|app [Employee] ended at Sun Jun 09 22:28:38 1996

At startup, all of the intranet apps write several things to the log:

At shutdown, the app writes a corresponding entry to its startup message. This is shown in Listing 7.2, also.

Note
, "Logging Classes," discusses the DiskLog and ScreenLog classes which implement these design goals.

Database Connectivity

Connecting to databases with Java is a key point in your intranet app design stage. Various methods are currently available. Some are HTTP server extensions that return data in HTML format. Others are non-portable system-dependent solutions. A more Java-like option is JDBC.

Note
JDBC, along with other database connectivity options are covered in depth in , "Database Connectivity Options."

It appears today that JDBC is the strongest supported database standard for Java. For this reason alone, JDBC is chosen as the database connectivity package for the intranet apps in this tutorial. Using JDBC allows us to choose from almost any database and provides the flexibility to change databases when coding is complete. To simplify database connectivity just a bit, we need to create a class that encapsulates the more monotonous aspects of connecting and disconnecting from a database server. This new class provides a connection strategy that is simple to use and easily extensible. This class also encapsulates much of the rudimentary JDBC initialization and cleanup. All we need to do is extend this class for each database we need to connect with. Listing 7.3 shows how easy the class is to use.


Listing 7.3. How you should use your Database Connector Class.
// Make the connection...
if ( myConnector.connect( "munster", "hermy", "tcp-loopback.world" ) )
{
// Connection successful...
}
else
{
// Connection failed...
}

As you can see, the connect() method is called with the connection parameters necessary to make the connection. The exception handling is handled for you in the class, returning nothing but a simple true or false. This indicates the connection state as well.

Note
, "Database Classes," discusses many database classes. One of them is the DBConnector class. This class implements many of these design goals.

Look and Feel

The final standard about the intranet apps is that they should have a consistent look and feel. This is achieved through the use of standard font, and a consistent layout of components. Screenshot illustrates the standard look and feel of the model intranet app. This app is the "Hello World" example presented in , "User Interface Classes." Screenshot : The standard intranet app look and feel. Referring to Figure 7.1, you see the following standard app attributes:

You might notice that there is a menu shown in Figure 7.1; however, no menu is shown as a standard look and feel. This menu varies from app to app. It is not fair to impose a rigid menu structure on apps that might not even need a menu. Therefore, menus are not part of the app design.

Note
discusses many classes which implement these design goals.

Coding Style Notes

There are several things about the source code in this tutorial that might be different from other Java tutorials that you have seen. A good percentage of the code styles here are simply done for readability. Here is a list of what I think is different and superior:

Let's go over each individually and show some examples.

Code Layout

The code in this tutorial is laid out, or rather formatted, in a manner that might be different from other Java tutorials that have been published. The format used in this tutorial is my personal coding style for C and C++. I feel that this format is more readable and easier on the eyes and brain. My style differs in the ways described in the next few sections.

Parentheses and Code Blocking

The original Java samples and source code that come with the JDK use what is known as the K&R style of code blocking. This style places the open parenthesis at the end of the statement that begins the block. Listing 7.4 is an example of K&R style.


Listing 7.4. The BadKittyclass-K&R style.
public class BadKitty extends Kitty {
public BadKitty( int clawCount ) {
}
}

K&R stands for Kernigham (Brian) and Ritchie (Dennis), the creators of the C coding language. In their (in)famous tutorial, The C Programming Language, this was the manner of code layout, hence the name. In this tutorial however, the parenthetical style used is that the braces match up in the same column. This style is easier to read and more clearly marks the blocks of code. Listing 7.5 illustrates this point.


Listing 7.5. The BadKittyclass-Non-K&R style.
public class BadKitty extends Kitty
{
public BadKitty( int clawCount )
{
// Code goes here!
}
}

Using Tabs Versus Spaces

Whenever code is indented, tabs are used. Tabs keep code aligned and are portable between operating systems. The tab stops for the code in this tutorial are every four spaces.

Liberal Use of Spaces

As you may or may not know, the compiler really doesn't care about spaces in your code. All white space and comments are stripped out before the actual compilation is done. Adding more spaces than necessary is another readability issue. Wherever possible, spaces are used. This might seem a bit lengthy. However, you will see the improvement. The following line of code uses no spacing:

blackBoxToUse=(myBlackBox==null)?defaultBlackBox:myBlackBox;

And this one spaces things out nicely:

blackBoxToUse = ( myBlackBox == null ) ? defaultBlackBox : myBlackBox;

Look how much more readable the second line is! You can quickly parse the line and understand what is going on. You don't spend time parsing.

Multiple Lines Per Statement

In an effort to make the code more readable, all class and function declarations are split into two, three, or four lines. The number of lines depends on the number of elements that make up the statement. The rules are different between class and function declarations.

Class Declarations

Class declarations in this tutorial can appear on up to four lines and are in the following order:

[access] class
name
[extends super_class]
[implements interface]

Usually this declaration is made on a single line. However, by splitting it up into multiple lines you can immediately learn information about the class without even reading the declaration. Listing 7.6 illustrates the class declaration.


Listing 7.6. A beautiful class declaration.
public class
FileDate
extends Date
{
...
}

Function Declarations

Functions are declared in much the same manner as classes. However, the function name is always on the second line, and all other information about the function is on the first line. Function declarations are always two lines long. The declarations are in the following format:

[access] return_type
function_name
( arguments )

Listing 7.7 shows a complete function declaration using our described style.


Listing 7.7. A well-styled function declaration.
public String
toFileString()
{
String retString = "";
int m = 1 + getMonth();
int d = getDate();
int y = getYear() % 100;

if ( y < 10 )
retString += "0";

retString += y;

if ( m < 10 )
retString += "0";

retString += m;

if ( d < 10 )
retString += "0";

retString += d;

return( retString );
}

Comments

Comments are a sore issue with many programmers. A friend of mine (Hey Bill!) used to tell me that the only purpose comments serve are to amuse the compiler. In some cases, he might be right. However, to better document the code in this tutorial, comments are everywhere. Generally the comments are restricted to a single line, right above the line of code to which it pertains. This is common practice. In addition to the single line comments, I like to distinguish chunks of code from others with the use of a block header. It serves no purpose other than to segregate blocks of code visually. Listing 7.8 shows an example of such segregation.


Listing 7.8. Comments really do improve the readability of your code!
//****************************************************************************
//* Package &nb sp; *
//****************************************************************************

package jif.util;

//****************************************************************************
//* Imports &nb sp; *
//****************************************************************************

import java.util.Date;

//****************************************************************************
//* Date *
//****************************************************************************

/**
* An extension of the default Java Date.
*
* @see java.util.Date
*
* @version 1.00, 1 May 1996
* @author Jerry Ablan, munster@mcs.net
*/

public class FileDate
extends Date
{

//****************************************************************************
//* toFileString &nbs p; *
//****************************************************************************

/**
* This method returns the date in a format suitable for using in
* file names. This format is YYMMDD, where YY is the year, MM is the
* month, and DD is the day.
*
* @see java.util.Date#toString
*/

public String
toFileString()
{
String retString = "";
int m = 1 + getMonth();
int d = getDate();
int y = getYear() % 100;

if ( y < 10 )
retString += "0";

retString += y;

if ( m < 10 )
retString += "0";

retString += m;

if ( d < 10 )
retString += "0";

retString += d;

return( retString );
}
}

Code Order

Finally, there is code order. Again, some of the Java tutorials published have different orders. The oddest order I've seen is that all class variable declarations are below all of the function declarations. This is quite odd, and not at all like any other coding language. I've tried to keep the coding style similar to C and C++ for clarity. All the source code in this tutorial lays out in the following order:

  1. Package name
  2. Imports
  3. Class declaration
  4. Class members declaration
  5. Class functions

All class functions lay out in a similar manner:

  1. Function declaration
  2. Function variables
  3. Function code

Maintaining consistency throughout the code considerably improves readability.

Summary

This chapter introduces the four app design standards that are implemented in the next four chapters. These standards produce configuration processing, common logging, database connectivity, and consistent user interface. Through the use of these standards, the intranet app development will just fly by! In the following chapters, the standards set forth in this chapter are implemented.


Java ScreenshotJava ScreenshotJava ScreenshotJava Screenshot



Comments