Adobe Flash Builder (formerly Adobe Flex Builder) introduces a powerful new set of tools for using remote data services. Of particular interest is Flash Builder's support for SOAP (Simple Object Access Protocol) web services, as SOAP is both a mainstay and a frequent source of headaches in the software industry. The new data service tools in Flash Builder natively automate enough of the grunt work that using a SOAP web service is almost trivial.
This two-part series (see Part 2
) shows how to use Flash Builder to rapidly build a SOAP-driven map search application called TerraClient. Part 1-this article-shows how to automatically bind to SOAP services, generate a search form, and handle the initial search results. Part 2 will show you how to handle the multiple asynchronous SOAP requests and responses needed to display the map imagery. Figure 1 shows the finished product.
Figure 1. TerraClient:
A map client of SOAP web services built with Flash Builder.
To get map data and imagery for TerraClient, you'll use the public TerraService web service hosted on MSR Maps. The data center behind MSR Maps is owned and operated by Microsoft, but the map data and imagery are provided by the U.S. Geological Survey. The website -- formerly TerraServer USA -- provides a well-documented set of public SOAP web services that you can call directly from Flash Builder.
To run the code used in this article, you need Flash Builder version 4 build 2 or later. If you haven't installed it yet, I recommend getting the Flash Builder 4 Standalone Installer instead of the Flash Builder 4 Plug-in for Eclipse. When Flash Builder is installed and ready to go, you're only a few minutes away from using a SOAP web service.
Step 1: Initial Project Setup
Skipping the initial project setup and getting right to the good stuff, begin by downloading terraclient_initial.fxp. Then, import the file into Flash Builder:
1. Launch Flash Builder, and then click File > Import.
2. Select Flash Builder Project as the Import Source, and then click Next.
3. Select Import Project, and then browse to the location of terraclient_initial.fxp.
4. Edit the Extract new project(s) to path, and remove the trailing _final from the project folder name. When you're done, the project path should look like
…/terraclient instead of …/terraclient_initial.
5. Click Finish.
You should now have a basic Flex project-four basic components with some minimal user interface (UI) scaffolding-loaded and ready to use. Here are the components:
* src/TerraClient.mxml. This is the application entry point. For this project, its role is simply to assemble the other components.
* src/client/SearchForm.mxml. This file contains a search form used to query the TerraService for a list of location names. It also holds the list of locations that the query returns.
* src/client/ImageOptions.mxml. This utility class simply provides two drop-down menus to specify the kind of map imagery desired.
* src/client/PlaceMap.mxml. This component is the workhorse that assembles the map tile images. You'll use what you learned from the Flash Builder-generated code in Search Form to create programmatic variations in the PlaceMap component.
Step 2: Connecting to the SOAP Service
In this step, you use Flash Builder's Data Service tools to connect to the web service, then generate a service proxy with its related value objects.
From the Flash perspective, click Window > Open Perspective > Flash. Your window configuration should look similar to Figure 2.
The initial SearchForm.mxml file as viewed in the Flash perspective.
Take a look at the Data/Services tab at the bottom of your window. You'll use this tool to connect to the TerraService Web Services Description Language (WSDL) file and create a local proxy for the GetPlaceList operation.
Click the Connect to Data/Service link to open the wizard. Then, perform the following steps:
1. Select the Service Type: "Web Service" option, and then click Next.
2. Specify WSDL to Introspect:
* Keep the default option to access the web service directly from the client.
* In the WSDL URI field, enter the WSDL location for TerraService (http://msrmaps.com/TerraService2.asmx?WSDL).
* Service name: Keep the default value of TerraService2.
* Service package: Type server.services.terraservice2 to put the Service proxy classes into a top-level server package.
* Data type package: Type server.valueObjects to place the value objects package within the top-level server package.
3. Click Next.
4. The Configure Code Generation wizard step shows all of the operations available in the TerraService WSDL file. For now, keep things simple:
* Clear all of the web service operations with the Deselect All button
* Select the GetPlaceList operation, and then click Finish.
As the wizard closes, Flash Builder generates code for the TerraService2 proxy, the GetPlaceList operation, and the value objects used in both the request and the response. The items on the Data/Service tab, shown in Figure 3, provide a logical view of the data types and operations related to the newly generated TerraService2 proxy. There is also a new /src/server package in the Package Explorer with all of the generated source code.
The new service object and value objects generated using WSDL.
Step 3: Generate the Search Form
With the service and value objects generated, you are going to generate a search form for the GetPlaceList operation. This form lets users type a place name, submit it to the web service, and get back a list of matching places. You will then add a List component to display the search results.
To get started, open /src/client/SearchForm.mxml. There's basically nothing in the file yet, but that's about to change. Return to the Data/Service panel, and then open the logical tree under TerraService2. Right-click the GetPlaceList operation, and then click Generate Form (see Figure 3). The form generated will be inserted into the SearchForm.mxml component.
In the Generate Form wizard, perform the following steps:
1. Configure the wizard options:
* Generate form for: Keep the Service call default.
* New Service Call: This option should be selected.
* Service: Keep the TerraService2 default.
* Operation: Keep the GetPlaceList default.
* Create: Select Form for input parameters, but clear the Form for return type option. Because GetPlaceList returns an array of PlaceFacts, generating a form for the return type isn't useful. You'll handle displaying the search results using a List.
2. Click Next.
3. On the Property Control Mapping wizard page, keep the defaults, and then click Finish.