Controllers provide a number of advantages:

Controllers are generally run in a servlet context. This means that they remain resident in RAM, and multiple threads run through them. Controllers must be thread safe in this context. Thread un-safe code is the 'bogeyman' that haunts any servlet project, because the bugs are often intermittent and hard to reproduce and fix. And they happen under load, when stability is particularly valuable. Part of the EJB design is to remove multithreading as a programmer responsibility, by having pools of EJB objects and running their methods in a strictly controlled manner, cloning EJBs if necessary, avoiding concurrency. However, EJBs engender their own complexity too, and for some purposes, there can be smart applications of the concept of one object, many threads.

The following references and cautions apply to Controllers:

The controller architecture is independant of the method used to present the outputs of the controller to the user - User Interfaces (UI) are available for several different web-application technologies, including:

Special support facilities exist to make using Controller objects easier in a web forms-based environment, providing the ability to validate forms, especially against DB Objects, suppliing error handling and retry abilities, and provide the ability for the user to navigate between forms easily.

DBObjects are not Enterprise Java Beans. However, if you have Expresso Framework 5 downloaded on your webserver, you can work with Enterprise Java Beans if you want to. There are no restrictions. However since Expresso does not create or manipulate EJBs directly (at the moment), but instead talks to the database using DBObjects, you will have to do the extra work yourself. Briefly, EJB technology is designed to be distributed component based, transaction safe, scalable across virtual machines, and portable across J2EE application servers. This is important if you run Enterprise mission-critical applications. In detail, EJB provides the following features:

DBObjects (in Expresso 5.X) do not have any of the above Enterprise features. However DBObjects are better than nothing if you have no Object Relational layer. DBObjects are good because you can manipulate database tables within Java, the language we all love. DBObjects are an implementation of a well-recognized software design pattern (see Mark Grand, J2EE Enterprise Patterns, Wiley 2001) For more info look at TheServerSide.com for Chuck Cavaness' preview book chapter on ``EJB and Struts''.

An Input object is a request from the Controller for the client to supply some information. Some additional attributes of the Input object can provide some formatting "hints", which the client may or may not use, but the actual presentation to the user is up to the UI portion of the application. Input objects may also provide "valid values", which allow the UI to present a list of values to the user for him/her to select from. Again, the nature of this list is up to the UI layer.

Normally, if a particular state of a Controller requests an input, the subsequent states will require it as a parameter.

An Output object represents a response from the Controller to be presented to the user. This can be as simple as a single String, or as complex as a nested tree of items, that the UI might choose to represent as a table, for example. Every Output may have zero or more other Outputs "nested" within it, to represent structure in the returned items. For example, an Output called "invoice" might have a number of "line item" outputs nested within it.

Output's also have "Attributes", which are a group of arbitrary name/value pairs that help further describe the Output to the client application - for example, the "invoice" Output might have an attribute called "count", which might give the number of line items associated with this invoice.

A Transition object represents a choice for the client to transition to a new state - only states that are appropriate given the current state and allowed given the current user's permission have action items generated for them.

For easier use in JSP's (and other environments) where there are a lot of inputs, outputs and transitions, the concept of "blocks" is available to help keep the controller response organized.

A Block object's purpose is to act as a container for other ControllerElement objects such as Transition, Input, Output and other Block objects. The idea behind a Block object is that it is a logical grouping of other ControllerElement objects for presentation purposes. Think about a HTML page which has multiple sections (not necessarily HTML frames), with each section having its own text messages, buttons/links and forms.  by name, which Input, Output and Transition items were to be grouped together.  With Block objects,  the Controller writer would  group each logical set of Input, Output and Transition objects within a Block, with each logical section of the HTML page getting allocated its own Block.  The JSP writer in turn, would simple get an Enumeration of all the Blocks from the controller,  iterate over each ControllerElement and then create appropriate HTML for each object.  Since a Block returns each ControllerElement in the order it was put into the Block, if a JSP writer did not care, the ControllerElements could be placed in the same order that the Controller writer put them in.  Of course, the JSP-writer is still free to access each ControllerElement by name as previously and then do a custom HTML presentation.

Here's an example.  Let's assume that the HTML page consists of several lines of messages, followed by some links, followed by a form. In some Controller.someState():

//The first logical block 
Block b1 = new Block("Header"); // The parameter sets the name of the Block 
Output o1 = New Output("Msg1", "This is message 1"); 
b1.add(o1); //Nest the action within the block 
Output o2 = new Output("Msg2", "This is message 2"); 
b1.add(o2); 
Output o3 = New Output("Msg3", "This is message 3"); 
b1.add(o3); 
addBlock(b1); //Add the block to the controller. 
 
// The second logical block 
Block b2 = new Block("Links"); 
Transition a1 = new Transition("Take action 1", "/servlets/ControllerServlet?trx=......."); 
a1.setName("Transition"); 
b2.add(a1); 
Transition a2 = new Transition("Take action 2", "/servlets/ControllerServlet?trx=......."); 
a2.setName("Transition"); 
b2.add(a2); 
Output o4 = new Output("Msg4", "Please choose one of the links above"); 
b2.add(o4); 
addBlock(b2); 
 
// The third logical block 
Block b3 = new Block("Form:Form1"); 
Output o5 = new Output("Msg5", "Please fill in the information below"); 
b3.add(o5); 
Input i1 = new Input("Name"); 
i1.setLabel("Name"); 
i1.setType("text"); 
b3.add(i1);
Transition a3 = new Transition("Submit", "/servlets/ControllerServlet?controller=......"); 
a3.setName("Submit");
b3.add(a3);
addBlock(b3);

In a corresponding HTML generator (whether it is another utility class, a bean to be accessed from a JSP, adapter classes for WebMacro/Freemarker, or a JSP itself), one would write something similar to:

 String blockName = ".....";    // Name as in the controller 
 for (Enumeration e = controller.getBlock(blockName).getContents().elements(); 
                  e.hasMoreElements(); ) { 
     ControllerElement oneElement = ( ControllerElement)e.nextElement(); 
     if (oneElement instanceof Transition) { 
         handleTransition((Transition)oneElement); 
     } else if (oneElement instanceof Input) {
         handleInput((Input)oneElement); 
     } else if (oneElement instanceof Output) {
         handleOutput((Output)oneElement); 
     } else if (oneElement instanceof Block) {
         handleBlock((Block)oneElement); 
     } else { 
         throw new Exception("Cannot handle object of type:" 
                            + oneElement.getClass().getName()); 
     }
}

One could also use the controller.getBlocks() call to get an enumeration of all the Block objects to iterate over. Note that the exact mechanics of the HTML output generation is not shown here to keep the example simple and to the point.

There are several types of controllers available, all extending the base class com.javacorporate.common.controller.Controller. They each have a specific use:

The following table lists some of the important Controller classes included with Expresso. All of them belong to the com.jcorporate.expresso.services.controller package.

In the diagram above, you see a simple representation of a Controller with 5 states. Let's follow the execution of this controller to see how the interactions work:

This example is of course very simplistic, and a real controller would have many other connections between states, and probably more complex behaviors in each state, but it serves to illustrate the use of the Controller model. It is important to realize that this Controller could actually be used in a number of different ways - for example, from a JSP page that showed a list of students enrolled in a particular course, an authorized user could select a link that said "Show Grades". This link might invoke our example controller, but not at the initial state: It would go directly to the "display grades" state, and assuming that permissions were OK, and that the course and Student Id were supplied (as these are the required parameters to enter this state), our sample controller would respond with the same output that it provided when it was invoked in the way we describe above. This kind of "interaction" with other controllers increases the utility of the Controller model considerably, and promotes re-use without sacrificing portability or data integrity.

Of course, a Controller object typically interacts with one or more database objects (or other controllers) to do it's job - but these interactions are completely concealed within the states themselves, and the client does not need to be aware of them.

If states are to be coded "internal" to the Controller class, then the state objects are created internally in the constructor of the method. You then define your state handler with a particular naming convention. An example of this is below:

/** 
 * Our constructor declares the states this 
 * controller supports 
 */ 
public DBSecurityMatrix() { 
   State prompt = new State("prompt", "Prompt for Schema and User Group"); 
   addState(prompt); 
   setInitialState("prompt"); 

   State dbobjmatrix = new State("dbobjmatrix", "Enter/View Database Object permissions"); 
   dbobjmatrix.addParameter("SchemaClass"); 
   dbobjmatrix.addParameter("GroupName"); 
   addState(dbobjmatrix);
} /* DBSecurityMatrix() */

ControllerResponse runPromptState(ControllerRequest request, ControllerResponse response)
        throws ControllerException {
    return response; 
}
 
/*
  runPromptState(ControllerRequest, ControllerResponse);
*/

In the code above, the State object is create, and then the "addState" method used to "register" that state as belonging to the controller. The logic for the state, however, is coded into methods built right into the controller object itself.

To do this, you create a special function that follows a particular naming convention. The naming convention is similar to that of the JavaBeans naming convention, but with a twist to help maintain backwards compatibility. Name your function as run<StateName with first letter capitalized>State(ControllerRequest, ControllerResponse). If you keep to this convention, then Expresso will automatically find your internal state function through the use of the Java Reflection API's.

1. ControllerResponse runPromptState(ControllerRequest request, ControllerResponse response)
  throws ControllerException {
2.  ServletControllerRequest scr = (ServletControllerRequest)request;
3. /** Get HttpServlet Request through: scr.getHttpServletRequest() **/ .....
4 } 

ControllerResponse runPromptState(ServletControllerRequest request,
                                  ControllerResponse response)
        throws ControllerException { 
    /** Get HttpServlet Request through: request.getHttpServletRequest() **/

    .....
}
/*
  runPromptState(ControllerRequest, ControllerResponse);
*/

In a more complex controller, or one with more states, it is often better to create individual "State" objects, rather than the "internal states" methodology discussed above. Again the superclass handles the transitioning to the correct state, dynamically invoking the appropriate State object's "run()" method when each state is entered.

When using "external" state objects, the declaration of the Controller is a bit different:

1. public Upload() {
2. PromptBrowser browser = new
  PromptBrowser("browser", "Prompt for Upload from Browser");
  3. browser.addParameter("resource", false);
  4. addState(browser);
  5.
  6. DoBrowser dobrowser = new DoBrowser("dobrowser", "Process Upload from Browser");
  7. dobrowser.addParameter("action");
  9.
  addState(dobrowser);
  10.
  11. } /* Upload() */

In the listing above, PromptBrowser and DoBrowser are objects defined external to the Controller class that extend the State object. For example, PromptBrowser could look like this:

(package and import statements omitted)
public class PromptBrowser extends State {

   public PromptBrowser(String stateName, String descrip) {
       super(stateName, descrip);
   }

   public void run() throws ControllerException {
       Controller myController = getController();
       String currentNumber = 
                 StringUtil.notNull(myController.getParameter("number")); // here the State will do
                                                                          // whatever logic it needs to
   }/* run() */
}

In the listing above, the PromptBrowser class extends State, defining it as one of the possible states for a Controller, and implements the "run()" method. The "run()" method is called by the superclass of the controller object whenever the Controller transitions into the specified state - it is where all of the work of the state will get done, where the Inputs, Outputs, and Transitions are generated, etc.

In order for a State object to have access to it's Controller's parameters, session, and other information, it has available to it the "getController()" method. This method returns a Controller object - the Controller object that contains this state, specifically. This allows the state to use "getParameter(name)" and other methods to interact with the controller itself, and to use the Controller's "add" methods to return it's Inputs, Outputs and Transitions as required. At the end of the "run()" method, control returns to the Controller superclass, which then processes the new Inputs, Outputs and Transitions appropriately.

As a part of it's processing, a State object often uses one or more DBObjects, and of course it can also submit jobs, access other controllers, and generally perform whatever processing is required of it.

Controller sometimes also need to transition from one state to another programmatically - in other words, not in response to a user clicking a button or selecting a link, but in response to logic within a state. This can be done in one of several ways:

1. Transition t = new Transition(); 
2. t.setName("goSomewhere"); 
3. t.addParameter("controller", "com.something.SomeOtherController");
4. t.addParameter("state", "someState"); 
5. t.addParameter("otherParameter", "etc"); 
6. t.transition(req, res); 
7. return;

As of Expresso 5.0, developers can easily derive their own controllers from existing controllers. The mechanics of this is a rewrite of the reflection mechanism that Expresso controllers utilize to call various states. Now if you do not override any particular state, Expresso's controller walks up the inheritance hierarchy looking for other classes that implement the requested state. If an object in the hierarchy is found to implement the state, it will invoke that state and return. In the past, if your own controller didn't override EVERY state, Expresso's reflection mechanism would fail.

Now, you have the ability to derive your own controller and ONLY override the states where you want to change the default behavior of the base controller.

One of the annoying aspects of dealing with frameworks like Expresso is the fact that normally to change the user interface, you'd have to change the default jsp pages that ship with Expresso. Although this is fine initially, with each release of Expresso, you would have to re-merge your changes. This problem is exacerbated by anybody working with a CVS copy, where CVS will mark any changed files and try to merge any updates, thus preventing any effective development with CVS snapshots.

The solution is to create your own controller, and then create your own JSP pages based upon this new controller

package com.jcorporate.myproject.controller; 
import  com.jcorporate.expresso.core.controller.Controller; 
import  com.jcorporate.expresso.core.controller.ControllerException; 
public class MyLoginController extends com.jcorporate.expresso.services.controller.LoginController { 
   public MyLoginController () {
       super();
       setSchema(com.jcorporate.myproject.MyProjectSchema.class); 
   }
   public String getTitle() {
       return "Sample Controller Login";
   }
}

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE struts-config PUBLIC 
          "-//Apache Software Foundation//DTD Struts Configuration 1.0//EN"
          "http://jakarta.apache.org/struts/dtds/struts-config_1_0.dtd">
<struts-config>
 <action-mappings>
  <action path="/MyAppLogin"
          type="com.jcorporate.myproject.controller.MyLoginController"
          name="default" scope="request" validate="false">
   <!-- This sample only changes the promptLogin screen -->
   <forward name="promptLogin"
            path="/expresso/components/myapp/login.jsp"/> 
   <forward name="processLogin"
            path="/expresso/jsp/register/redirect.jsp"/> 
   <forward name="processLogout"
            path="/expresso/jsp/register/logout.jsp"/> 
   <forward name="promptChangePassword"
            path="/expresso/jsp/register/change.jsp"/>
   <forward name="processChangePassword"
            path="/expresso/jsp/register/status.jsp"/>
   <forward name="emailValidate"
            path="/expresso/jsp/register/status.jsp"/>
   <forward name="promptSendPassword"
            path="/expresso/jsp/register/sendPassword.jsp"/>
   <forward name="processSendPassword"
            path="/expresso/jsp/register/status.jsp"/>
   <!-- you can use XSLT transforms here too. any path which ends with 
        .xsl or .xslt will be handled appropriately. -->
   <forward name="someOtherMethod"
            path="/expresso/xsl/blah.xsl"/>;
  </action>
 </action-mappings>
</struts-config>

<class-handler
  name="login"
  classHandler="com.jcorporate.myproject.controller.MyLoginController"/>

Any object oriented course teaches that you should be able to derive an object and override it's behavior. Expresso Controllers are no different. State handlers in Expresso should be of protected visibility, so you should be able to override any state handler to perform what you wish. We have a program listing that shows that kind of behavior:

package com.jcorporate.myproject.controller; 
import com.jcorporate.expresso.core.controller.*; 
public class MyLoginController
       extends com.jcorporate.expresso.services.controller.LoginController { 
   public MyLoginController () { 
       super(); 
   } 
   public String getTitle() { 
       return "Sample Controller Login";
   }
   
   /**
    *Overridden getRegistraitonController() 
    */
   public Controller getRegistrationController() throws ControllerException { 
       return ConfigManager.getControllerFactory()
              .getController(MyRegistrationController.class.getName());
   }
   /**
    * Overridden state that simply adds an additional output to the response.
    */
   protected void runPromptLoginState(ControllerRequest request,
                                      ControllerResponse response) throws ControllerException {
       super.runPromptLoginState(request,response); 
       response.add(new Output("myaddition","This is my added text message"); 
   }
}

Now what you see in the above code, we've overridden the rumPromptLogin state in such a way as the normal promptLoginState is run, but we add our own Outputs after the fact. Oftentimes this can be the easiest way to accomplish a simple extension since in your jsp page layout you can always not render any ControllerElements (Inputs, Outputs, Transitions, Blocks) that you don't want to see on the screen. If, however, you, wish for more radical differences in your own work, you can always omit the call to super() and perform whatever behavior you need.

So what about the functions getRegistrationController() and getLoginController()?? Well, it turns out that LoginController is a strange beast compared to a normal controller. The reason being is that Login and Registration are fairly tightly coupled classes at this point in time. If you derive your own Registration class, for example, Login will need to know what Class to forward registration requests to. By overriding this method, we're now causing our controller's links to point to our own derived Registration Controller. Most other controllers will not need this done.

The following persons have contributed their time to this chapter:

Copyright © 2001-2004 Jcorporate Ltd. All rights reserved.