Apple's WebObjects is a comprehensive suite of tools and frameworks for quickly developing Java server applications. The release of WebObjects 5.2 allows developers to add standards-based web services to these applications, as well.

WebObjects gives you the ability to build or use web services without writing low-level SOAP, XML or WSDL documents. The WebObjects tools enable code-free generation, configuration and testing of web services from existing data assets. Because these web services can interoperate with clients written in many languages, including Java, AppleScript, and Perl, you can quickly create integrated solutions that would otherwise require a lot of coding.

This article shows you how to take an existing database and publish assets as web services, including a service description, all without writing any code.

Installation

If you don't own your own copy of WebObjects 5.2, it is available in a free trial version for Mac OS X version 10.2 or later at Apple Developer Connection. Directions on how to find the download are on the WebObjects - Getting Started page. We will be working with Mac OS X 10.3 and Xcode so you will also need the Xcode Tools for Mac OS X, available for download at the Apple Developer Connection web site, in the Developer Tools section. After you download everything, install the WebObjects_X_Developer package in the Developer folder and restart your system. You must upgrade to WebObjects 5.2.2 via Software Update or you can get the manual update at the page About the WebObjects 5.2.2 Update.

If you don't want to build the project by hand and just want to run it, you can download the example used in this article.

The Data Model

Installing WebObjects installs a sample database in addition to the WebObjects tools. Navigate to /Library/Frameworks/JavaRealEstate.framework/Resources/ and open the RealEstate.eomodeld file. This launches EOModeler and opens the model file of a ficticious real estate database of houses in Silicon Valley. EOModeler is used to reverse-engineer databases, automatically finding all tables, columns and relationships. At runtime the WebObjects persistence engine automatically maps and generates Java objects from JDBC databases. You don't need to write any SQL code.

The image below shows the tables found in the real estate database on the left; however, EOModeler refers to them as entities. We're going to work with two of them, Listing and ListingAddress. On the right are the attributes (columns) of a Listing. You may quit EOModeler. We don't need it anymore.

Building the Server Application

The model can now be used to automatically generate a web services-enabled server application. First, launch Xcode, located in /Developer/Applications. Choose File > New Project. In the New Project Assistant, select Direct to Web Services Application. Name the project Houses. Accept the defaults until you see the Choose EOModels pane. Add the RealEstate.eomodeld model file at /Library/Frameworks/JavaRealEstate.framework/Resources. In the Build and Launch Project pane, deselect "Build and launch project now" and click Finish.

In the Xcode main window, click the triangle next to Resources. Select the Properties file and edit it so it looks like this:

WOAutoOpenInBrowser=false
WOPort=55555

Click the Build and Run button in the Xcode toolbar to build and run the application. When you see the message Waiting for requests..., the WebObjects server application is running.

Everything should look like the image below:

Configuring the Web Service

To customize a Direct to Web Services application you use the Web Services Assistant. It's located in /Developer/Applications.

After you launch the Assistant, the Connect dialog appears. Enter http://localhost:55555 in the text input field and click Connect.

Most web services define a service with one or more operations, or methods. We'll build a service HouseSearch and define an operation searchByPrice, which finds all house listings under a certain price. In addition to searching, WebObjects can generate Web service operations that let you insert, delete or update entries in a database.

In the Web Services Assistant main window, select http://localhost:55555 in the left-hand side list. Click the New Service toolbar button. Enter HouseSearch in the Service Name text field. Select Listing in the Available list of the Public Entities pane and add it by clicking the left-pointing arrow. Repeat for ListingAddress, making sure that the Enabled option is selected.

Now you add an operation to the HouseSearch Web service and define the calling arguments:

Click New Operation in the toolbar.

Enter searchByPrice in the Name text field.

Choose Listing from the Entity pop-up menu. Make sure the Type is search. Click OK.

In the main window, select askingPrice in the Available list in the Arguments pane and click the left-arrow button.

Choose "<=" from the Operator pop-up menu.

Select Return SOAP Struct.

Everything should look like the image below:

Now, define the return values for this operation:

In the Return Values pane, select askingPrice from the Available list and click the left-arrow button.

Click the triangle next to address. Select address.street and click the left-arrow button. Repeat for address.city, address.state and address.zip.

You have now defined the HouseSearch service with the searchByPrice operation that finds all houses with an asking price less than or equal to its askingPrice argument and returns an array of listings, each with their asking price and address.

Everything should look like the image below:

Testing the Service

Select searchByPrice under HouseSearch under http://localhost:55555.

Click the Test toolbar button. A test window is automatically generated with the appropriate user interface to test the searchByPrice operation.

Enter 250000 in the text input field and click Test. An empty list is returned. That is because a quarter of a million dollars won't buy a home in Silicon Valley. Try again, entering 300000. This time three entries should be returned with their asking price and address.

See the image below:

Generating WSDL Documents

Web Services Definition Language or WSDL is an XML format for describing web services and the operations they provide.

In the test window, click the WSDL tab. The WSDL document describing the HouseSearch Web service and its searchByPrice operation appears.

The WSDL document can also be retrieved directly from the server via the URL http://localhost:55555/cgi-bin/WebObjects/Houses.woa/ws/HouseSearch?wsdl. If you want to download the WSDL document and look at it, using the curl command is a convenient way to do so. In Terminal, execute the following command:

curl 'http://localhost:55555/cgi-bin/WebObjects/Houses.woa/ws/HouseSearch?wsdl' -o mywsdl.txt

Conclusion

You have developed, configured and tested a working Web service with WebObjects without writing any SOAP, XML or Java code. In addition, you learned how to obtain the WSDL description that you can publish so client applications can be built that use the service.

For more information about web services and WebObjects, please refer to the manual titled "Web Services" on the WebObjects Documentation site.

Editor's note: WebObjects can do a lot more than web services, including dynamic Web pages and distributed Java Client applications. To find out more about WebObjects, visit the Web Objects page.

Last Updated: 2004-03-09