Package org.bibeault.frontman

Bear Bibeault's Front Man™ (called simply "Front Man" from here on) is an ultra-lightweight framework (if you could call it that) for quickly creating web applications of all sizes.

See:
          Description

Interface Summary
Command Interface that defines a unit of controller execution: a "Command".
CommandContext Defines the interface for an object instance passed to the execute() method of a Command instance.
 

Class Summary
CommandBroker A simple Front Controller using two properties files to define command verbs and view names.
CommandContextImplementation A context object that maintains the state information for the invocation of a command, as well as making various useful methods available to Command implementations.
 

Enum Summary
ScopedContext Enumeration modeling the four context scopes.
 

Exception Summary
CommandNotFoundException An extension of ServletException that is thrown by the Command Broker in the event that an invalid command verb is referenced.
ViewNotFoundException An extension of ServletException that is thrown by the Command Broker in the event that an invalid view name is referenced.
 

Package org.bibeault.frontman Description

Bear Bibeault's Front Man™ (called simply "Front Man" from here on) is an ultra-lightweight framework (if you could call it that) for quickly creating web applications of all sizes.

The purpose of Front Man is to provide an ultra-weight web framework that adheres to the principle that the answer to the question "How big should a framework be?" is "Barely enough". It aims to provide the basic plumbing for Model 2-patterned web applications while achieving the project goals of:

Setup

Overview of set up steps:

  1. Drop the Front Man jar file into your application's WEB-INF/lib folder.
  2. Add the <servlet> and <servlet-mapping> entries for the Command Broker servlet in the deployment descriptor (web.xml).
  3. Create two properties files to define the command verbs and view names respectively.
  4. Start writing pages and commands.

Adding the jar file to the application

Once you have obtained the frontman-n.n.n jar file (where n.n.n is the most recent revision level of Front Man), just drop it into your web application's WEB-INF/lib folder.

No other jar files are necessary.

Set up the Deployment Descriptor

The Front Man front controller, the CommandBroker class, must be established as a servlet in the deployment descriptor, and mapped to an approriate URL pattern. Initialization parameters specify the path to the two required properties files: one that associates command verbs with command class names, and one that associates view names with the context-relative URL for view resources such JSP or HTML pages.

A typical such declaration might look like:

<servlet>
  <servlet-name>CommandBroker</servlet-name>
  <servlet-class>org.bibeault.frontman.CommandBroker</servlet-class>
  <init-param>
    <param-name>commandVerbsResourcePath</param-name>
    <param-value>/WEB-INF/CommandVerbs.properties</param-value>
  </init-param>
  <init-param>
    <param-name>viewNamesResourcePath</param-name>
    <param-value>/WEB-INF/ViewNames.properties</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
  

The commandVerbsResourcePath and viewNamesResourcePath init parameters are required and must specify the path where the property files can be found. These path values must begin with "/" and are considered relative to the context root.

The servlet mapping for this controller is typically along the lines of:

<servlet-mapping>
  <servlet-name>CommandBroker</servlet-name>
  <url-pattern>/command/*</url-pattern>
</servlet-mapping>
  

The command prefix can be any word you would like, but the pattern for the mapping must be as shown. Use of the conventional prefix command is highly recommended unless it would cause a conflict with a URL pattern that you are not at liberty to change.

This mapping establishes URLs to the various commands you will define as:

http://yourserver.com/contextPath/command/commandVerb
  
where:

So, if you have defined a command verb such as doSomethingWonderful in your properties file, the URL to execute that command would be:

    http://yourserver.com/contextPath/command/doSomethingWonderful
  

Set up the Command Verb and View Name Properties Files

The configuration files that map command class names to their verbs, and view names to their resource URLs, are refreshingly simple. They are merely run-of-the-mill Java properties files.

The Command Verbs Properties Files

The command verbs properties file is used to associate command verbs with the command classes that should be executed when that verb is used in a URL to the Front Man command broker servlet. This file is identified to the system via the commandVerbsResourcePath init parameter to that servlet.

Within the properties file, each entry associates a command verb with the class name of the concrete command class that is to be executed for that verb. Some typical entries in this properties file could be:

doSomethingWonderful=com.whatever.someproject.commands.DoSomethingWonderfulCommand
login=com.whatever.someproject.commands.LoginCommand
viewHomePage=com.whatever.someproject.commands.ViewHomePageCommand
viewLoginPage=com.whatever.someproject.commands.ViewLoginPageCommand

Note the naming patterns used for command verbs and for the corresponding command classes. It is highly recommended to follow these conventions as it has proved to keep URLs and command code as readable and understandable as possible. Notably:

You are, of course, free to come up with your own conventions, but time and usage has proved that the above simple conventions keep things tidy and understandable.

The View Names Properties Files

The view names properties file is used to asscoiate view names with the context-relative URLs that locate the resource (usually a JSP or HTML file) invoked when the view name is referenced. This file is identified to the system via the viewNamesResourcePath init parameter to the command broker servlet.

View names are most often referenced from within commands as the target of a forward or redirect operation. By abstracting the view names from their physical location, changes in the view resource hierarchy will not require any changes to the code as physical URLs are not used to reference the resources.

Within the properties file, each entry associates a view name with the location of the named resource. Some typical entries in this properties file could be:

ErrorPage=/errors.jsp
HomePage=/WEB-INF/pages/home.jsp
LoginPage=/WEB-INF/pages/login.jsp
ProfileEntryForm=/WEB-INF/pages/profile-entry.jsp

As with command verbs, a recommended convention has been established that seems to help keep things tidy:

Note that in this example most of the pages are hidden in the folder hierarchy under the WEB-INF folder. This is typical of Model 2 web applications where is it highly unusual to visit a view without first going through a controller. Placing the JSP files under WEB-INF prevents any direct access via URL.

Naming Tips and Tricks

In some projects it may make sense to "namepsace" the command verbs and view names in the project. This can easily be performed by adding a namespace suffix to the verb or name and using the period character as a separator.

An example where such segregation is useful might be a web application that requires authentication. Most pages in the application require a logged in user, but obviously some pages, such as the login form itself, should not require a logged in user. Commands and views requiring authentication could belong to one namepsace, and non-authenticated commands and views to another.

It would then be a simple matter to write a servlet filter that would use the namesapce to determine if the command being invoked required authentication or not by looking at the namespace.

There are many other situations in which namespacing your command verbs and view names might be useful. It's a handy tip that can make your code and life simpler.

Write Your Command Classes

That's all there is to the setup. You are now ready to start writing your application, particularly the command classes.

All commands must implement the Command interface which consists of a single method to be called when the Command is to perform its function. A context object of type CommandContext is passed to this method which not only gives the method access to its environment, it provides a bevvy of useful methods that the Command can take advantage of; methods to easily forward or redirect to other Commands or views via their abstracted names, for example.

Write Your Pages

Go ahead and write your JSP pages. There is no required "goo" that you must put on the pages in order for them to work. No required tags. No required declarations. No required directives.

The use of JSP scriptless pages that employ the EL and JSTL to best advantage is highly recommended.

There are a small handful of useful custom actions and EL functions defined in the frontman.tld tag library (which is in the META-INF folder of the Front Man jar file, and therefore automatically available to your application), but use of them is entirely at your own discretion.

See the TLD documentation for details.

Release Notes

1.5.0, November 6, 2006
1.4.0, July 14, 2006
1.3.0, March 22, 2006
1.2.0, March 3, 2006
1.1.0, February 25, 2006
1.0.1, February 21, 2006
1.0.0, February 10, 2006
Initial version.