TweetFollow Us on Twitter

Nov 01 Adv WebObjects

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");
           + resultOfRequest);
  return r;

Controlling Backtracking (Back Button)

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() {
  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");


  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".

Web Components Communication

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();

  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();

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)
  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

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"); 


Getting and Sending Data to External Pages

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:¶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 ="value to encode");
provided by Java. The result of the above line of code would be "value+to+encode". Don't encode the whole URL, just the values.

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:

Methods Description
NSDictionary formValues() Returns key/value
pairs for all form
NSArray formValueKeys() Returns the list of all
form field names
(NSArray of String).
These are used as
input for the next
String formValueForKey(String keyName) Returns the value for
the specified field
NSArray formValuesForKey(String keyName) Ditto. Use when
passed a list of
(NSArray of String)

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=”” 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();
  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=”” 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.

Direct Actions

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


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:


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:


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:


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:


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.

Customizing Error Pages

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 {
    return resultPage;
  } catch (Throwable e) {
    NiceExceptionPage nep = new NiceExceptionPage();
    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);

  WOResponse response = nep.generateResponse();

  return response;

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

Error handler in Application Is called ...
handleException() ... always. Default
brings up one of
the next error
pages, or if none of
them are
appropriate, brings
up the page
handleSessionCreationErrorInContext() ... when there was
an exception during
initialization. By
default, brings up
the page
handleSessionRestorationErrorInContext() ... when the session
timed out and
the user is trying to
go back to an
earlier page. By
default, brings up
the page
handlePageRestorationErrorInContext() ...when the user
backtracks to an
earlier page (back
button) but the
context of that page
is lost. By default,
brings up the page

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:

Location Component Name
/System/Library/Frameworks/ WOExceptionPage.wo
JavaWOExtensions.framework/ WOPageRestorationError.wo
Resources/ WOSessionCreationError.wo

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


Community Search:
MacTech Search:

Software Updates via MacUpdate

The best games like Animal Crossing on m...
Animal Crossing amiibo Festival is out right now for the Wii U, reminding us of just how much fun that world can be. Or at least to go back and check in on our villages once in a while. [Read more] | Read more »
Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »
Facility 47 (Games)
Facility 47 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: You wake up alone and freezing in an icy cell. You try the cell door but it’s locked, it seems that you are stuck with no... | Read more »
The best Photoshop alternative on iPad
Instagram and Lightroom are great and all, but sometimes people need to get extra creative with their image editing.Like, Photoshop creative. If you're one of these people, take a look at our pick for the best mobile Photoshop experience on iPad... | Read more »
The Walking Dead: No Man’s Land guide -...
A new update for The Walking Dead: No Man’s Land was released last week, making it the perfect time for you to head back to your base and take out some walkers. Here’s the lowdown on what’s new to the game, and how to take advantage. [Read more] | Read more »
Goat Rider guide - Tips and tricks to st...
We've all been there. One second, we're riding high on a crazed goat, and the next, we've been tossed off it like someone who's no good at goat ridin'. [Read more] | Read more »
Real Boxing 2 CREED: How to become a gre...
Just in time for Rocky fans who can’t wait to see CREED, the latest movie, we have the official tie-in game,Real Boxing 2 CREED. It builds on the success of its predecessor and there’s lots to take in so we at 148apps thought we’d run you through... | Read more »
CoinOp Heroes 2 guide - How to build an...
CoinOp Heroes 2 justlaunched and, like all clickers, it's dangerously addictive stuff. You have to furiously tap your screen to defeat wave after wave of foes and earn an insane amount of cash to spend on character upgrades and an army of minions... | Read more »
Dr. Panda Firefighters (Education)
Dr. Panda Firefighters 1.0.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0.1 (iTunes) Description: FIGHT FIRES AND SAVE THE DAY!Work together with Dr. Panda and his firefighting team to rescue his trapped... | Read more »
Puddle + (Games)
Puddle + 1.0 Device: iOS iPhone Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Puddle is back in a new "+" edition featuring enhanced graphics, new videos and Apple TV support ! No IAP and No Ads. Dive into Puddle... | Read more »

Price Scanner via

Save $30-$40 on new Apple TVs after rebate
Adorama has new Apple TVs on sale for up to $40 off MSRP after mail-in rebate, good through December 15th. Shipping is free, and Adorama charges NY & NJ sales tax only: - 32GB Apple TV: $119.99... Read more
13-Inch Haswell MacBook Air At Two Years – Th...
The 13-inch mid-2013 “Haswell” MacBook Air I ordered in Apple’s November 2013 Black Friday sale was my first new Mac in four and a half years — the longest interval I’ve gone between system upgrades... Read more
Target Black Friday Early Access deals: $100...
Target is offering early access to their Black Friday deals on Apple products on their online store for today, the 25th, only. Choose free shipping or free local store pickup (if available): - Apple... Read more
BlackBerry Q3 Mobility Index Report Finds iOS...
BlackBerry has announced results of its thirteenth Good Mobility Index Report, showing that organizations are increasingly building custom secure apps. Among Good Powered by BlackBerry (formerly Good... Read more
Wednesday roundup of early Black Friday Mac s...
Save up to $500 on a new Mac with these early Black Friday deals from Apple resellers, currently the lowest prices available for these models: (1) B&H Photo has all new Macs on sale for up to $... Read more
iPod nano on sale for $119, $30 off MSRP
Walmart has the 16GB iPod nano (various colors) on sale for $119.20 on their online store for a limited time. That’s $30 off MSRP. Choose free shipping or free local store pickup (if available). Sale... Read more
Adorama Black Friday deals: Up to $400 off Ma...
Adorama has released their Black Friday deals for 2015. Save up to $400 on MacBook Pros, $200 on MacBooks and MacBook Airs, and $270 on iMacs. Use code RYBFDEAL during checkout to see these prices.... Read more
B&H Photo Deals: $200 off 12-inch 1.2GHz...
In addition to the B&H Photo Black Friday week sales we posted yesterday, B&H has lowered their price on two products to $200 off MSRP: - 12″ 1.2GHz Gray Retina MacBook: $1399 save $200 - 13... Read more
Best Buy Early Access: Today only, Up to $125...
Best Buy has iPad Air 2s on sale for up to $125 off MSRP and Apple Watch models on sale on their online store for up to $100 off MSRP with special codes through midnight CT tonight. Choose free... Read more
UPPERCASE DESIGNS Premium Ultra Thin Keyboard...
UPPERCASE Designs today announced its new Premium Ultra Thin Keyboard Protector and its Palm Rest Protector Set for the 12-inch MacBook. The accessories provide durable protection for the 12-inch... Read more

Jobs Board

Hardware Systems Integration Engineer - *App...
# Hardware Systems Integration Engineer - Apple Watch Job Number: 39380139 Santa Clara Valley, Califo ia, United States Posted: Apr. 23, 2015 Weekly Hours: **Job Read more
Sr. Technical/Project Manager, *Apple* Educ...
# Sr. Technical/Project Manager, Apple Education Job Number: 36588557 New York City, New York, United States Posted: Jul. 30, 2015 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Merchant Operations Manager: *Apple* Pay -...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
*Apple* Pay QA Manager - Apple Inc. (United...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.