Volume Number: 17 (2001)
Issue Number: 11
Column Tag: Advanced WebObjects

Part 3 - Cool Programming Tricks

by Emmanuel Proulx

Neat things you can do with WebObjects.

You already know that, in order to jump from a Web Component to another one, the syntax is simply:

WOComponent anAction() {
  return pageWithName("ComponentName");
}

But what if the page you want to jump to is external to the application? One way of statically jumping to an external page is to hardcode the URL in a static hyperlink on the page. But sometimes you need to process the request before you jump to that external page. How can you do that?Ê

WebObjects has a utility class called WORedirect, which produces a "redirection page". This page will have the browser jump to that external URL. You can invoke WORedirect it by using the following syntax:

WOComponent anExternalAction() {
  //Compute this request...
  WORedirect r = (WORedirect)pageWithName("WORedirect");
  r.setURL("/phonypage?param=" 
           + resultOfRequest);
  return r;
}Ê

Backtracking (clicking on the "back" button of the browser) can cause big problems, in all Web applications. The problem may arise when:

• the user is in a first page, the system being in a certain state A
• the user clicks on something to go to the second page, setting the system to a new state B
• the user clicks on "back" to see the first page, thinking the state of the system is A again - but the system is still in state B! Any number of things can go wrong now.

As an example, the user might choose to see the records for Monday (state A), then click on a hyperlink marked "Tuesday". The page reloads with the new set of records for Tuesday (state B). The user then backtracks to the previous page, and decides to click button "clean" that deletes all records for the current day. The user thinks he just erased the records for Monday, but in fact he/she erased the records for Tuesday.

This can be a big problem. It is well known by the Web developers, that handle the problem in specific ways:

You can fix the problem by forcing the previous pages to reload every time the user accesses them. You do that by calling the function setPageRefreshOnBacktrackEnabled() from the Application object's constructor. This is implemented in WebObjects by setting an "already expired" expiry date of all produced pages. This solution is pretty good, but not sufficient, because WebObjects caches the pages that are produced. When a user uses the back button to an expired page, WebObjects returns the pages as it was generated previously.

You can also turn off page caching, by calling another function from the Application object: setPageCacheSize(). How does this work? By default, WebObjects keeps the 30 last pages in memory, and returns them to the browsers that ask for them. Setting the cache size to 1 prevents the user from receiving cached pages (except the current one).

Here's an example:

public Application() {
  setPageRefreshOnBacktrackEnabled(true);
  setPageCacheSize(1); //keep only the current page
  //...
}

You can also prevent the user from re-accessing your application after leaving it. The user can still browser back and forth in the system's pages, but not after exiting. This usually involves an "Exit" or "logoff" button or hyperlink, linked to an action like:

public WOComponent exitAction() { 
  WORedirect r = (WORedirect)pageWithName("WORedirect");
  r.setURL("http://www.mactech.com");
Ê
  session().terminate();
Ê
  return r;
}

You still need to call setPageRefreshOnBacktrackEnabled(true) in the Application object's constructor to force page reload, or else the user will be able to see the old defunct pages that have no associated session, instead of an honest error message saying "session timed out".

There's a number of ways pages of the same system can communicate among each other. Let's overview the different ways.

Global Variables

The different pages can share global information by setting variables inside the Application or Session objects.

Imagine a "Login" page and a "User Information" page. These would share a piece of data called the "userID". You would make an instance variable called "userID" in the Session object, like this:

public class Session extends WOSession {
  //...
  protected String userID;
  public String userID() { return userID; }
  public void setUserID(String newID) { userID = newID; }
  //...
}Ê

Then you would set the userID in an action in the Login page:

protected String userIDField;
Ê
public WOComponent doLogin() {
  //Verify username and password
  Session s = (Session)session();
  s.setUserID(userIDField);
Ê
  UserInformation ui = (UserInformation)pageWithName("UserInformation");
  return ui;

}Ê

Finally, you would use this information from somewhere within the User Information page:

public UserInformation () { //constructor
  Session s = (Session)session();
  actUponUser(s.userID());
}Ê

This is simple, but can lead to potential problems. All modules from within the system have access to the global variables, and may change them, yielding possibly bad results. This may or may not be appropriate - it's up to you to decide.

Local Variables

You can send information to another page by setting a local variable instead of a global one. Let's use the same example. This time there's no Session or Application involved; the communication would happen directly. You would send the userID to the User Information page like this:

protected String username;
Ê
public WOComponent doLogin() {
  //Verify username and password
Ê
  UserInformation ui = (UserInformation)
    pageWithName("UserInformation");
  ui.setUserID(username);
  return ui;
}Ê

You need a variable to receive the userID in the User Information page, in order to use it:

protected String userID;
public String userID() { return userID; }
public void setUserID(String newID) { userID = newID; }
Ê
public UserInformation () { //constructor
  actUponUser(userID());
}Ê

Interface Variables

Custom Components are meant to be "black boxes"; you can use them but you don't know how they are built from the inside. In theory, you could buy libraries of components, and you don't have to have the source code in order to use them. But sometimes you need to communicate with them to let them know how they should behave. How can you do that without opening the .java file and looking at the source code? To work around this problem, we use an "interface"; a description of their publicly available members. The interface shows up in the WebObjects Builder while editing the parent component, by selecting the sub-component and opening the Inspector.

NOTE: Go to any project folder and take a look at the available files. Notice these files with the extension ".api". These files hold the interfaces for your Web Components.

The tool used for managing the interface is the API Editor. It is available in the WebObjects Builder, by clicking on the toolbar button .

Open any component and click on this button. This dialog is API Editor window: Ê

Here's the list of things you can do in this window:

You can expose your component's variables. You do that by clicking on the button in the upper-right corner, and choosing "Add binding". You then enter the name of your variable. For each variable, you can then specify restrictions (a failure to obey these restrictions in the parent component will trigger an error message when displaying the component):

• Required: is it mandatory to link this attribute to a value?
• Will Set: must the attribute be linked to a variable of the parent component? (As opposed to a constant value.)
• Value Set: specifies the type of data that can be sent to the variable. The choices are shown here:

The button "Add Keys From Class" lets you share all variables of the current component at once. This is a big time saver. I usually click on this first, and then remove the unwanted variables.

The Validation tab lets you describe a "validation scheme", a more complex restriction strategy than the one in the Bindings tab. If the user of the component fails to link the attributes to values that follow the validation condition, an error will be returned when displaying the component.

The Display tab lets you specify a documentation file (an HTML file that will show up when clicking on the help button in the Inspector), and an icon file that represents your component (shows up in the parent components instead of the default icon, e.g. ).

Interface Variable Synchronization

In WebObjects, you have control over the way values are stored in the attributes of elements (or sub-components).

The attribute's connection (also called binding) is a two-way street; if you set an element attribute in the parent component, the destination variable is automatically updated with the new value. If you set the binded variable in the element or sub-component, the parent's source variable is also changed (assuming it's not a constant). The "synchronization" between the parent and child variable happens at six specific times during the Request/Response loop, in the active WOComponent instance:

Before the generation, right before and right after calling takeValuesFromRequest()

During the action processing, right before and right after calling invokeActionFromRequest()

After the generation, right before and right after calling appendToResponse()

This process ensures that both the parent component and the element/sub-component have harmonized values at all times. It happens automatically, and relies on the existence of standard getter and setter functions in the classes of the variables. Casting is also done automatically as needed.

In the case of Custom Components, sometimes you don't want the variables to be in harmony. Sometimes, you don't even have a destination variable in the sub-component. You can turn off the synchronization of the variables and handle it by hand. You do that by overloading the Custom Component's synchronizesVariablesWithBindings() function. Then, you need to implement the variable synchronization yourself. Two functions help you do that: valueForBinding() to get the parent component's variable, and setValueForBinding() to set it to a new value. In the following example, we read in a variable from the parent, process it, and return the result in another variable:

import java.lang.Math;
Ê
public class MortgageCalculator extends WOComponent {
  //...
Ê
  public boolean synchronizesVariablesWithBindings() { 
    //Don't synchronize the parent's variables -
    //we'll do that ourselves
    return false;
    }

  public void awake() {
    //the parent thinks these variables exist:
    Double p = (Double)valueForBinding("principal");
    Double y = (Double)valueForBinding("years");
    Double i = (Double)valueForBinding("interest"); 
    if( (p==null) || (y==null) || (i==null) ) return;
    double r = i.doubleValue() / 1200;
    double cr = p.doubleValue() * r;
    double a = Math.pow(1.0+r, 12.0 * y.doubleValue());
    double b = a - 1.0;
    
    //put result back in another binding
    setValueForBinding(new Double(cr * a/b) , "payments"); 
  }
Ê
  //...
}Ê

You can't send values to external pages with global or local variables. We have to use the "standard" HTTP ways...

URL parameters

You can send data to a page by passing it URL parameters. The syntax is:
www.mactech.com/path/phonypage?param1=value1¶m2=value2...

The values have to be properly encoded (spaces replaced by plus signs (+), etc.). Ê

TRICK: you can translate each value to comply to the URL encoding by using the function

String encodedValue = java.net.URLEncoder.encode("value to encode");Ê

Note that URL parameters are automatically decoded and transformed into fields on reception...

Processing fields

You can receive form fields (including URL parameters) from an external page by using these WORequest functions, in the overloaded takeValuesFromRequest() of your component:

In the following example, we'll receive the username and password, and pre-populate the corresponding fields:

String password = ""; //connected to a "password" form field
String username = ""; //connected to a "username" form field
Ê
public void takeValuesFromRequest(WORequest r, WOContext c) {
  //Method #1
  String u = r.formValueForKey("username");
  if( (u != null) && !u.equals("") ) //not empty, assign it
  username = u; //pre-populate the username field on this login page
Ê
  //Method #2
  NSDictionary d = r.formValues(); //get all fields
  String p = d.objectForKey("password"); //extract field password
  if( (p != null) && !p.equals("") ) //not empty, assign it
    password = p; //pre-populate password field on this login page
}Ê

Posting fields

The other way around, you can post form data to an external page, if you know how. Usually, the user navigates to an external page by clicking on a button, an image button or a hyperlink. Posting data is necessarily done by not pointing back to an action on the server, but by going directly to that external location. Note that this solution is equivalent to sending data as URL parameters. Here are some points to consider while implementing this solution:'

When using a hyperlink, submit button or image button, use a static one. You can turn a dynamic element into a static one by opening the Inspector and clicking on the button "Make Static". If you're planning to use a hyperlink, make it execute the submission of the form, like this:
<A HREF=”” onClick=”document.formName.submit(); return true;”>

Click here to submit

You should also use a static form (use "Make Static" button), and in the HTML , add some code to go to the external site. <FORM method=post ACTION=”www.othersite.com/cgi-bin/page.pl” NAME=formName> Ê

The fields you use can be dynamic, but they don't have to be visible: you can use "hidden" fields to hide the submission of the form from the eyes of the user. This is commonly used to make it harder for the user to see data that he/she is not allowed to view. To make a hidden field, insert a custom component in your form , and in the Inspector set its class to WOHiddenField. Don't forget to set the "value" attribute.

Post-processing field posting

You might be interested in executing an action on the server before posting the form data to an external page. I have yet to see a simple way to do that. The most effective way I have found is to use a component with a form that posts itself automatically:

Use a normal button or hyperlink, connected to an action. The action would contain something like:

public WOComponent doSomethingAction() {
  //calculate value1
  //calculate value2
  //other processing...
  RedirectionPage rp = new RedirectionPage();
  rp.setField1(value1);
  rp.setField2(value2);
  return rp;
}Ê

Create the new RedirectionPage component. It is an empty page, that consists of words "Please Wait", and the static Form with two hidden fields: field1 and field2. In the static Form's declaration, add the following action (in bold): <FORM method=post ACTION=”www.othersite.com/cgi-bin/page.pl” NAME=formName>

In the page's tag, add this JavaScript to post the form (in bold): <BODY onLoad=”document.formName.submit(); return true;”>

That's all. You may instead write a generic "Please Wait" page for your application, containing a dictionary of fields/values, and a variable target for the form. That way you would get maximum reuse.Ê

Let's do an experiment. Run any application and get in it through the front door by going to the URL:Ê

http://localhost/cgi-bin/WebObjects.exe/AppName

Then click on a link. You should get a weird-looking URL syntax, with lots of digits that don't seem to mean anything. Here's an example URL:

http://localhost/cgi-bin/WebObjects.exe/AppName.woa/wo/nJ600003400sh6002/0.6

Let's dissect this URL. Of course, the first part is the protocol and server (http://...) followed by the WebObjects Adaptor (/cgi-bin/WebObjects.exe). Then there's the application name (AppName.woa - the extension is optional and means "WebObjects Application"). Until now, everything seems exactly like the previous URL. But what is the rest for? The wo/ tells us we are looking at a Web component. The following nJ600003400sh6002 is a randomly generated code that represents the current session, stored in the Session object as the member sessionID(). Lastly, the code /0.6 represents the page itself.

Take a look at the session identifier again. It is randomly generated. That means, when you return to the front door of the application, a new sessionID is created. This also means, after a session has expired, there's no way to point directly to the current page, if it is not the component Main.wo. This can be problematic, because sometimes you want to be able to bookmark or jump directly to a page.

This is a job for the Direct Actions. A Direct Action is a "backdoor" to your site. It is represented by a special URL syntax, like this:

http://localhost/cgi-bin/WebObjects.exe/AppName.woa/wa/actionName

Here the .woa extension is mandatory. The following /wa indicates a Direct Action, as opposed to a Component. And then there's the Direct Action's name.

Here there's no session identifier involved. The page is bookmarkable, and can be hardcoded in external Web pages and applications.

By default, Direct Actions point to a special class of your application, called DirectAction (extends WODirectAction), which is created automatically by the New Project assistant. When the user specifies a Direct Action, WebObjects calls automatically to the right function in this class, by using the Reflection API - no need to configure anything!

As an example, consider an administration page Admin.wo. It cannot be accessed directly or else any user would have total control. Creating a backdoor access to this site is very simple. The URL to use is:

http://localhost/cgi-bin/WebObjects.exe/AppName.woa/wa/Admin

and the corresponding Direct Action method is:

public class DirectAction extends WODirectAction {
  //...
  public WOComponent AdminAction() {
    Admin a = (Admin)pageWithName("Admin");
    return a;
  }
  //...
}Ê

The important point here is to use a different Direct Action name for every "backdoor" entry point of the application, and to create a function of the same name, but with the word "Action" appended. Example: Since the Direct Action name is "AdminPage", so the function name is AdminPageAction().

TRICK: Say you want to get in through a backdoor from an external application, but keep the current session's context at the same time. You can do that by sending the session().sessionID() String out to the external application, then by going back to the desired Direct Action and passing back the session identifier in the URL parameter "wosid". This acronym means "WebObjects Session IDentifier", and it's a reserved URL/form parameter name. Here's an example URL:Ê

http://localhost/cgi-bin/WebObjects/AppName.woa/wa/action?wosid=nJ600003400sh6002

Many more things can be done with Direct Actions. For example, in buttons and hyperlinks, Direct Actions can be used in lieu of regular actions. Also, special URL syntax can be used to access Direct Actions located in classes other than DirectAction.

Whenever there's an exception in your application, whether it happens in your code or in the frameworks, you get the usual, dreaded, ugly WebObjects exception page. Take a look at this sample:Ê

Figure 1. Default ugly error page.

You don't want your users to see that - believe me. In an ideal world, you would never get an exception. But this is far from an ideal world, so let's get to work.

What you do want your users to see is a custom-made company-standards-compliant pretty page. How do you achieve that? Well, you can for sure catch exceptions as they occur (try block). Then you can redirect right away to your own nice exception page.

The following piece of code does just that, in the form of an action method:

WOComponent anAction() {
  try {
    doSomething();
    return resultPage;
  } catch (Throwable e) {
    NiceExceptionPage nep = new NiceExceptionPage();
    nep.setExceptionMessage(e.getMessage());
    nep.setTrace(NSLog.throwableAsString(e));
    return nep;
  }
}Ê

But that's not complete. What about the other exceptions, the ones that happen outside your control? You're in luck. Whenever an uncaught exception occurs, WebObjects calls Application.handleException(). Let's see an example in which we overload this function to fire up our NiceExceptionPage:

public WOResponse handleException (Exception e, WOContext c) {
  NiceExceptionPage nep = new NiceExceptionPage(c);
  nep.setExceptionMessage(e.getMessage());
  nep.setTrace(NSLog.throwableAsString(e));
Ê
  WOResponse response = nep.generateResponse();
Ê
  return response;
}

You can even make a different error page for each of these events, by overloading the proper function:Ê

There's a second way to customize the error pages. You can fix all exception pages once and for all, for every single application on your computer or your server. It involves modifying the template files for the actual (ugly) exception pages from WebObjects' framework folders. Here's the location of these components:

NOTE: when you modify these components, don't forget to

• make a copy of the original page before starting
• propagate the modified pages to all your Server(s) along with your application - they are not tied to your project

This will save you a lot of trouble.

Emmanuel Proulx is a Course Writer, Author and Web Developer, working in the domain of Java Application Servers. He can be reached at emmanuelproulx@yahoo.com.