A Bioinformatics Web Service with Mac OS X
Pages: 1, 2, 3

The WebServices Framework API's

Let's examine the low level frameworks that allow OS X developers to seamlessly integrate web services into their applications.

Apple has released WebServicesCore.Framework as part of the CoreServices API. CoreServices is a set of general use, low-level APIs which sit underneath both Carbon and Cocoa. These APIs include CoreFoundation, CarbonCore, WebServicesCore, and CoreGraphics. In this article we will be dealing with the WebServicesCore APIs.

Apple developer documentation can be found on the Apple developer site. Apple describes the WebServicesCore APIs as the toolkits and frameworks for accessing Web services from Mac OS X.

On an OS X 10.2 system the WebServicesCore APIs can be found in the folder:

/System/Library/Frameworks/CoreServices.framework/Frameworks/
   WebServicesCore.framework

The WebServicesCore API's contain two header files, WSMethodInvocation.h and WebServicesCore.h.

These files describe the methods that can be used to build web services client applications using either XML-RPC or SOAP/WSDL. We will be using the W3C's recommended SOAP style of web service invocation. For an introduction to XML-RPC Cocoa application and XML-RPC web services see http://ranchero.com/cocoa/xmlrpcdemo/.

The WSMethodInvocation.h file defines the most primitive ways to invoke a web service. The most important object defined in this file is the WSMethodInvocationRef, which is the main object used to invoke a web service, get the results back from the service, or check to see if any errors occurred. While we could use the objects that are defined in this file, Apple has supplied an application called WSMakeStubs that reads in a WSDL file and generates stubs that use this WebServicesCore.framework to execute methods against a web service that has been defined through SOAP and WSDL.

If your service does not expose its interface via WSDL, you are stuck writing all the supporting code for the service by yourself.

The WSMakeStubs Application

WSMakeStubs is a command line tool that consumes a WSDL file and generates Objective-C, C++ classes, or AppleScript code to execute methods that are defined by WSDL. A good introduction to WSDL can be found at the W3Schools web site.

The WSMakeStubs application comes with the Mac OS X 10.2 developer tools CD. Once the developer tools have been installed on your system you can find the WSMakeStubs application in /Developer/Tools/WSMakeStubs.

When invoked, the WSMakeStubs application outputs the following information:

Generates stubs for use with WebServices.framework.  
One of -url or -file must be specified.    

         -x:  the development language to use        
        -dir:  a path to the output directory where the stubs 
	           will be generated.         
               If not specified, defaults to the current working 
               directory        
       -name:  the name to be used for the root of the output file. 
               An appropriate extension will be added to
               the file[s]. The default name is WSStub.        
        -url:  url to a valid WSDL file        
       -file:  path to a valid WSDL file in the filesystem.  If 
               this is '-', the file is read from stdin        

     Available language emitters: (c++ is the default)    
         c++:  CoreFoundation with C++ bindings.  
               Additionally creates WSGeneratedStub.{cp.h}        
        ObjC:  CoreFoundation with Objective-C bindings. 
               Additionally creates WSGeneratedObj.{m,h}        
 applescript:  AppleScript        

    Tool version 0.2 (smz)

Generating the OmniGene Analysis Engine Stubs

We will be using the WSMakeStubs application to point at the OmniGene Analysis Engine. See the resources section or the OmniGene web page for a complete description of the framework. You will need to have the OmniGene Analysis Engine installed in order to follow along with the code examples.

Once OAE is installed and configured with the example "echo" service, point the WSMakeStubs application at the web service using the following command:

WSMakeStubs -x ObjC -name AnalysisStub -dir \ 
    <path_for_output_files> -url \
    http://<servername>:<port>/axis/services/Analysis?wsdl

Where <path_for_output_files> is the path where you would like to save the generated files, and <port> is the port that the OAE is listening on (typically 8080).

This will generate Objective-C stubs that can be used to execute the methods that are described in the OAE WSDL file. These stubs will be used in our example application to gain access to the OAE at runtime.

Writing The Cocoa Application

To get started writing the Cocoa application, open Project Builder, which can be found on your system at /Developer/Applications/Project Builder.app, and go to the File menu and choose "New Project".

Choose "Cocoa application" from the menu and then name the application "AnalysisApp" as shown in figures 1 and 2.

Figure 1. Choosing a new Cocoa Project.

Figure 2. Saving the application as AnalysisApp.

These two steps produce a default Cocoa project in the location you specified in the Project Directory path as shown in figure 2. After these steps have been completed, the Project Builder IDE will display your newly created project as shown in figure 3.

Figure 3. Project Builder Default Project View.

In order for our new application to use the stubs created by the WSMakeStubs application, we need to add them to our newly created project. Go to the Project Builder menu Project and select "Add Files". Find the files that you generated with the WSMakeStubs application (AnaysisStub.h, AnalysisStub.m, WSGeneratedObj.h and WSGeneratedObj.m) and add them to the AnalysisApp project. Figure 4 shows the dialog box that you will be presented with.

Figure 4. Adding the AnalysisStubs to the project.

You have now added the files to your project. Click on the AnalysisStub.h or AnalysisStub.m; you'll be presented with the source code that was generated by the WSMakeStubs application. Figure 5 shows the AnalysisStub.h source code as presented by Project Builder. You can browse all source code by using the method described above.

Figure 5. Showing source code in Project Builder.

Now that the generated files have been added to the project, we need to add the CoreServices framework to our project so that it can link against this framework and use the WebServices APIs. To do this, go to the Project Builder IDE "Project" menu and select the "Add Frameworks" menu item. Browse to /System/Library/Frameworks/ and select CoreServices.framework to add the WebServiceFramework to the project.

Pages: 1, 2, 3

Next Page