An Introduction to WebObjects

WebObjects is most often referred to as an application server; however, it's much more. WebObjects consists of a set of frameworks that allow you to write cross-platform, server-distributed applications, and a set of tools to help you write them. The tools include WebObjects Builder, EOModeler, Rule Editor, and WebServices Assistant. You'll also use Project Builder and sometimes even Interface Builder.

The applications must be written in Java, but can be distributed in a variety of ways, including HTML, Java Client, or even via Web Services. Since WebObjects is Java-based, you can actually use other tools to create WO Applications, such as Eclipse, an open source Java IDE led by IBM. However, I'm going to concentrate on using Apple's tools for creating and distributing an HTML application.

Why Use WO?

WebObjects allows you to create a wide variety of applications. It's a mature suite of frameworks and tools that were obtained by Apple in its acquisition of NeXT.

WebObjects was a crown jewel at NeXT. Companies like Disney, Deutch Bank, and AAA all use(d) WebObjects to create cutting edge web applications (heck, even Dell used it). Even today, WebObjects is being used to create new and compelling applications, like the Apple Music Store.

For $700, you get the complete WebObjects package. In the package, you'll find a developers license and a deployment license, along with a few manuals. You will be able to deploy on almost every J2EE application server or on any system running J2SE (1.3.1 or higher). However, Apple only supports deployment on Mac OS X Server, Windows 2000, or Solaris 8. As you'll discover, WebObjects is an amazing deal at almost any price. (The deployment license used to cost $50,000 just three years ago!)

What is EnterpriseObjects?

If you read about WebObjects, you're bound to come across the terms EnterpriseObjects (EOs), EOF, and EOModel. I'm sure you're wondering "What the heck is all this EO stuff?" In my opinion, EO is the greatest thing since sliced bread. However, since this is a technically sophisticated audience, I'll go into little greater detail. Also, it would be a crime to not mention EOF while talking about WO. (This is even a felony in some parts of the world.)

The Enterprise Objects Framework (EOF) helps you manage the persistence of objects. Most often, this persistence relates to a database. EOF is wonderfully database-independent, so it doesn't matter if you initially use MySQL, only to discover you've won the lottery and can grab a copy of Oracle. Of course, the more likely scenario is that your company has decided to develop against MySQL and use Oracle for deployment. In either case, a simple flip of the JDBC switch and your application has migrated from MySQL to Oracle.

Why Use EOs?

EOF allows you to store information in a database and access the information in an object-oriented manner. EOF provides a persistence layer to maintain information over an indefinite period of time, even if you turn your server off. There are a few products similar to EOF on the market, and they fall under the Object-Relational Mapping banner.

Let's Get to Work: Create a Simple Login Page

In order for you to create the next Big Thing, you'll need to learn how to use WebObjects. The first step in learning WO is to get a copy. If you're a member of the Apple Developer Connection, you should be able to download a demo version. If you're not a member, you can either join ADC or purchase a copy of WebObjects. Below, I'm going to walk you through creating a simple login page.

As a side note, I want to mention that I've been using WO/EOF since late 1999 and am still learning new features. The set of frameworks is rich and deep, so don't be surprised if you're still discovering features a few years after working with the product. As a programmer, I love this fact.

Simple Login Window using WebObjects

Create a New Project

Go ahead and launch ProjectBuilder and create a new Project. You'll notice that WO provides you with templates for nine different types of projects. You should select the WebObjects Application template.

You will need to name your Project, and then go through a series of configuration options. You can safely click on the Next button each time without changing any options.

In your new Project, you'll find a group called Web Components. When you open the Web Components group, you'll find another group called Main. Within Main you'll find:

• Main.wo: the View to be presented to the client; don't worry about Main.wo's contents.
• Main.java: the source code for your Main component.
• Main.api: a configuration file. You don't need to currently concern yourself with it.

Using WebObjects Builder

When you double-click on Main.wo, the WebObjects Builder (WOB) application will launch. Using WOB, you will be able to design your web page. You will also be able to generate Java code, which is placed into the Main.java file of your Project.

Okay, so now you have a blank web page. It's time to get going.

You'll want add a Table, to make the Login area look nice and clean. You will find the Table button in the toolbar, on the upper right-hand side; it looks like an old window. You should configure the Table to have three rows and two columns.

Since this is a Login page, you can merge the top row of the Table and put "Please Log In..." to let the user know this is a Login area. You also need to allow the user to enter their username and password. You can merge the top two cells by using the Merge Cells button by click-dragging across the two top cells ...

... and then clicking on the Merge Cells button, located in the Inspector panel. It looks like an X. If your Inspector panel is not visible, click on the Inspector button in the toolbar.

Once the cells are merged, you should design the table to indicate where the user is to input the username and password. You'll also want to add a couple of WOTextFields into the table.

Without a couple of variables, your page is pretty useless. So you need to add them. On the bottom left side of your Main you will see two objects, application and session, listed in the Object Browser. If you control-click (or right-click) in this area, you will get a pop-up list of options. The two items to pay attention to are the "Add Key to ..." and "Add Action to ..." options.

Select the "Add Key to Main" option and name the variable username. Select the Type as a String and also have WOB generate source code for you. Java purists can select to prepend get to their variable returning method name.

You should also do this for the password.

Now that there are a couple of variables, you can bind them to your view by simply click-dragging from the variable name to the component you wish to bind. You will want to bind the value attribute of the WOTextField to your variable. Do this for both the username and password.

You'll also want to change the WOTextField for the password to a Password Field. You can accomplish this by selecting the WOTextField and changing the Inspector Panel to show the Static Inspector.

You can then select to make the WOTextField a Password Field. This will hide the user's input behind bullets while typing.

NOTE: By changing to a Password Field, you are not encrypting the information. You are simply changing from an HTML Text Field to an HTML Password Field. As always, unless the connection between the client and the server is encrypted, the text in this field will be sent across the network in clear text.

The final three steps in the page layout are to add a Submit button, add a Submit action, and to place the panel inside of a WOForm.

• To add the Submit button, click on the WOSubmit button in the toolbar.

• To add the Submit action, control-click (or right-click) in the Object Browser and select the "Add Action to Main" option. Name it submit and return null for the Page.

  

  You should then bind submit to the Submit button. You can accomplish this as before, by simply click-dragging from submit to the Submit button. You will want to bind the action attribute.

  
• Finally, you want to "wrap" the login panel and Submit button in a WOForm. The WOForm button can be found directly to the left of the WOTextField button. By selecting the section of the page you wish to "wrap" (the table and Submit button) and clicking on the WOForm button, you will enclose the login panel inside of the WOForm. If you do not use a WOForm, the Submit button will not work correctly.

I'm sure some of you are asking, "Where's the EOF stuff?" Well, it's coming, but you need to crawl before you can walk. For now, you need to go back to Project Builder and enter some code.

Using Project Builder

In your Main.java file, you'll want to add some code. First, you'll need somewhere to store the username and password for your users. For this example, you'll use an NSMutableDictionary.

    protected NSMutableDictionary userDictionary;

    public Main(WOContext context) {
        super(context);
	
        String users[] = new String[] {"Andy","Beth"};
        String passwords[] = new String[] {"alpha", "beta"};
        userDictionary = new NSMutableDictionary(passwords, users);
    }

NSMutableDictionary is a simple object that allows you to store and retrieve "values" using "keys", following the Key-Value Coding Pattern.

You're almost there, but you still need to give the Submit button (which is bound to our submit method) a little more oomph. In your Main.java file, locate the submit method that WOB created for you. When the user clicks the Submit button, you'll do a quick lookup in the userDictionary to see if the information is correct.

    public WOComponent submit()
    {
	String s;
	
	s = (String) userDictionary.valueForKey(username);
	if (s != null && s.equals(password)) {
	    System.out.println("correct");
	}
	else {
	    System.out.println("incorrect");
	}
	return null;
    }
    

When the user clicks on the Submit button, WebObjects is going to do its magic and call the submit method. It is also going to "push" the values the user inputs into your username and password variables. Therefore, you'll be able to compare the input values to the values in your userDictionary.

Challenge: add a feedback variable to your Main page, bind it to a WOString , and provide some feedback to the user instead of printing out to the console.

As you'd quickly discover, keeping the user's information in a hard-coded NSMutableDictionary is not very useful (even though it is mutable). Considering that the userDictionary object is only valid while the program is running, you can't even rely on changing a user's password. The second you shut down the application, the changes would be lost. You could move the code around the project, creating special storage components, moving it into the Session object or even the Application object, but it's kind of like putting earrings on a pig.

Simple "Login Window" Example Using WO/EOF

Create an EOModel for a User

Open EOModeler and create a new Model. You will be asked if you'd like to create a connection using JDBC, JNDI, or None. Select the JDBC option and enter the information for your database. I've chosen to use OpenBase, but you're free to use any database that has a JDBC driver available.

One of the beautiful features of EOModeler is that it is database-independent. EOF will handle generate SQL statements for you, which will allow you to move from one database vendor to another with little effort. This feature will also allow you to concentrate on your project and not the underlying database calls.

I recently had a personal experience with this feature moving a site running on MySQL to OpenBase. I was able to accomplish the "port" in about 15 minutes. It took a little more time than I had planned because I had two raw SQL calls in my project to use MySQL's IN BOOLEAN MODE search feature.

Okay, enough stories, back to work. You should create a new Entity and name it User. An Entity is similar to a Table in the database, except for the fact that an Entity will become an Object; an EOEnterpriseObject, to be specific.

Once you have created your Entity, you'll want to provide information to EOModeler to create the Object-Relational Mapping. Make sure the Inspector Panel is open. You'll need to provide the Table name that you wish to relate to this Entity. Don't worry about the Class Name, EOGenericRecord is fine for now. Database purists can feel free to name their Tables in UPPERCASE.

You should now add a few Attributes to your Entity. When adding Attributes, you should relate them to a Column in your database. You will want to add (the External Types will depend on your database vendor):

• username: Value Class - String / External Type - varchar
• password: Value Class - String / External Type - varchar
• pk: Value Class - Number / External Type - integer

You will be using the pk Attribute as your Primary Key. EOF will handle its generation for you; however, you will need to indicate that it is to be used as a Primary Key. Therefore, click in the Key column.

After you've modeled your Entities, you'll want to double check that the External type (the type of data your database will store the information as) and the Internal type (the type of Object EO will use) for each Attribute. Some of this may seem tedious, especially when you start building larger models, but the attention you pay to details here will pay off tremendously in the future. Once you're happy with your Model, you can have EOModeler create your database for you. Simply click on the SQL button and then Execute SQL. If all goes well, you'll have a your database.

I also need to mention that EOModeler can reverse-engineer a previously created database. So, if you just happen to get the call requesting to build a system on a current database, you'll be able to have EOModeler do the heavy lifting for you. WO has a great technology called Direct To Web (D2W) that can give you web-driven access to a database in minutes. At first glance D2W may look like a toy, but trust me -- it's not.

Store Variables in the Database

In order to move forward with this article, you need a way to get information into the database. There are a number of ways to accomplish this, but since this is a WO/EO article, I figured I'd detour just briefly.

In Project Builder, create a new File. The Assistant will present itself. You should select the Display Group Component, located under the WebObjects heading. You should then name your new component UserGroup. After naming your component, you will be presented with the choice of an Entity, which should be a simple choice, as you only have one.

The Assistant will then walk you through a number of questions. When choosing the Layout, you should select "Selected Record" and "Matching Records" for the configuration.

What you are actually doing is creating a simple page to Search, Edit, Create, and Delete information stored in the User table of the database. You will then be prompted through additional configuration options. When you have walked through the steps, click Finished.

Feel free to do this part of the article a few times, each time selecting different options. It should prove insightful.

Now you are going to add a hyperlink on your Main page and link it to the new UserGroup page. This will allow you to add new Users to the database. You would obviously only use this UserGroup page as an administrator of your site, as it's not restricted in what it can accomplish.

When you created the UserGroup page, a WODisplayGroup was created and configured for you. WebObjects provides a class called WODisplayGroup, which is used in the UserGroup page. You are going to use a WODisplayGroup for your Main page, as well. My feelings on WODisplyGroup? "There's gold in them thar hills."

There are three ways to get a WODisplayGroup into an already existing page. You can add it by:

1. Writing the code directly in the .java file.
2. Adding a Key in WOBuilder.
3. Dragging the Entity from EOModeler to WOBuilder.

I typically use method (2) or (3). For this article, you'll use option (3), since it's the most fun.

From the EOModel window, click and drag your User Entity to the WOBuilder window for your Main page. You will be prompted to "Add & Configure" the new DisplayGroup being created. Name the DisplayGroup userDisplayGroup. The default configuration will be fine.

You can now bind the username and password WOTextFields in your Login panel to the userDisplayGroup. For the username, you're going to traverse the hierarchy in the Object Browser to userDisplayGroup>queryMatch>username. You will do the same for the password.

Next, you should bind the Submit button. Connect it to the userDisplayGroup>qualifyDataSource method. When a user clicks Submit, the WODisplayGroup will use the supplied username/password to try to find a match in the database.

Next, add a WOHyperlink to the page. Name it "Create" and bind it to the UserGroup page. You can accomplish this by using the pop-up menu to the right of the pageName key in the Inspector Panel.

On the Main.wo page, add a couple of WOConditional elements. You'll notice they have a plus sign on them. Click on one of the plus signs and change it to a minus sign. Inside of the WOConditional with the plus, type "Please log in..." In the one with the minus, type "Thank you, " and then add a WOString . Bind this WOString to userDisplayGroup>selectedObject>username. Your completed Login panel should look similar to this:

Now that you've taken advantage of Apple's generosity, you can greatly reduce the amount of code you need to maintain. Your entire Main.java file can now look like this:

import com.webobjects.foundation.*;
import com.webobjects.appserver.*;
import com.webobjects.eocontrol.*;
import com.webobjects.eoaccess.*;

public class Main extends WOComponent {
    public WODisplayGroup userDisplayGroup;

    public Main(WOContext context) {
        super(context);
    }

}

Go ahead and "Build and Run" your application. Initially, you won't have any data in your database. In order to insert some data, you will use the "Create" hyperlink. The UserGroup page will allow you to create a new user and save the information appropriately.

Since you are now connected to a database, the information is persistent. Try stopping your application and running it again. Try using the Login panel. The information you've entered for users should be the same as it was when you stopped.

Apple provides sample code with WebObjects for creating a Login Panel using the Basic Authentication protocol. It is up to you (or the boss man) to decide whether Basic Authentication protocol is acceptable for your project.

Parting Thought

As I mentioned earlier, the Apple Music Store is a WebObjects application. When you access the Apple Music Store, you'll notice that you can find out what music other people are buying, whether it's through the Top 10 list or the "...other people bought" suggestion. Of course, you can also do a simple search. Obviously, Apple isn't guessing at this information, so you can conclude they're keeping the information in a persistent store: a database. The WebObjects set of frameworks makes all of this possible.

Josh Paul is the founder and CEO of Aweli, a startup focused on digital video solutions, and the author of Digital Video Hacks. He has provided software and service solutions to entertainment production companies throughout Los Angeles and New York.

Return to the Mac DevCenter

Copyright © 2009 O'Reilly Media, Inc.