Creating Data-Driven Applications with

ADOBE FLEX 4
® ®

Prerelease Adobe Confidential - 01/06/2009

© 2009 Adobe Systems Incorporated. All rights reserved.
Copyright

Creating Data-Driven Applications with Adobe® Flex® 4. Prerelease version.

This pre-release version of the Software may not contain trademark and copyright notices that will appear in the commercially available version of the Software.
Adobe, the Adobe logo, ActionScript, Adobe AIR, ColdFusion, Dreamweaver, Flash, Flash Player, Flex, Flex Builder, and LiveCycle are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Microsoft and Windows are either registered trademarks
or trademarks of Microsoft Corporation in the United States and/or other countries. Apple, Macintosh, and Mac OS are trademarks of Apple Inc., registered in
the United States and other countries. Java is a trademarks or registered trademark of Sun Microsystems, Inc. in the United States and other countries. Linux is
the registered trademark of Linus Torvalds in the U.S. and other countries. All other trademarks are the property of their respective owners.
This Work is licensed under the Creative Commons Attribution Non-Commercial 3.0 License. To view a copy of this license, visit
http://creativecommons.org/licenses/by-nc-sa/3.0/
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.

Prerelease Adobe Confidential - 01/06/2009

 iii

Contents
Chapter 1: Accessing data services overview
Accessing remote data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Compare data access in Flex to other methodologies ................................................................... 2
Access data services with Flash Builder ................................................................................. 4

Chapter 2: Implementing services for data-centric applications

Action Message Format (AMF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Implementing ColdFusion services ..................................................................................... 6
Implementing PHP services ............................................................................................ 6
Debugging remote services ........................................................................................... 7

Chapter 3: Building data-centric applications with Flash Builder

Connecting to remote data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Building the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Configuring return types for a data service operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Managing the access of data from the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Flash Builder code generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Deploying applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 4: Accessing Server-Side Data with Flex

Using HTTPService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using WebService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Using RemoteObject components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Explicit parameter passing and parameter binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Handling service events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Prerelease Adobe Confidential - 01/06/2009

 1

Chapter 1: Accessing data services

overview
You can access three types of data services in Adobe Flex: HTTP (REST-style) services, web services, and remote object
services.
Adobe Flash Builder provides wizards and tools to connect to remote services and generate client application code.
The application accesses operations on the service by using data access components.
If you are not using Flash Builder, you can write MXML or ActionScript code to implement data access components.

Accessing remote data

Flex data access components use remote procedure calls to provide data to client applications and send data to back-
end data sources. Flex interacts with server environments such as PHP, Adobe ColdFusion, and Microsoft ASP.NET.
Depending on the interface to a particular server-side application, you connect to an application using one of the
following methods:
• Remote object services, using Adobe Action Message Format (AMF)
• HTTP GET or POST (REST-style web services)
• Simple Object Access Protocol (SOAP) compliant web services

Remote object services using AMF

Remote object services let you access business logic directly in its native format rather than formatting it as XML, as
you do with REST-style services or web services. This saves you the time required to expose existing logic as XML.
Another benefit of remote object services is the speed of communication across the wire. Data exchanges still happen
over HTTP or https, but the data itself is serialized into a binary representation. This results in less data going across
the wire, reduced client-side memory usage, and reduced processing time.
ColdFusion, PHP, BlazeDS, and Adobe LiveCycle Data Services ES can use server-side typing when accessing data on
the server. The client application accesses a Java object or ColdFusion component (which is a Java object internally)
directly by remote invocation of a method on a designated object. The object on the server can then deal with its native
data types as arguments, query a database from those arguments, and return its native data types as values.
When server-side typing is not available, Flash Builder has tools to implement client-side typing. Use the Flash Builder
tools to configure and define types for data returned from the service. This allows the client application to query a
database and retrieve properly typed data.
Client-side typing is required for any service that does not define the type of data returned by the service.

REST-style services
Another common name for an HTTP service is a REST-style web service. REST stands for Representational State
Transfer, an architectural style for distributed hypermedia systems.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 2
Accessing data services overview

For REST-style services, you use a server resource such as a PHP page, JavaServer Page (JSP) or servlet, or ColdFusion
page that receives a POST or GET request from an application using the HTTPService component. That server
resource then accesses a database using whatever means are traditional to the particular server technology.
The results of data access can be formatted as XML instead of HTML, as might be typical with the server technology,
and returned as the response to the application. Flex, Adobe Flash Player, and Adobe AIR have excellent XML-
handling capabilities that let you manipulate the data for display in the application’s user interface. REST-style services
provide an easy way to access a server resource without a more formalized API such as those provided by web services
or remote object services. These services can be implemented using any number of server technologies that can get an
HTTP request and return XML as the response.
For more information about REST, see Representational State Transfer (REST) chapter of Architectural Styles and the
Design of Network-based Software Architectures by Roy Thomas Fielding.

Web services
SOAP-compliant web services are a standardized type of REST-style service. Rather than accessing a PHP, JSP, or
ColdFusion page specifically, an application accesses a web service endpoint. Based on published specifications, a web
service knows the format in which the data was sent and how to format a response.
Many server technologies provide the ability to interact with applications as web services. Because web services comply
with a standard, you don't need to know the implementation details of the code with which an application interacts.
This is useful for applications, such as business-to-business applications, that require a high degree of abstraction.
However, SOAP is often verbose and heavy across the wire, which can result in higher client-side memory
requirements and processing time than working with informal REST-style services.

Compare data access in Flex to other methodologies

The way that Flex works with data sources and data is different from other web application environments, such as JSP,
ASP, PHP, and ColdFusion.

Client-side processing and server-side processing

Unlike a set of HTML templates created using JSPs and servlets, ASP, PHP, or CFML, Flex separates client code from
server code. The application is compiled into a binary SWF file that is sent to the client.
When the application makes a request to an external service, the SWF file is not recompiled and no page refresh is
required. The remote service returns only data. Flex binds the returned data to user interface components in the client
application.
For example, in Flex, when a user clicks a Button control in an application, client-side code calls the web service. The
result data is returned into the binary SWF file without a page refresh. The result data is then available to use as
dynamic content in the application.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 3
Accessing data services overview

<?xml version="1.0"?>
<!-- fds\rpc\RPCIntroExample2.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<!-- Declare a WebService component (the specified WSDL URL is not functional). -->
<mx:WebService id="WeatherService"
destination="wsDest"/>

<mx:Button label="Get Weather"

click="WeatherService.GetWeather(input.text);"/>

<mx:TextInput id="input"/>
</mx:Application>

Compare this Flex example to the following example, which shows JSP code for calling a web service using a JSP
custom tag. When a user requests the JSP, the web service request is made on the server instead of on the client. The
result is used to generate content in the HTML page. The application server regenerates the entire HTML page before
sending it back to the user's web browser.
<%@ taglib prefix="web" uri="webservicetag" %>

<% String str1="BRL";

String str2="USD";%>

<!-- Call the web service. -->

<web:invoke
url="http://www.itfinity.net:8008/soap/exrates/default.asp"
namespace="http://www.itfinity.net/soap/exrates/exrates.xsd"
operation="GetRate"
resulttype="double"
result="myresult">
<web:param name="fromCurr" value="<%=str1%>"/>
<web:param name="ToCurr" value="<%=str2%>"/>
</web:invoke>

<!-- Display the web service result. -->

<%= pageContext.getAttribute("myresult") %>

Data source access

Another difference between Flex and other web application technologies is that you never communicate directly with
a data source in Flex. You use a Flex service component to connect to a server-side service that interacts with the data
source.
The following example shows one way to access a data source directly in a ColdFusion page:
...
<CFQUERY DATASOURCE="Dsn"
NAME="myQuery">
SELECT * FROM table
</CFQUERY>
...

To get similar functionality in Flex, you use an HTTPService, a web service, or a RemoteObject component to call a
server-side object that returns results from a data source.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 4
Accessing data services overview

Events, service calls, and data binding

Flex is an event driven technology. A user action or a program event can trigger access to service. For example, a user
clicking a button is an event that can trigger a service call. An example of a program event is when the application
completes the creation of a user interface component such as a DataGrid. The creationComplete event can then call a
remote service to populate the DataGrid.
Service calls in Flex are asynchronous. The client application does not have to wait for returned data. Asynchronous
service calls provide additional benefits when retrieving or updating large sets of data.
Data returned from a service call is stored in a CallResponder property associated with the service call. User interface
components then use data binding to retrieve returned data from the CallResponder.
Data binding in Flex allows you to dynamically update a user interface component with a data source. For example, a
Flex component can associate its text attribute with the lastResult attribute of a CallResponder. When the data changes
in the CallResponder, the Flex component is automatically updated.
Flex also implements two-way data binding. With two-way data binding, when data changes in either the Flex
component or the data source, the corresponding data source or Flex component automatically updates. Two-way
data binding is useful when updating remote data from the user inputs to a Form component or a Flex data
component.

Access data services with Flash Builder

Flash Builder provides wizards and other tools to connect to remote services and bind returned data to user interface
components. Flash tooling generates client code for accessing remote services, and also for synchronizing data
management and paged data retrieval.

Flash Builder workflow for accessing services

Use the following workflow when using Flash Builder to create an application that accesses data services.
1 Connect to remote service or Build user interface.
Depending on your circumstances, you start by connecting to the remote service or by building the user interface.
Connect to remote service. If you start by connecting to the remote service, you must then build the user interface.
Build user interface. If you start by building the user interface, you must then connect to the remote service.
Note: Where you start is a matter of personal preference. For example, if you already have a user interface design
planned, you might build the user interface first. Conversely, you might connect to the data first and let Flash Builder
assist you in generating application components.
2 Bind data operations to application components.
Flash Builder has several ways to assist you in binding data operations to application components. You can generate
Forms or data components for a service data type or for specific service operations. You can also select a user
interface component and navigate the service operations to select the appropriate operation to bind to.
3 (Optional) Manage the retrieval and update of data.
Flash Builder tools allow you to implement the paging of returned data and coordinate the update of sets of data.
When returning large amounts data records, you typically implement paging to retrieve a set of records on an “as
needed” basis.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 5
Accessing data services overview

For applications that updates several records, you can implement data management features. Data management
allows you to update all changed records simultaneously. Data management also provides undo operations to revert
changes.
4 Run the application and monitor the data flow.
Once the application is complete you run the application to view it in operation. Use the Flash Builder Network
Monitor to view data passed between the application and the service. The Network Monitor is useful for diagnosing
errors and analyzing performance.
Flash Builder also provides robust debugging and profiling environments.
See “Building data-centric applications with Flash Builder” on page 9 for more information.

Accessing Flex service components directly

In Flex Builder 3, you implement remote procedure calls to data services using Flex data access components. The tools
available with Flash Builder 4 simplifies this process by generating code for data access components and binding the
returned data to user interface components.
However, you can bypass the Flash Builder tools and implement your own remote procedure calls to data services. See
“Accessing Server-Side Data with Flex” on page 27 for information on writing code to access to data services.

Extending services supported by Flash Builder

Flash Builder wizards and tools support access to the following type of service implementations:
• PHP services
• ColdFusion services
• BlazeDS
• LiveCycle Data services
• HTTP (REST-style) services
• Web services (SOAP)
• ASP.NET
If you need tooling support for additional types of services, such as Ruby on Rails, you can extend the Flash Builder
implementation. See Extending Service Support in Flash Builder for more information.

Prerelease Adobe Confidential - 01/06/2009

 6

Chapter 2: Implementing services for data-

centric applications

Action Message Format (AMF)

Flex uses remote object services and AMF to access services implemented in ColdFusion, PHP, BlazeDS, and Adobe
LiveCycle Data Services ES. AMF provides the messaging needed to exchange data between a database and the client
application.
ColdFusion, BlazeDS, and Adobe LiveCycle Data Services ES each provide an AMF framework for remote object
services. For services implemented in PHP, Flash Builder uses the Zend AMF framework.
ColdFusion and PHP services can provide server-side typing. In server-side typing, the type of data returned.
However, if the service implementation does not define the return data type, Flash Builder provides client-side typing.
Flash Builder samples data from the service, allowing you to configure the return type in the client application.

Implementing ColdFusion services

When implementing services in ColdFusion, the services should be implemented as ColdFusion component (CFC)
files. The classes do not necessarily have to be object-oriented classes. Rather, each class can be a library of functions
that provide the service operations.
You can create ColdFusion services in any editing environment, such as DreamWeaver or Bolt. Flash Builder does not
provide an editor optimized for editing ColdFusion files. However, if you open a ColdFusion file in Flash Builder, Flash
Builder launches the application on your system associated with ColdFusion files.
Flash Builder Premium provides the Bolt editing environment, which is optimized for creating ColdFusion services.

Implementing PHP services

When implementing services in PHP, the services should be implemented as PHP classes. The classes in PHP do not
necessarily have to be object-oriented classes. Rather, each class can be a library of functions that provide the service
operations.
You can create PHP services in any editing environment, such as DreamWeaver or Zend Studio. Flash Builder does
not provide an editor optimized for editing PHP files. However, if you open a PHP file in Flash Builder, Flash Builder
launches the application on your system associated with PHP files.

Accessing services using Zend AMF Framework

PHP data services are available using Action Message Format (AMF). AMF provides messaging between a Flash client
and the database server. Flash Builder uses the Zend AMF framework to implement AMF messaging for PHP data
services.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 7
Implementing services for data-centric applications

Note: Although Flash Builder uses the Zend AMF framework, you are not required to use Zend components when
creating PHP services. Although Zend components work well with Flash Builder, you can also use any PHP development
environment for creating services.

Installing Zend Framework

When accessing PHP services for the first time, Flash Builder determines if the Zend Framework is installed on your
computer. If the Zend Framework is not installed, Flash Builder prompts you to confirm installation of the Zend
Framework. If you accept, Flash Builder installs the Zend Framework into the default location, which is the root
directory of your web server. The installation also modifies your php.ini file.

Debugging remote services

There are several ways to debug applications that access remote services. You can use the Network Monitor, to view
data sent between the server and client. You can also write scripts to test server code and write output stream
information to log files.

Network Monitor
The Network Monitor is available in Flash Builder from the Flex Debugging Perspective. The monitor must be enabled
before it can be used to monitor data. Refer to Network Monitor for details about enabling and using the Network
Monitor.

Scripts to test server code

Use test scripts to view and debug server code before attempting to connect to the server in Flash Builder. Test scripts
provide the following benefits:
• You can view test results from a web browser.
As you make changes to the code, simply refresh the browser page to view the results.
• You can echo or print results to the output stream, which you cannot do directly from AMF.
• Error displays are nicely formatted and generally more complete than errors captured using AMF.

ColdFusion Scripts
Use the following script, tester.cfm, to dump a call to a function.
<!--- tester.cfm --->
<cfobject component="EmployeeService" name="o"/>
<cfdump var="#o.getAllItems()#">

In tester2.cfm, you specify the method and arguments to call in the URL.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 8
Implementing services for data-centric applications

<!--- tester2.cfm --->

<cfdump var="#url#">

<cfinvoke component="#url.cfc#" method="#url.method#" argumentCollection="#url#"

returnVariable="r">

<p>Result:

<cfif isDefined("r")>
<cfdump var="#r#">
<cfelse>
(no result)
</cfif>

For example, call the getItemID method in EmployeeService with the following URL:
http://localhost/tester2.cfm?EmployeeService&method=getItemId&id=12

tester3.cfm writes a log that records calls to operations and dumps the input arguments using cfdump.
<!--- tester3.cfm --->
<cfsavecontent variable="d"><cfdump var="#arguments#"></cfsavecontent>

<cffile action="append"
file="#getDirectoryFromPath(getCurrentTemplatePath())#MyServiceLog.htm"
output="<p>#now()# operationName #d#">

PHP Scripts
Use the following script, tester.php, to dump a call to a function.
<pre>
<?php
include('MyService.php');
$o = new MyService();
var_dump($o->getAllItems());
?>
</pre>

Add the following code to your PHP service to log messages during code execution.
$message = 'updateItem: '.$item["id"];
$log_file = '/Users/me/Desktop/myservice.log';
error_log(date('d/m/Y H:i:s').' '.$message.PHP_EOL, 3, $log_file);

Add the following code to your PHP service to enable dumping to a log file:
ob_start();
var_dump($item);
$result = ob_get_contents();
ob_end_clean();

$message = 'updateItem: '.$result;

$log_file = '/Users/me/Desktop/myservice.log';
error_log(date('d/m/Y H:i:s').' '.$message.PHP_EOL, 3, $log_file);

Prerelease Adobe Confidential - 01/06/2009

 9

Chapter 3: Building data-centric

applications with Flash Builder
The workflow for accessing data services using Flash Builder is not a sequential process. For example, many developers
start with building a client application before creating or configuring access to the server. Other developers start with
creating and configuring services, including managing the access of the data.

Connecting to remote data

Connecting to remote data requires a Flex server project. From the Flex server project, you connect to an existing
remote service. You then configure custom data types for data retrieved from the data service.
• “Creating a server project” on page 9
• “Building the client application” on page 14
• “Configuring return types for a data service operation” on page 17
• “Managing the access of data from the server” on page 18
• “Flash Builder code generation” on page 21
• “Deploying applications” on page 26

Creating a server project

Create a Flex project that corresponds to the data service you are accessing. ColdFusion and PHP server projects
support AMF-based services for access to data on the server. Additionally, all projects support connecting to HTTP
(REST-style) services and web services (SOAP).
A cross-domain policy file is necessary when accessing services that are on a different domain from the SWF file for
the application. Typically, AMF-based services do not need a cross-domain policy file because these services are on the
same domain as the application. For more information, see Using cross-domain policy files

Types of server projects

You can create the following types of Flex server projects:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 10
Building data-centric applications with Flash Builder

Server Type Services supported

PHP • AMF-based PHP services

• Web services

• HTTP services

ColdFusion • ColdFusion Flash Remoting

• BlazeDS

• LiveCycle Data Services

• Web services

• HTTP services

J2EE • Web services

• HTTP services

ASP.NET

No server specified • Web services

• HTTP services

For more information about creating Flex projects, see Working with Projects.

Changing the server type of a project

Flex server projects are configured to access specific types of services. Flash Builder warns you if you attempt to access
a type of service for which the project is not configured. For example, Flash Builder warns you if you try to connect to
a PHP service from a ColdFusion server project.
However, if you did not specify a server type when you created a Flex project, you can change the server configuration.
The service configuration for a project is available from Project >Properties > Flex Server. Flash Builder takes you to
the Flex Server properties page when you attempt to connect to a service that requires a server project.

Working with ColdFusion services

Before connecting to a ColdFusion data service, create a server project for ColdFusion and make that the active project.
When creating the project, select a remote access object service.
For ColdFusion, you have three options:
• LiveCycle Data Services
• BlazeDS
• ColdFusion Flash Remoting
You can only specify one ColdFusion remote access object service in a project. The remote service must be available
under the web root you specified when creating the project. All applications in the project have access to the remote
service.

Connecting to ColdFusion data services

1 Make sure that you have a Flex server project for ColdFusion and that it is the active project.
Note: To make a project active, open an application file in the project and make it the active file in the editor.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 11
Building data-centric applications with Flash Builder

2 From the Flash Builder Data menu, select Connect to Data/Service.

Flash Builder provides various ways to connect to the data service:
• Flash Builder Data menu
• Data/Services View Data menu
• Data/Services View context menu
3 In the Select Service Type dialog, select ColdFusion. Click Next.
4 In the Configure ColdFusion Service dialog, indicate whether to import an existing CFC or generate code stubs for
a sample CFC:
• Import CFC: Navigate to the location of an existing ColdFusion service.
Flash Builder suggests a name for the service, which you can change.
• Generate Sample CFC: Flash Builder generates a sample CFC with commented service functions. Use the sample
as a starting point for implementing a ColdFusion service.
When generating a sample CFC, specify the name of the service and its location.
5 (Optional) Modify the generated package name for the service.
Flash Builder generates ActionScript classes in the specified package. The generated class files provide access to
service operations from the client application.
6 (Optional) If you are importing a service, click Next if you want to view the service operations.
7 Click Finish.
Flash Builder does the following:
• If you are creating a CFC, Flash Builder generates a CFC file that contains functions for common service
operations.
• Flash Builder launches the editor on your system for editing ColdFusion files, opening the CFC file.
• The operations for the service are available in the Data/Services view.
• Flash Builder generates ActionScript classes that provide access to service operations from the client application.
8 Modify the implementation of your service.
If you are creating a service, the generated stubs contain suggestions for operations to access a database.
The functions in the sample CFC are suggestions, not requirements. Modify or replace the code in your service as
necessary. You can modify parameters to operations and add additional functions.
9 (Optional) If you modify a service, select Refresh from the context menu.
Modifications requiring a refresh include the following:
• Changing an operation signature
• Adding an operation
• Removing an operation
After implementing the service, see configuring the return types for the data service.

Working with PHP services

PHP data services are available using Action Message Format (AMF). AMF provides messaging between a Flash client
and the database server. Flash Builder installs the Zend AMF framework to provide access to PHP services.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 12
Building data-centric applications with Flash Builder

Note: You are not required to use Zend components when creating PHP services. Although Zend components work well
with Flash Builder, you can use any PHP development environment for creating services.
Before connecting to a PHP data service, you must first create a server project for PHP and make that the active project.
The data service must be available under the web root you specified when creating the project. All applications in the
project have access to the remote service.

Connecting to PHP data services

1 Make sure that you have a Flex Server project for PHP and that it is the active project.
Note: To make a project active, open an application file in the project and make it the active file in the editor.
2 From the Flash Builder Data menu, select Connect to Data/Service.
Flash Builder provides various ways to connect to the data service:
• Flash Builder Data menu
• Data/Services View Data menu
• Data/Services View context menu
3 In the Select Service Type dialog, select PHP. Click Next.
4 In the Configure PHP Service dialog, indicate whether to import an existing PHP class or generate code stubs for a
sample PHP class:
• Import PHP Class: Navigate to the location of an existing PHP class service.
Flash Builder suggests a name for the service, which you can change.
• Generate Sample PHP Class: Flash Builder generates a sample PHP class file with commented service functions.
Use the sample as a starting point for implementing a PHP service class.
When generating a sample PHP class, specify the name of the service and its location.
5 (Optional) Modify the generated package name for the service.
6 (Optional) If you are importing a service, click Next if you want to view the service operations.
7 Click Finish.
Flash Builder does the following:
• If you do not have the Zend AMF framework installed on your system, Flash Builder prompts you to install Zend
AMF.
• If you are creating a PHP class, Flash Builder generates a PHP class file that contains stubs for common service
operations.
• Flash Builder launches the editor on your system for editing PHP files, opening the PHP class file.
• The operations for the service are available in the Data/Services view.
8 Modify the implementation of your service.
If you are creating a service, the generated stubs contain suggestions for operations to access a database.
The functions in the sample PHP class are suggestions, not requirements. Modify or replace the code in your service
as necessary. You can modify parameters to operations and add additional functions.
9 (Optional) If you modify a service, select Refresh from the context menu.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 13
Building data-centric applications with Flash Builder

Modifications requiring a refresh include the following:

• Changing an operation signature
• Adding an operation
• Removing an operation
After implementing the service, see configuring the return types for the data service.

Working with HTTP (REST-style) services

You can create applications that connect to REST-style HTTP services. You can connect to HTTP services from any
Flex project. You do not have to specify a server technology for the project.
A cross-domain policy file is necessary when accessing services that are on a different domain from the SWF file for
the client application. For more information, see Using cross-domain policy files.

Connecting to HTTP services

1 Select a Flex project for the application that accesses HTTP services.
2 From the Flash Builder Data menu, select Connect to Data/Service.
3 In the Select Service Type dialog, select HTTP. Click Next.
4 Specify a name for the service.
5 Click Add to add operations.
Note: You do not have to add the initial operation.
6 Specify GET operations for the service:
a Specify a name for the GET operation.
b Specify GET for the method.
c Specify a URL for the service.
Include any parameters to the service in the URL. For example, to access the Flickr photo service, specify this URL:
http://api.flickr.com/services/feeds/photos_public.gne?format=x&tags=y

Note: When specifying parameters, include values for the parameters. You can modify the values for the
parameters when configuring service operations.
7 Specify POST operations for the service:
• Specify a name for the POST operation.
• Specify POST for the method.
• Specify the Content Type for the POST operation.
• Add parameters for the POST operation.
8 (Optional) Modify the generated package name for the service.
9 Click Finish.
Flash Builder adds the HTTP service to the Data/Services view.
Expand the service to view the available operations.
After connecting to the HTTP service, configure the return type for the operation. See “Configuring return types for
a data service operation” on page 17 for details.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 14
Building data-centric applications with Flash Builder

Working with web services

Placeholder for documentation of web services.

Building the client application

Use the Flash Builder code editor to create a user interface. You can use the editor either in Design View or Source
View. You can also generate a Form from service operations in the Data/Services view.
After laying out the components for the application, generate event handlers as needed for user interaction with the
application.

Using Design View to build an application

In Design View of the MXML editor drag-and-drop components from the Components View into the Design Area.
Then arrange the components and configure their properties. After designing the application layout, bind data
returned from the data service to the components.

Controls
Flex provides a rich set of user-interface components such as Button, TextArea, and ComboBox controls. You place
controls in containers. Containers are user-interface components that provide a hierarchical structure for controls and
other containers.
Flex provides various data-driven controls that are ideal for displaying sets of data in lists, tables, or trees.

Data Controls

DataGrid

AdvancedDataGrid

OLAPDataGrid

List

TileList

Tree

For more information, see Data-driven controls.

Binding service operations to controls

There are several ways to bind service operations to a control component. You can drag service operation from the
Data/Service View onto a component in Design View. You can also open the Bind to Data dialog to select an operation
to bind to a component.
When you bind a service operation to a control component, Flash Builder generates MXML and ActionScript code to
access the service operation from the client application.

Bind a service operation to a DataGrid control (drag-and-drop)

This procedure assumes that you have connected to a data service. It also assumes that you have configured the data
return type for a service operation so it returns a set of records.
1 In Design View, drag a DataGrid component from Components View to the editing area.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 15
Building data-centric applications with Flash Builder

2 Drag an operation from the Data/Services View onto the DataGrid component.
The DataGrid component changes to show the fields retrieved from the database.
3 Customize the display of the DataGrid.
4 Save and run the application.

Bind a DataGrid control to a service operation (Bind to Data dialog)

This procedure assumes that you have connected to a data service and the data return type for operations have been
configured.
1 In Design View, drag a DataGrid component from Component View to the editing area.
2 Open the Bind to Data dialog using one of the following methods:
• Select Bind to Data from either the Flash Builder Data menu or the DataGrid context menu.
• Select the Bind to Data button in the Property Inspector.
3 Select New Service Call, then select a Service and Operation.
4 (Optional) Select Change Return Type:
Select Change Return Type if you want to reconfigure the return type for the service operation.
If the return type for the operation has not been previously configured, select Configure Return Type to continue.
See “Configuring return types for a data service operation” on page 17.
5 Click OK.
The DataGrid component changes to show the fields retrieved from the database.
6 Customize the display of the DataGrid.
7 Save and run the application.

Generating a Form for an application

Flash Builder can generate several types of Forms for accessing data services.

Form Description

Custom data type Contains entries for each field of a custom

data type for a service

Master -detail Form Contains entries for a selected item in a

data control, such as a DataGrid or a List

Service call Displays the data returned from a service

call

When generating Forms, specify which fields to include and whether to make the Form editable. You can also specify
the type of user interface control to represent the Form items.

Generating a Form for a service call

This procedure assumes that you have connected to a data service and that you are in Design View of the MXML
Editor.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 16
Building data-centric applications with Flash Builder

This procedure shows how to generate a Form for a service call. The procedure for generating other types of Forms are
similar.
1 There are several ways to run the Generate Form wizard:
• From the Data/Service View, select an operation from the context menu. Select Generate Form.
• From the Flash Builder Data menu, select Generate Form or Generate Details Form
• Select a Data Control in Design View. From the context menu, select Generate Details Form
2 In the Generate Form wizard, select Generate Form for Service Call.
3 Select New Service Call, then specify the Service and Service Operation.
4 Configure the return type (or change the return type) for the selected operation.
The return type for the operation must be configured before you can generate the Form. If you previously
configured a return type, you have the option to change the return type.
See “Configuring return types for a data service operation” on page 17.
5 Specify whether to include Forms for input parameters and return type.
6 Specify whether to make the Form editable. Click Next.
7 In the Property control Mapping dialog, select which fields to include in the Form and the type of control to
represent the data.
8 Click Finish.

Generating event handlers

When you bind a data service operation to a component, Flash Builder generates an event handler that retrieves data
from the service to populate the component.
For example, if you bind an operation such as getAllItems() to a DataGrid, Flash Builder generates a creationComplete
event handler.
<DataGrid creatonComplete="getAllItemsResult.token = productService.getAllItems()" ... >

When you run the application, once the DataGrid has been created it populates itself with data retrieved from the
service.
You can accept the generated event handlers or replace them with others according to your needs. For example, you
can replace the creationComplete event handler on the DataGrid with a creationComplete handler on the Application.
You can also generate or create event handlers for Controls that accept user input, such as Buttons or Text. Do either
of the following to generate event handlers:
• From the Data/Services view, drag an operation onto the Control.
Flash Builder generates an event handler for the default event for the component. For example, for a Button, the
event handler would be the Click event.
• In Design View, select the Control and then in the Property Inspector, click the generate event icon.
Flash Builder opens the Source View of the editor and generates a stub for the event handler.
Fill in the remaining code for the event handler. Flash Builder provides Content Assist to help you code the event
handler.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 17
Building data-centric applications with Flash Builder

Configuring return types for a data service operation

When connecting to a data service, Flash Builder needs to know the data type for the data returned by a service
operation. The data types supported are those types recognized by AMF to exchange data with a database.
Many services define the type of returned data on the server (server-side typing). However, if the server does not define
the type, then the client application must configure the type for returned data (client-side typing).
When configuring return types for client-side typing, the data type must be recognized by AMF. The type can be an
ActionScript data type, a custom data type representing complex data, or void to indicate the operation does not return
any data. The following table lists possible data types for client-side typing.

Data Type Description

ActionScript types Boolean

Boolean[]

Date

Date[]

int

int[]

Number

Number[]

String

String[]

No data returned void

User-defined type CustomType

CustomType[]

Typically, you define custom data types for service operations that return complex data. For example, if you are
retrieving records from an employee database, then you would define the return type as Employee. In this case, the
custom data type for Employee would contain entries for each field in the record, as listed in the following table:
Employee Custom Data Type

Field Data Type

emp_no Number

first_name String

last_name String

hire_date Date

birth_date Date

Configuring the return type for data from a PHP or ColdFusion service
To configure the return type, Flash Builder samples the data returned by an operation. Then you define or specify a
data type.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 18
Building data-centric applications with Flash Builder

This procedure assumes that you have already connected to a remote data service.
1 In the Data/Services view, from the context menu for an operation, select Configure Return Type.
2 In the Configure Operation Return Type dialog, specify either a name for a new custom type or select an existing type.
You can select a data type from the drop-down list, or define a custom data type for the returned data.
For example, if you are returning a list of employees with associated data, then you might define the return type as
Employee.
3 If you select an existing data type or a previously defined data type that does not need to be updated, click Finish.
4 If you are defining a new data type, or are updating a previously defined data type, click Next.
If the data returned is not what you expect, or you encounter errors, click Cancel. Modify the implementation of
the service. If you modified the signature or return type, refresh the service. Then try again.
Note: When troubleshooting the implementation of the service, it is often easier to write test scripts that access the
service from a web browser. Analyze the results of those scripts to troubleshoot the service implementation. For
information on test scripts, see Debugging applications for remote services.
5 View and edit the properties of the returned data and click Finish.

Configuring the return type for data from an HTTP service

To configure the return type, Flash Builder samples the data returned by an operation. Then you define or specify a
data type.
This procedure assumes that you have already connected to a remote data service.
1 In the Data/Services view, from the context menu for an operation, select Configure Return Type.
2 In the Configure Operation Return Type dialog, specify either a name for a new custom type or select an existing type.

Managing the access of data from the server

Paging Paging is the incremental retrieval of large data sets from a remote service.

For example, suppose you want to access a database that has 10,000 records and then display the data in a DataGrid
that has 20 rows. You can implement a paging operation to fetch the rows in 20 set increments. When the user requests
additional data (scrolling in the DataGrid), the next page of records is fetched and displayed.
Data management In Flash Builder, data management is the synchronization of updates to data on the server from
the client application. Using data management, you can modify one or more items in a client application without
making any updates to the server. You then commit all the changes to the server with one operation. You can also
revert the modifications without updating any data.
Data management involves coordinating several operations (create, get, update, delete) to respond to events from the
client application, such as updating an Employee record.

Enabling paging
To enable paging your data service must implement a function with the following signature:
getItems_paged(startIndex:Number, numItems:Number): myDataType

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 19
Building data-centric applications with Flash Builder

function name You can use any valid name for the function.

startIndex The initial row of data to retrieve.

The data type for startIndex should be defined as Number in the client
operation.

numItems The number of rows of data to retrieve in each page.

The data type for numItems should be defined as Number in the client
operation.

myDataType The data type returned by the data service.

When implementing paging from a service, you can also implement a count() operation. A count() operation returns
the number of items returned from the service. The count operation must implement the following signature:
count(): Number

function name You can use any valid name for the function.

Number The number of records retrieved from the operation.

Flex uses the count operation to properly display user interface components that retrieve large data sets. For example,
the count operation helps determine the thumb size for a scroll bar of a DataGrid.
Some remote services do not provide a count operation. Paging still works without a count operation, but the control
displaying the paged data might not properly represent the size of the data set.

Paging operations for filtered queries

You can enable paging for queries that filter results from the database. When filtering results in the query, use these
signatures for the paging and count functions.
getItems_pagedFiltered(filterParam1:String, filterParam2:String, startIndex:Number,
numItems:Number): myDataType

countFiltered(filterParam1:String, filterParam2:String)

filterParam1 Optional filter parameter. This parameter should be the same in

getItems_PagedFiltered() and countFiltered().

filterParam1 Optional filter parameter. This parameter should be the same in

getItems_PagedFiltered() and countFiltered().

Here is a code snippet of a getItems_pagedFiltered() function that is implemented in PHP. The code snippet shows
how to use the optional filter parameter.
get_Items_paged($expression, $startIndex, $numItems) {
. . .
SELECT * from employees where name LIKE $expression LIMIT $startIndex, $numItems;
. . .
}

Enable paging for an operation

This procedure assumes that you have coded both getItems_paged() and count() operations in your remote service. It
also assumes that you have configured the return data type for the operation, as explained in Configuring return types
for a data service operation.
1 In the Data/Services view, from the context menu for the getItems_paged() operation, select Enable Paging.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 20
Building data-centric applications with Flash Builder

2 If you have not previously identified a unique key for your data type, specify the attributes that uniquely identify an
instance of this data type. Click Next.
Typically, this attribute is the primary key.
3 Specify the count() operation. Click Finish.
Paging is now enabled for that operation.
In Data/Services View, the signature of the function that implements paging no longer includes the startIndex and
numItems parameters. These values are now dynamically added based on the user interface component that
displays the paged data.

Enabling data management

To enable data management, implement one or more of the following functions, which are used to synchronize
updates to data on the remote server:
• Add (createItem)
• Get All Properties (getItem)
• Update (updateItem)
• Delete (deleteItem)
These functions must have the following signatures:
createItem(item:myDatatype):int
deleteItem(itemID:Number):void
updateItem((item: myDatatype):void
getItem(itemID:Number): myDatatype

function name You can use any valid name for the function.

item An item of the data type returned by the data service.

itemID A unique identifier for the item, usually the primary key in the database.

myDataType The data type of the item available from the data service. Typically, you define a
custom data type when retrieving data from a service.

Enable data management for an operation

This procedure assumes that you have implemented the required operations in your remote service. It also assumes
that you have configured the return data type for the operations that use a custom data type. See Configuring return
types for a data service operation.
1 In the Data/Services view, expand the Data Types node.
2 From the context menu for a data type, select Enable Data Management.
3 If you have not previously identified a unique key for your data type, specify the attributes that uniquely identify an
instance of this data type. Click Next.
Typically, this attribute is the primary key.
4 Specify the Add, Get All Properties, Update, and Delete operations. Click Finish.
Data management is now enabled for that operation.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 21
Building data-centric applications with Flash Builder

Flash Builder code generation

Flash Builder generates client code that provides access to remote service operations. Flash builder generates code in
the following circumstances:
• Connecting to a data service
• Refreshing the data service in Data/Services View
• Configuring a return type for an operation
• Binding a service operation to a user interface control
• Enabling paging for a service operation
• Enabling data management for a service operation

Service classes
Use the Service Wizard to connect to a data service. When you connect to a service, Flash Builder generates an
ActionScript class file that provides access to the service operations. The generated class extends the
RemoteObjectServiceWrapper class.
Flash Builder bases the name of the generated class file on the name you provided for the service in the Service Wizard.
By default, Flash Builder places this class in a package under src. The name of the package is based on the service name.
For example, Flash Builder generates the following ActionScript classes for an EmployeeService class.
- project
|
- src
|
+ (default package)
|
- services.employeeservice
|
- _Super_EmployeeService.as
|
- EmployeeService.as

The super class contains the implementation for the EmployeeService class.
Never edit the super class, which is a generated class. Modifications you make to the super class can be overwritten.
Any changes you make to the implementation might result in undefined behavior.
In this example, use EmployeeService.as to extend the generated super class and add your implementation.

Classes for custom data types

Many remote data services provide server-side typing. These services return complex data as a custom data type.
For remote data services that do not return typed data, Flash Builder provides client-side typing. With client-side
typing, you use the Flash Builder Connect Wizard to define and configure the data type for complex data returned by
the service. For example, for a service that returns employee database records, you define and configure an Employee
data type.
Flash Builder generates an ActionScript class for the implementation of each custom data type returned by the service.
Flash Builder uses this class to create value objects, which it then uses to access data from the remote service.
For example, Flash Builder generates the following ActionScript classes for an Employee class:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 22
Building data-centric applications with Flash Builder

- project
|
- src
|
+ (default package)
|
- services.employeeservice
|
- _Super_Employee.as
|
- Employee.as

The super class contains the implementation for the Employee custom data type.
Never edit the super class, which is a generated class. Modifications you make to the super class can be overwritten.
Any changes you make to the implementation might result in undefined behavior.
In this example, use Employee.as to extend the generated super class and add your implementation.

Binding a service operation to a user interface control

“Binding service operations to controls” on page 14 shows how you can bind data returned from service operations to
a user interface control. When you bind a service operation to a control, Flash Builder generates the following code:
• Declarations tag containing a CallResponder and service tag
• Event handler for calling the service call
• Data binding between the control and the data returned from the operation

Declarations tag
A Declarations tag is an MXML element that declares non-default, non-visual properties of the current class. When
binding a service operation to a user interface, Flash Builder generates a Declarations tag containing a CallResponder
and a service tag. The CallResponder and generated service class are properties of the container element, which is
usually the Application tag.
The following example shows a Declarations tag providing access to a remote EmployeeService:
<fx:Declarations>
<s:CallResponder id="getAllItemsResult"/>
<employeesvc:EmployeeSvc id="employeeSvc" destination="ColdFusion"
endpoint="http://localhost:8500/flex2gateway/"
fault="Alert.show(event.fault.faultString)" showBusyCursor="true"
source="EmployeeService.EmployeeSvc"/>
</fx:Declarations>

Call Responder
A CallResponder manages results for calls made to a service. It contains a token property that is set to the Async token
returned by a service call. The CallResponder also contains a lastResult property, which is set to the last successful
result from the service call. You add event handlers to the CallResponder to provide access to the data returned
through the lastResult property.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 23
Building data-centric applications with Flash Builder

When Flash Builder generates a CallResponder, it generates an id property based on the name of the service operation
to which it is bound. The following code sample shows CallResponders for two operations of an EmployeeService. The
getAllItems operation is bound to the creationComplete event handler for a DataGrid. The delete operation is bound
to the selected item in the DataGrid. The DataGrid displays the items retrieved from the getAllItems service call
immediately after is created. The Delete Item Button control removes the selected record in the DataGrid from the
database.
<fx:Declarations>
<s:CallResponder id="getAllItemsResult"/>
<employeeservice:EmployeeService id="employeeService" destination="ColdFusion"
endpoint="http://localhost:8500/flex2gateway/"
fault="Alert.show(event.fault.faultString)"
showBusyCursor="true" source="CodeGenCF.CodeGenSvc"/>
<s:CallResponder id="deleteItemResult"/>
</fx:Declarations>
<mx:DataGrid id="dg" editable="true"
creationComplete="getAllItemsResult.token =
employeeService.getAllItems()"dataProvider="{getAllItemsResult.lastResult}">
<mx:columns>
<mx:DataGridColumn headerText="emp_no" dataField="emp_no"/>
<mx:DataGridColumn headerText="last_name" dataField="last_name"/>
<mx:DataGridColumn headerText="hire_date" dataField="hire_date"/>
</mx:columns>
</mx:DataGrid>
<s:Button label="Delete Item"
click="deleteItemResult.token = employeeService.deleteItem(dg.selectedItem.emp_no)"/>

Event handlers
When you bind a service operation to a user interface component, Flash Builder generates an inline event handler for
the CallResponder. The event handler manages the results of the operation. You can also create an event handler in an
ActionScript code block, and reference that event handler from a property of a user interface component.
Typically, you populate controls such as Lists and DataGrids with data returned from a service. Flash Builder, by
default, generates a creationComplete event handler for the control that fires immediately after the control is created.
For other controls, Flash Builder generates a handler for the control’s default event. For example, for a Button, Flash
Builder generates an event for the Button’s click event.
Flash Builder generates inline event handlers. The ActionScript code for the event handler is set directly in the event
property of the control. The following example shows the generated creation complete event handler for a DataGrid:
<mx:DataGrid id="dg" editable="true"
creationComplete="getAllItemsResult.token = employeeService.getAllItems()"
dataProvider="{getAllItemsResult.lastResult}">
<mx:columns>
<mx:DataGridColumn headerText="emp_no" dataField="emp_no"/>
<mx:DataGridColumn headerText="last_name" dataField="last_name"/>
<mx:DataGridColumn headerText="hire_date" dataField="hire_date"/>
</mx:columns>
</mx:DataGrid>

You can also create event handlers in ActionScript blocks and reference the event handler from the event property of
the control. The following example shows the same event handler for a DataGrid implemented in an ActionScript
block.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 24
Building data-centric applications with Flash Builder

<fx:Script>
<![CDATA[
import mx.events.FlexEvent;
import mx.controls.Alert;

protected function dg_creationCompleteHandler(event:FlexEvent):void

{
getAllItemsResult.token = employeeService.getAllItems();
}

]]>
</fx:Script>

. . .
<mx:DataGrid id="dg"
creationComplete="dg_creationCompleteHandler(event)"
dataProvider="{getAllItemsResult.lastResult}">
<mx:columns>
<mx:DataGridColumn headerText="emp_no" dataField="emp_no"/>
<mx:DataGridColumn headerText="last_name" dataField="last_name"/>
<mx:DataGridColumn headerText="hire_date" dataField="hire_date"/>
</mx:columns>
</mx:DataGrid>

You can also generate event handlers for controls that respond to user events, such as Buttons. The following example
shows a generated event handler for a Button that populates a DataGrid:
<s:Button label="Delete Item" click="deleteItemResult.token =
employeeService.deleteItem(dg.selectedItem.emp_no)"/>

You can also implement the event handler for the Button in an ActionScript block:
<fx:Script>
<![CDATA[
import mx.controls.Alert;

protected function delete_button_clickHandler(event:MouseEvent):void

{
deleteItemResult.token =
employeeService.deleteItem(dg.selectedItem.emp_no);
}

]]>
</fx:Script>

. . .

<s:Button label="Delete Item" id="delete_button"

click="delete_button_clickHandler(event)"/>

Data binding
Flash Builder generates code that binds the data returned from a service operation to the user interface control that
displays the data. The following example code that Flash Builder generates to populate a DataGrid control. The
getAllItems operation returns a set of employee records for the custom data type, Employee.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 25
Building data-centric applications with Flash Builder

The dataProvider property of the DataGrid is bound to the results stored in the CallResponder, getAllItemsResult.
Flash Builder automatically updates the DataGrid with DataGridColumns corresponding to each field returned for an
Employee record. The headerText and dataField properties of each column are set according to the data returned in
an Employee record.
<mx:DataGrid creationComplete="datagrid1_creationCompleteHandler(event)"
dataProvider="{getAllItemsResult.lastResult}" editable="true">
<mx:columns>
<mx:DataGridColumn headerText="gender" dataField="gender"/>
<mx:DataGridColumn headerText="emp_no" dataField="emp_no"/>
<mx:DataGridColumn headerText="birth_date" dataField="birth_date"/>
<mx:DataGridColumn headerText="last_name" dataField="last_name"/>
<mx:DataGridColumn headerText="hire_date" dataField="hire_date"/>
<mx:DataGridColumn headerText="first_name" dataField="first_name"/>
</mx:columns>
</mx:DataGrid>

Enabling paging for a service operation

When you enable paging, Flash Builder modifies the implementation of the generated service. When you populate a
data control (such as a DataGrid or a List) with paged data, Flash Builder determines the number of records visible in
the data control and the total number of records in the database. Flash Builder provides these values as arguments to
the service operation that you used to implement paging.
You do not have to modify any client application code after paging is enabled.
See “Enabling paging” on page 18 for more information.

Enabling data management for a service

In Flash Builder, data management is the synchronization of a set of updates to data on the server. You can enable data
management for custom data types returned from the service. With data management enabled, you can modify one or
more items in a client application without making any updates to the server. You can then commit all the changes to
the server with one operation. You can also revert the modifications without updating any data on the server.
“Enabling data management” on page 20 shows how to implement this feature.
When you enable data management, Flash Builder modifies the implementation of the generated service class and the
generated class for custom data types. Flash Builder creates a DataManager to implement this functionality.
When you call service operations for a managed data type, the changes are reflected in the client application. However,
data on the server is not updated until you call the DataManager’s commit method. The DataManager also provides a
revertChanges method. The revertChanges method restores the data displayed in the client application to the values
retrieved from the server before the last commit call.
To access the commit and revertChanges methods for a managed type, first get the DataManager for the type, and then
call the methods. For example, if you have an instance of employeeService and enabled data management for the
Employee data type, then you would do the following:
employeeService.getDataManager (employeeService.DATA_MANAGER_EMPLOYEE).revertChanges();
employeeService.getDataManager (employeeService.DATA_MANAGER_EMPLOYEE).commit();

You can also call the commit method directly from the employeeService instance. Calling the commit method directly
from the service instance commits all changes for all managed data types.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 26
Building data-centric applications with Flash Builder

employeeService.commit();

Note: You cannot call revertChanges directly from the service instance.

Deploying applications
XXXXXXXXXXXXXXXXXXXXXXXXX

Prerelease Adobe Confidential - 01/06/2009

 27

Chapter 4: Accessing Server-Side Data

with Flex
Adobe® Flex® data access components use remote procedure calls to interact with server environments, such as PHP,
Adobe ColdFusion, and Microsoft ASP.NET. The remote procedure calls provide data to applications built with Flex
and send data to back-end data sources. For an introduction to data access components, see Data access.

Using HTTPService components

You use an HTTPService component with any server-side technology that sends and receives data over HTTP,
including PHP pages, ColdFusion pages, JavaServer Pages (JSPs), Java servlets, Ruby on Rails, and Microsoft ASP
pages.
You can call a service directly by specifying its URL in the HTTPService component’s url property. If you have the
Adobe LiveCycle Data Services ES or BlazeDS server, you proxy your requests through the server’s proxy service by
specifying a server destination in the HTTPService component’s destination property.
If you are not using LiveCycle Data Services ES or BlazeDS, you can access services in the same domain as your Flex
application or use a crossdomain.xml (cross-domain policy) file that allows access from your application's domain and
that must be installed on the web server hosting the RPC service.
For API reference information about the HTTPService component, see mx.rpc.http.mxml.HTTPService.

Working with PHP and SQL data

You can use a Flex HTTPService component in conjunction with PHP and a SQL database management system to
display the results of a database query in a Flex application and to insert data into a database. You can call a PHP page
with GET or POST to perform a database query. You can then format the query result data in an XML structure and
return the XML structure to the Flex application in the HTTP response. When the result has been returned to the Flex
application, you can display it in one or more user interface controls.

MXML code
The Flex application in the following example calls a PHP page with the POST method. The PHP page queries a
MySQL database table called users. It formats the query results as XML and returns the XML to the Flex application,
where it is bound to the dataProvider property of a DataGrid control and displayed in the DataGrid control. The
Flex application also sends the user name and e-mail address of new users to the PHP page, which performs an insert
into the user database table.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 28
Accessing Server-Side Data with Flex

<?xml version="1.0" encoding="utf-8"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
xmlns="*" creationComplete="send_data()">
<mx:Script>
<![CDATA[
private function send_data():void {
userRequest.send();
}
]]>
</mx:Script>
<mx:Form x="22" y="10" width="493">
<mx:HBox>
<mx:Label text="Username"/>
<mx:TextInput id="username"/>
</mx:HBox>
<mx:HBox>
<mx:Label text="Email Address"/>
<mx:TextInput id="emailaddress"/>
</mx:HBox>
<mx:Button label="Submit" click="send_data()"/>
</mx:Form>
<mx:DataGrid id="dgUserRequest" x="22" y="128"
dataProvider="{userRequest.lastResult.users.user}">
<mx:columns>
<mx:DataGridColumn headerText="User ID" dataField="userid"/>
<mx:DataGridColumn headerText="User Name" dataField="username"/>
</mx:columns>
</mx:DataGrid>
<mx:TextInput x="22" y="292" id="selectedemailaddress"
text="{dgUserRequest.selectedItem.emailaddress}"/>
<mx:HTTPService id="userRequest" url="http://localhost/myproj/request_post2.php"
useProxy="false" method="POST">
<mx:request xmlns="">
<username>{username.text}</username>
<emailaddress>{emailaddress.text}</emailaddress>
</mx:request>
</mx:HTTPService>
</mx:Application>

The HTTPService’s send() method makes the call to the PHP page. This call is made in the send_data() method in
the Script block of the MXML file.
The resultFormat property of the HTTPService component is set to object, so the data is sent back to the Flex
application as a graph of ActionScript objects. This is the default value for the resultFormat property. Alternatively,
you can use a resultFormat of e4x to return data as an XMLList object on which you can perform ECMAScript for
XML (E4X) operations. Switching the resultFormat property to e4x requires the following minor changes to the
MXML code.
Note: If the result format is e4x, you do not include the root node of the XML structure in the dot notation when binding
to the DataGrid.
The XML returned in this example contains no namespace information. For information about working with XML
that does contain namespaces, see “Handling results as XML with the E4X result format” on page 84.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 29
Accessing Server-Side Data with Flex

...
<mx:DataGrid id="dgUserRequest" x="22" y="128" dataProvider="{userRequest.lastResult.user}">
...
<mx:HTTPService id="userRequest" url="http://server/myproj/request_post2.php"
useProxy="false" method="POST" resultFormat="e4x">
...

When using the e4x result format, you can optionally bind the lastResult property to an XMLListCollection object
and then bind that object to the DataGrid.dataProvider property, as the following code snippet shows:
...
<mx:XMLListCollection id="xc"
source="{userRequest.lastResult.user}"/>

<mx:DataGrid id="dgUserRequest" x="22" y="128" dataProvider="{xc}">

...

MySQL database script

The PHP code for this application uses a database table called users in a MySQL database called sample. The following
MySQL script creates the table:
CREATE TABLE `users` (
`userid` int(10) unsigned NOT NULL auto_increment,
`username` varchar(255) collate latin1_general_ci NOT NULL,
`emailaddress` varchar(255) collate latin1_general_ci NOT NULL,
PRIMARY KEY (`userid`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1 COLLATE=latin1_general_ci AUTO_INCREMENT=3 ;

PHP code
This application calls the following PHP page. This PHP code performs SQL database inserts and queries, and returns
query results to the Flex application in an XML structure.
<?php
define( "DATABASE_SERVER", "servername" );
define( "DATABASE_USERNAME", "username" );
define( "DATABASE_PASSWORD", "password" );
define( "DATABASE_NAME", "sample" );

//connect to the database.

$mysql = mysql_connect(DATABASE_SERVER, DATABASE_USERNAME, DATABASE_PASSWORD);

mysql_select_db( DATABASE_NAME );

// Quote variable to make safe

function quote_smart($value)
{
// Stripslashes
if (get_magic_quotes_gpc()) {
$value = stripslashes($value);
}
// Quote if not integer
if (!is_numeric($value)) {
$value = "'" . mysql_real_escape_string($value) . "'";
}
return $value;
}

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 30
Accessing Server-Side Data with Flex

if( $_POST["emailaddress"] AND $_POST["username"])

{
//add the user
$Query = sprintf("INSERT INTO users VALUES ('', %s, %s)", quote_smart($_POST['username']),
quote_smart($_POST['emailaddress']));

$Result = mysql_query( $Query );

}

//return a list of all the users

$Query = "SELECT * from users";
$Result = mysql_query( $Query );

$Return = "<users>";

while ( $User = mysql_fetch_object( $Result ) )

{
$Return .= "<user><userid>".$User->userid."</userid><username>".$User-
>username."</username><emailaddress>".$User->emailaddress."</emailaddress></user>";
}
$Return .= "</users>";
mysql_free_result( $Result );
print ($Return)
?>

Working with ColdFusion and SQL data

You can use a Flex HTTPService component in conjunction with a ColdFusion page and a SQL database management
system to display the results of a database query in a Flex application and to insert data into a database. You can call a
ColdFusion page with GET or POST to perform a database query. You can then format the query result data in an XML
structure and return the XML structure to the Flex application in the HTTP response. When the result has been
returned to the Flex application, you can display it in one or more user interface controls.

MXML code
The Flex application in the following example calls a ColdFusion page with the POST method. The ColdFusion page
queries a MySQL database table called users. It formats the query results as XML and returns the XML to the Flex
application, where it is bound to the dataProvider property of a DataGrid control and displayed in the DataGrid
control. The Flex application also sends the user name and e-mail address of new users to the ColdFusion page, which
performs an insert into the user database table.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 31
Accessing Server-Side Data with Flex

<?xml version="1.0" encoding="utf-8"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*" layout="absolute"
creationComplete="userRequest.send()">
<mx:Form x="22" y="10" width="493">
<mx:HBox>
<mx:Label text="Username"/>
<mx:TextInput id="username"/>
</mx:HBox>
<mx:HBox>
<mx:Label text="Email Address"/>
<mx:TextInput id="emailaddress"/>
</mx:HBox>
<mx:Button label="Submit" click="userRequest.send()"/>
</mx:Form>
<mx:DataGrid id="dgUserRequest" x="22" y="128"
dataProvider="{userRequest.lastResult.users.user}">
<mx:columns>
<mx:DataGridColumn headerText="User ID" dataField="userid"/>
<mx:DataGridColumn headerText="User Name" dataField="username"/>
</mx:columns>
</mx:DataGrid>
<mx:TextInput x="22" y="292" id="selectedemailaddress"
text="{dgUserRequest.selectedItem.emailaddress}"/>
<mx:HTTPService id="userRequest" url="http://server:8500/flexapp/returncfxml.cfm"
useProxy="false" method="POST">
<mx:request xmlns="">
<username>{username.text}</username>
<emailaddress>{emailaddress.text}</emailaddress>
</mx:request>
</mx:HTTPService>
</mx:Application>

The HTTPService’s send() method makes the call to the ColdFusion page. This call is made in the send_data()
method in the Script block of the MXML file.
The resultFormat property of the HTTPService component is set to object, so the data is sent back to the Flex
application as a graph of ActionScript objects. This is the default value for the resultFormat property. Alternatively,
you can use a result format of e4x to return data as an XMLList object on which you can perform ECMAScript for
XML (E4X) operations. Switching the resultFormat property to e4x requires the following minor changes to the
MXML code.
Note: If the result format is e4x, you do not include the root node of the XML structure in the dot notation when binding
to the DataGrid.
The XML returned in this example contains no namespace information. For information about working with XML
that does contain namespaces, see “Handling results as XML with the E4X result format” on page 84.
...
<mx:DataGrid id="dgUserRequest" x="22" y="128" dataProvider="{userRequest.lastResult.user}">
...
<mx:HTTPService id="userRequest" url="http://server:8500/flexapp/returncfxml.cfm"
useProxy="false" method="POST" resultFormat="e4x">
...

When using the e4x result format, you can optionally bind the lastResult property to an XMLListCollection object
and then bind that object to the DataGrid dataProvider property, as the following code snippet shows:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 32
Accessing Server-Side Data with Flex

...
<mx:XMLListCollection id="xc"
source="{userRequest.lastResult.user}"/>
<mx:DataGrid id="dgUserRequest" x="22" y="128" dataProvider="{xc}">
...

SQL script
The ColdFusion code for this application uses a database table called users in a MySQL database called sample. The
following MySQL script creates the table:
CREATE TABLE `users` (
`userid` int(10) unsigned NOT NULL auto_increment,
`username` varchar(255) collate latin1_general_ci NOT NULL,
`emailaddress` varchar(255) collate latin1_general_ci NOT NULL,
PRIMARY KEY (`userid`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1 COLLATE=latin1_general_ci AUTO_INCREMENT=3 ;

ColdFusion code
This application calls the following ColdFusion page. This ColdFusion code performs SQL database inserts and
queries, and returns query results to the Flex application. The ColdFusion page uses the cfquery tag to insert data into
the database and query the database, and it uses the cfxml tag to format the query results in an XML structure.
<cfprocessingdirective pageencoding = "utf-8" suppressWhiteSpace = "Yes">
<cfif isDefined("username") and isDefined("emailaddress") and username NEQ "">
<cfquery name="addempinfo" datasource="sample">
INSERT INTO users (username, emailaddress) VALUES (
<cfqueryparam value="#username#" cfsqltype="CF_SQL_VARCHAR" maxlength="255">,
<cfqueryparam value="#emailaddress#" cfsqltype="CF_SQL_VARCHAR" maxlength="255"> )
</cfquery>
</cfif>
<cfquery name="alluserinfo" datasource="sample">
SELECT userid, username, emailaddress FROM users
</cfquery>
<cfxml variable="userXML">
<users>
<cfloop query="alluserinfo">
<cfoutput>
<user>
<userid>#toString(userid)#</userid>
<username>#username#</username>
<emailaddress>#emailaddress#</emailaddress>
</user>
</cfoutput>
</cfloop>
</users>
</cfxml>
<cfoutput>#userXML#</cfoutput>
</cfprocessingdirective>

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 33
Accessing Server-Side Data with Flex

Working with JavaServer Pages

You can use a Flex HTTPService component in conjunction with a JSP page and a SQL database management system
to display the results of a database query in a Flex application and insert data into a database. You can call a JSP page
with GET or POST to perform a database query. You can then format the query result data in an XML structure and
return the XML structure to the Flex application in the HTTP response. When the result has been returned to the Flex
application, you can display it in one or more user interface controls.

MXML code
The Flex application in the following example calls a JSP page that retrieves data from a SQL database. It formats
database query results as XML and returns the XML to the Flex application, where it is bound to the dataProvider
property of a DataGrid control and displayed in the DataGrid control.
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:HTTPService id="srv" url="catalog.jsp"/>

<mx:DataGrid dataProvider="{srv.lastResult.catalog.product}" width="100%" height="100%"/>

<mx:Button label="Get Data" click="srv.send()"/>

</mx:Application>

The HTTPService’s send() method makes the call to the JSP page. This call is made in the click event of the Button
in the MXML file.
The resultFormat property of the HTTPService component is set to object, so the data is sent back to the Flex
application as a graph of ActionScript objects. This is the default value for the resultFormat property. Alternatively,
you can use a result format of e4x to return data as an XMLList object on which you can perform ECMAScript for
XML (E4X) operations. Switching the resultFormat property to e4x requires the following minor changes to the
MXML code.
Note: If the result format is e4x, you do not include the root node of the XML structure in the dot notation when binding
to the DataGrid.
The XML returned in this example contains no namespace information. For information about working with XML
that does contain namespaces, see “Handling results as XML with the E4X result format” on page 84.
...
<mx:HTTPService id="srv" url="catalog.jsp" resultFormat="e4x"/>
...
<mx:DataGrid dataProvider="{srv.lastResult.product}" width="100%" height="100%"/>

When using the e4x result format, you can optionally bind the lastResult property to an XMLListCollection object
and then bind that object to the DataGrid.dataProvider property:
...
<mx:XMLListCollection id="xc"
source="{userRequest.lastResult.product}"/>

<mx:DataGrid id="dgUserRequest" x="22" y="128" dataProvider="{xc}">

...

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 34
Accessing Server-Side Data with Flex

JSP code
The following example shows the JSP page used in this application. This JSP page does not call a database directly. It
gets its data from a Java class called ProductService, which in turn uses a Java class called Product to represent
individual products.
<%@page import="flex.samples.product.ProductService,
flex.samples.product.Product,
java.util.List"%>
<?xml version="1.0" encoding="utf-8"?>
<catalog>
<%
ProductService srv = new ProductService();
List list = null;
list = srv.getProducts();
Product product;
for (int i=0; i<list.size(); i++)
{
product = (Product) list.get(i);
%>
<product productId="<%= product.getProductId()%>">
<name><%= product.getName() %></name>
<description><%= product.getDescription() %></description>
<price><%= product.getPrice() %></price>
<image><%= product.getImage() %></image>
<category><%= product.getCategory() %></category>
<qtyInStock><%= product.getQtyInStock() %></qtyInStock>
</product>
<%
}
%>
</catalog>

Calling HTTP services in ActionScript

The following example shows an HTTP service call in an ActionScript script block. Calling the useHTTPService()
method declares the service, sets the service URL, sets up result and fault event listeners, and calls the service’s send()
method.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 35
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\HttpServiceInAS.mxml. Compiles -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" verticalGap="10">
<mx:Script>
<![CDATA[
import mx.controls.Alert;
import mx.rpc.http.HTTPService;
import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;

private var service:HTTPService

public function useHttpService(parameters:Object):void {
service = new HTTPService();
service.url = "catalog.jsp";
service.method = "POST";
service.addEventListener("result", httpResult);
service.addEventListener("fault", httpFault);
service.send(parameters);
}

public function httpResult(event:ResultEvent):void {

var result:Object = event.result;
//Do something with the result.
}

public function httpFault(event:FaultEvent):void {

var faultstring:String = event.fault.faultString;
Alert.show(faultstring);
}
]]>
</mx:Script>
</mx:Application>

Using WebService components

Flex applications can interact with web services that define their interfaces in a Web Services Description Language 1.1
(WSDL 1.1) document, which is available as a URL. WSDL is a standard format for describing the messages that a web
service understands, the format of its responses to those messages, the protocols that the web service supports, and
where to send messages. The Flex web service API generally supports Simple Object Access Protocol (SOAP) 1.1, XML
Schema 1.0 (versions 1999, 2000, and 2001), and WSDL 1.1 RPC-encoded, RPC-literal, and document-literal (bare and
wrapped style parameters). The two most common types of web services use remote procedure call (RPC) encoded or
document-literal SOAP bindings; the terms encoded and literal indicate the type of WSDL-to-SOAP mapping that a
service uses.
Flex applications support web service requests and results that are formatted as SOAP messages. SOAP provides the
definition of the XML-based format that you can use for exchanging structured and typed information between a web
service client, such as a Flex application, and a web service.
You can call a service directly by specifying its WSDL URL in the the WebService component’s wsdl property. If you
have the LiveCycle Data Services ES or BlazeDS server, you can proxy your requests through the server’s proxy service
by specifying a server destination in the WebService component’s destination property.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 36
Accessing Server-Side Data with Flex

If you are not using LiveCycle Data Services ES or BlazeDS, you can access web services in the same domain as your
Flex application or use a crossdomain.xml (cross-domain policy) file that allows access from your application's domain
must be installed on the web server hosting the RPC service.
For API reference information about the WebService component, see mx.rpc.soap.mxml.WebService. For
information about data type mapping between Flex and web services, see
http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=kb401841.

Sample WebService application

The following sample code is for an application that uses a WebService component to call web service operations.

MXML code
The Flex application in the following example calls a web service that queries a SQL database table called users and
returns data to the Flex application, where it is bound to the dataProvider property of a DataGrid control and
displayed in the DataGrid control. The Flex application also sends the user name and e-mail address of new users to
the web service, which performs an insert into the user database table. The back-end implementation of the web service
is a ColdFusion component; the same ColdFusion component is accessed as a remote object in “Using RemoteObject
components” on page 53.
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*" layout="absolute"
creationComplete="userRequest.returnRecords()">
<mx:Form x="22" y="10" width="493">
<mx:HBox>
<mx:Label text="Username"/>
<mx:TextInput id="username"/>
</mx:HBox>
<mx:HBox>
<mx:Label text="Email Address"/>
<mx:TextInput id="emailaddress"/>
</mx:HBox>
<mx:Button label="Submit" click="clickHandler()"/>
</mx:Form>
<mx:DataGrid id="dgUserRequest" x="22" y="128">
<mx:columns>
<mx:DataGridColumn headerText="User ID" dataField="USERID"/>
<mx:DataGridColumn headerText="User Name" dataField="USERNAME"/>
</mx:columns>
</mx:DataGrid>

<mx:TextInput x="22" y="292" id="selectedemailaddress"

text="{dgUserRequest.selectedItem.emailaddress}"/>
<mx:WebService
id="userRequest"
wsdl="http://localhost:8500/flexapp/returnusers.cfc?wsdl">

<mx:operation name="returnRecords" resultFormat="object"

fault="mx.controls.Alert.show(event.fault.faultString)"
result="remotingCFCHandler(event)"/>
<mx:operation name="insertRecord" result="insertCFCHandler()"
fault="mx.controls.Alert.show(event.fault.faultString)"/>
</mx:WebService>

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 37
Accessing Server-Side Data with Flex

<mx:Script>
<![CDATA[
import mx.rpc.events.ResultEvent;

private function remotingCFCHandler(e:ResultEvent):void

{
dgUserRequest.dataProvider = e.result;
}

private function insertCFCHandler():void

{
userRequest.returnRecords();
}
private function clickHandler():void
{
userRequest.insertRecord(username.text, emailaddress.text);
}
]]>
</mx:Script>
</mx:Application>

WSDL document
The following example shows the WSDL document that defines the API of the web service:
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://flexapp"
xmlns:apachesoap="http://xml.apache.org/xml-soap"
xmlns:impl="http://flexapp" xmlns:intf="http://flexapp"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns1="http://rpc.xml.coldfusion"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!--WSDL created by ColdFusion version 8,0,0,171651-->
<wsdl:types>
<schema targetNamespace="http://rpc.xml.coldfusion"
xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://flexapp"/>
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<complexType name="CFCInvocationException">
<sequence/>
</complexType>

<complexType name="QueryBean">
<sequence>
<element name="columnList" nillable="true" type="impl:ArrayOf_xsd_string"/>
<element name="data" nillable="true" type="impl:ArrayOfArrayOf_xsd_anyType"/>
</sequence>
</complexType>
</schema>
<schema targetNamespace="http://flexapp" xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://rpc.xml.coldfusion"/>

<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<complexType name="ArrayOf_xsd_string">
<complexContent>

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 38
Accessing Server-Side Data with Flex

<restriction base="soapenc:Array">
<attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:string[]"/>
</restriction>
</complexContent>
</complexType>
<complexType name="ArrayOfArrayOf_xsd_anyType">

<complexContent>
<restriction base="soapenc:Array">
<attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:anyType[][]"/>
</restriction>
</complexContent>
</complexType>
</schema>
</wsdl:types>

<wsdl:message name="CFCInvocationException">

<wsdl:part name="fault" type="tns1:CFCInvocationException"/>

</wsdl:message>
<wsdl:message name="returnRecordsRequest">
</wsdl:message>
<wsdl:message name="insertRecordResponse">
</wsdl:message>
<wsdl:message name="returnRecordsResponse">
<wsdl:part name="returnRecordsReturn" type="tns1:QueryBean"/>
</wsdl:message>
<wsdl:message name="insertRecordRequest">
<wsdl:part name="username" type="xsd:string"/>
<wsdl:part name="emailaddress" type="xsd:string"/>
</wsdl:message>
<wsdl:portType name="returncfxml">
<wsdl:operation name="insertRecord" parameterOrder="username emailaddress">
<wsdl:input message="impl:insertRecordRequest" name="insertRecordRequest"/>
<wsdl:output message="impl:insertRecordResponse" name="insertRecordResponse"/>
<wsdl:fault message="impl:CFCInvocationException" name="CFCInvocationException"/>
</wsdl:operation>
<wsdl:operation name="returnRecords">
<wsdl:input message="impl:returnRecordsRequest" name="returnRecordsRequest"/>
<wsdl:output message="impl:returnRecordsResponse" name="returnRecordsResponse"/>
<wsdl:fault message="impl:CFCInvocationException" name="CFCInvocationException"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="returncfxml.cfcSoapBinding" type="impl:returncfxml">
<wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="insertRecord">
<wsdlsoap:operation soapAction=""/>
<wsdl:input name="insertRecordRequest">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://flexapp" use="encoded"/>
</wsdl:input>
<wsdl:output name="insertRecordResponse">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://flexapp" use="encoded"/>
</wsdl:output>
<wsdl:fault name="CFCInvocationException">
<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 39
Accessing Server-Side Data with Flex

name="CFCInvocationException" namespace="http://flexapp" use="encoded"/>

</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="returnRecords">
<wsdlsoap:operation soapAction=""/>
<wsdl:input name="returnRecordsRequest">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://flexapp" use="encoded"/>
</wsdl:input>
<wsdl:output name="returnRecordsResponse">
<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://flexapp" use="encoded"/>
</wsdl:output>
<wsdl:fault name="CFCInvocationException">
<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
name="CFCInvocationException" namespace="http://flexapp" use="encoded"/>
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="returncfxmlService">
<wsdl:port binding="impl:returncfxml.cfcSoapBinding" name="returncfxml.cfc">
<wsdlsoap:address location="http://localhost:8500/flexapp/returnusers.cfc"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>

Calling web services in ActionScript

The following example shows a web service call in an ActionScript script block. Calling the useWebService() method
declares the service, sets the WSDL URL, fetches the WSDL document, and calls the echoArgs() method of the
service.
Note: When you declare a WebService component in ActionScript, you must call the WebService.loadWSDL() method.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 40
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\WebServiceInAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
import mx.rpc.soap.WebService;
import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;
private var ws:WebService;
public function useWebService(intArg:int, strArg:String):void {
ws = new WebService();
ws.wsdl="http://myserver:8500/flexapp/app1.cfc?wsdl";
ws.echoArgs.addEventListener("result", echoResultHandler);
ws.addEventListener("fault", faultHandler);
ws.loadWSDL();
ws.echoArgs(intArg, strArg);
}

public function echoResultHandler(event:ResultEvent):void {

var retStr:String = event.result.echoStr;
var retInt:int = event.result.echoInt;
//Do something.
}

public function faultHandler(event:FaultEvent):void {

//deal with event.fault.faultString, etc
}
]]>
</mx:Script>
</mx:Application>

Reserved Operation names

WebService operations are usually accessible by simply naming them after a service variable. However, naming
conflicts can occur if an operation name happens to match a defined method on the service. You can use the following
method in ActionScript on a WebService component to return the operation of the given name:
public function getOperation(name:String):Operation

Reading WSDL documents

You can view a WSDL document in a web browser, a simple text editor, an XML editor, or a development environment
such as Adobe Dreamweaver, which contains a built-in utility for displaying WSDL documents in an easy-to-read
format.
A WSDL document contains the tags described in the following table.

Tag Description

<binding> Specifies the protocol that clients, such as Flex applications, use to communicate with a web service. Bindings exist for
SOAP, HTTP GET, HTTP POST, and MIME. Flex supports the SOAP binding only.

<fault> Specifies an error value that is returned as a result of a problem processing a message.

<input> Specifies a message that a client, such as a Flex application, sends to a web service.

<message> Defines the data that a WebService operation transfers.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 41
Accessing Server-Side Data with Flex

Tag Description

<operation> Defines a combination of <input>, <output>, and <fault> tags.

<output> Specifies a message that the web service sends to a web service client, such as a Flex application.

<port> Specifies a web service endpoint, which specifies an association between a binding and a network address.

<portType> Defines one or more operations that a web service provides.

<service> Defines a collection of <port> tags. Each service maps to one <portType> tag and specifies different ways to access
the operations in that <portType> tag.

<types> Defines data types that a web service's messages use.

RPC-oriented operations and document-oriented operations

A WSDL file can specify either RPC-oriented or document-oriented (document-literal) operations. Flex supports both
operation styles.
When calling an RPC-oriented operation, a Flex application sends a SOAP message that specifies an operation and its
parameters. When calling a document-oriented operation, a Flex application sends a SOAP message that contains an
XML document.
In a WSDL document, each <port> tag has a binding property that specifies the name of a particular
<soap:binding> tag, as the following example shows:

<binding name="InstantMessageAlertSoap" type="s0:InstantMessageAlertSoap">

<soap:binding transport="http://schemas.xmlsoap.org/soap/http"
style="document"/>

The style property of the associated <soap:binding> tag determines the operation style. In this example, the style
is document.
Any operation in a service can specify the same style or override the style that is specified for the port associated with
the service, as the following example shows:
<operation name="SendMSN">
<soap:operation soapAction="http://www.bindingpoint.com/ws/imalert/
SendMSN"style="document"/>

Working with SOAP headers

A SOAP header is an optional tag in a SOAP envelope that usually contains application-specific information, such as
authentication information.

Adding SOAP headers to web service requests

Some web services require that you pass along a SOAP header when you call an operation.
You can add a SOAP header to all web service operations or individual operations by calling a WebService or
Operation object's addHeader() method or addSimpleHeader() method in an event listener function.
When you use the addHeader() method, you first must create SOAPHeader and QName objects separately. The
addHeader() method has the following signature:

addHeader(header:mx.rpc.soap.SOAPHeader):void

To create a SOAPHeader object, use the following constructor:

SOAPHeader(qname:QName, content:Object)

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 42
Accessing Server-Side Data with Flex

To create the QName object in the first parameter of the SOAPHeader() method, use the following constructor:
QName(uri:String, localName:String)

The content parameter of the SOAPHeader() constructor is a set of name-value pairs based on the following format:
{name1:value1, name2:value2}

The addSimpleHeader() method is a shortcut for a single name-value SOAP header. When you use the
addSimpleHeader() method, you create SOAPHeader and QName objects in parameters of the method. The
addSimpleHeader() method has the following signature:

addSimpleHeader(qnameLocal:String, qnameNamespace:String, headerName:String,

headerValue:Object):void

The addSimpleHeader() method takes the following parameters:

• qnameLocal is the local name for the header QName.

• qnameNamespace is the namespace for the header QName.

• headerName is the name of the header.

• headerValue is the value of the header. This can be a string if it is a simple value, an object that will undergo basic
XML encoding, or XML if you want to specify the header XML yourself.
The code in the following example shows how to use the addHeader() method and the addSimpleHeader()
method to add a SOAP header. The methods are called in an event listener function called headers, and the event
listener is assigned in the load property of an <mx:WebService> tag:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 43
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\WebServiceAddHeader.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" height="600">
<mx:WebService id="ws" wsdl="http://myserver:8500/flexapp/app1.cfc?wsdl"
load="headers();"/>
<mx:Script>
<![CDATA[
import mx.rpc.soap.SOAPHeader;
private var header1:SOAPHeader;
private var header2:SOAPHeader;
public function headers():void {

// Create QName and SOAPHeader objects.

var q1:QName=new QName("http://soapinterop.org/xsd", "Header1");
header1=new SOAPHeader(q1, {string:"bologna",int:"123"});
header2=new SOAPHeader(q1, {string:"salami",int:"321"});

// Add the header1 SOAP Header to all web service requests.

ws.addHeader(header1);

// Add the header2 SOAP Header to the getSomething operation.

ws.getSomething.addHeader(header2);

// Within the addSimpleHeader method,

// which adds a SOAP header to web
//service requests, create SOAPHeader and QName objects.
ws.addSimpleHeader
("header3", "http://soapinterop.org/xsd", "foo","bar");
}
]]>
</mx:Script>
</mx:Application>

Clearing SOAP headers

You use the WebService or operation object's clearHeaders() method to remove SOAP headers that you added to
the object, as the following example shows for a WebService object. You must call clearHeaders() at the level
(WebService or operation) where the header was added.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 44
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\WebServiceClearHeader.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" height="600" >

<!-- The value of the destination property is for demonstration only and is not a real
destination. -->
<mx:WebService id="ws" wsdl="http://myserver:8500/flexapp/app1.cfc?wsdl"
load="headers();"/>

<mx:Script>
<![CDATA[
import mx.rpc.*;
import mx.rpc.soap.SOAPHeader;

private function headers():void {

// Create QName and SOAPHeader objects.
var q1:QName=new QName("Header1", "http://soapinterop.org/xsd");
var header1:SOAPHeader=new SOAPHeader(q1, {string:"bologna",int:"123"});
var header2:SOAPHeader=new SOAPHeader(q1, {string:"salami",int:"321"});
// Add the header1 SOAP Header to all web service request.
ws.addHeader(header1);
// Add the header2 SOAP Header to the getSomething operation.
ws.getSomething.addHeader(header2);

// Within the addSimpleHeader method, which adds a SOAP header to all

// web service requests, create SOAPHeader and QName objects.
ws.addSimpleHeader("header3","http://soapinterop.org/xsd", "foo", "bar");
}

// Clear SOAP headers added at the WebService and Operation levels.

private function clear():void {
ws.clearHeaders();
ws.getSomething.clearHeaders();
}
]]>
</mx:Script>

<mx:HBox>
<mx:Button label="Clear headers and run again" click="clear();"/>
</mx:HBox>

</mx:Application>

Redirecting a web service to a different URL

Some web services require that you change to a different endpoint URL after you process the WSDL and make an
initial call to the web service. For example, suppose that you want to use a web service that requires you to pass security
credentials. When you call the web service to send login credentials, it accepts the credentials and returns the actual
endpoint URL that is required to use the service's business operations. Before calling the business operations, you must
change the endpointURI property of your WebService component.
The following example shows a result event listener that stores the endpoint URL that a web service returns in a
variable, and then passes that variable into a function to change the endpoint URL for subsequent requests:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 45
Accessing Server-Side Data with Flex

...
public function onLoginResult(event:ResultEvent):void {

//Extract the new service endpoint from the login result.

var newServiceURL = event.result.serverUrl;

// Redirect all service operations to the URL received in the login result.
serviceName.endpointURI=newServiceURL;

}
...

A web service that requires you to pass security credentials might also return an identifier that you must attach in a
SOAP header for subsequent requests. For more information, see “Working with SOAP headers” on page 41.

Serialization between ActionScript and web services

Default encoding of ActionScript data

The following table shows the default encoding mappings from ActionScript 3 types to XML schema complex types.

XML schema definition Supported ActionScript 3 Notes

types

Top-level elements

xsd:element Object If input value is null, encoded output is set with

the xsi:nil attribute.
nillable == true

xsd:element Object Input value is ignored and fixed value is used

instead.
fixed != null

xsd:element Object If input value is null, this default value is used

instead.
default != null

Local elements

xsd:element Object Input value is ignored and omitted from encoded

output.
maxOccurs == 0

xsd:element Object Input value is processed as a single entity. If the

associated type is a SOAP-encoded array, then
maxOccurs == 1 arrays and mx.collection.IList
implementations pass through intact and are
handled as a special case by the SOAP encoder for
that type.

xsd:element Object Input value should be iterable (such as an array or

mx.collections.IList implementation),
maxOccurs > 1 although noniterable values are wrapped before
processing. Individual items are encoded as
separate entities according to the definition.

xsd:element Object If input value is undefined or null, encoded

output is omitted.
minOccurs == 0

The following table shows the default encoding mappings from ActionScript 3 types to XML schema built-in types.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 46
Accessing Server-Side Data with Flex

XML schema type Supported ActionScript 3 Notes

types

xsd:anyType Object Boolean -> xsd:boolean

xsd:anySimpleType ByteArray -> xsd:base64Binary

Date -> xsd:dateTime

int -> xsd:int

Number -> xsd:double

String -> xsd:string

uint -> xsd:unsignedInt

xsd:base64Binary flash.utils.ByteArray mx.utils.Base64Encoder is used (without

line wrapping).

xsd:boolean Boolean Always encoded as true or false.

Number Number == 1 then true, otherwise false.

Object Object.toString() == "true" or "1" then

true, otherwise false.

xsd:byte Number String first converted to Number.

xsd:unsignedByte String

xsd:date Date Date UTC accessor methods are used.

Number Number used to set Date.time.

String String assumed to be preformatted and encoded

as is.

xsd:dateTime Date Date UTC accessor methods are used.

Number Number used to set Date.time.

String String assumed to be preformatted and encoded

as is.

xsd:decimal Number Number.toString() is used. Note that Infinity,

-Infinity, and NaN are invalid for this type.
String
String first converted to Number.

xsd:double Number Limited to range of Number.

String String first converted to Number.

xsd:duration Object Object.toString() is called.

xsd:float Number Limited to range of Number.

String String first converted to Number.

xsd:gDay Date Date.getUTCDate() is used.

Number Number used directly for day.

String String parsed as Number for day.

xsd:gMonth Date Date.getUTCMonth() is used.

Number Number used directly for month.

String String parsed as Number for month.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 47
Accessing Server-Side Data with Flex

XML schema type Supported ActionScript 3 Notes

types

xsd:gMonthDay Date Date.getUTCMonth() and

Date.getUTCDate() are used.
String
String parsed for month and day portions.

xsd:gYear Date Date.getUTCFullYear() is used.

Number Number used directly for year.

String String parsed as Number for year.

xsd:gYearMonth Date Date.getUTCFullYear() and

Date.getUTCMonth() are used.
String
String parsed for year and month portions.

xsd:hexBinary flash.utils.ByteArray mx.utils.HexEncoder is used.

xsd:integer Number Limited to range of Number.

and derivatives: String String first converted to Number.

xsd:negativeInteger

xsd:nonNegativeInteger

xsd:positiveInteger

xsd:nonPositiveInteger

xsd:int Number String first converted to Number.

xsd:unsignedInt String

xsd:long Number String first converted to Number.

xsd:unsignedLong String

xsd:short Number String first converted to Number.

xsd:unsignedShort String

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 48
Accessing Server-Side Data with Flex

XML schema type Supported ActionScript 3 Notes

types

xsd:string Object Object.toString() is invoked.

and derivatives:

xsd:ID

xsd:IDREF

xsd:IDREFS

xsd:ENTITY

xsd:ENTITIES
xsd:language

xsd:Name

xsd:NCName

xsd:NMTOKEN

xsd:NMTOKENS

xsd:normalizedString

xsd:token

xsd:time Date Date UTC accessor methods are used.

Number Number used to set Date.time.

String String assumed to be preformatted and encoded

as is.

xsi:nil null If the corresponding XML schema element

definition has minOccurs > 0, a null value is
encoded by using xsi:nil; otherwise the element is
omitted entirely.

The following table shows the default mapping from ActionScript 3 types to SOAP-encoded types.

SOAPENC type Supported ActionScript 3 Notes

types

soapenc:Array Array SOAP-encoded arrays are special cases and are supported only
with RPC-encoded web services.
mx.collections.IList

soapenc:base64 flash.utils.ByteArray Encoded in the same manner as xsd:base64Binary.

soapenc:* Object Any other SOAP-encoded type is processed as if it were in the

XSD namespace based on the localName of the type's QName.

Default decoding of XML schema and SOAP to ActionScript 3

The following table shows the default decoding mappings from XML schema built-in types to ActionScript 3 types.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 49
Accessing Server-Side Data with Flex

XML schema type Decoded ActionScript 3 Notes

types

xsd:anyType String If content is empty -> xsd:string.

xsd:anySimpleType Boolean If content cast to Number and value is NaN; or

Number if content starts with "0" or "-0", or

if content ends with "E":

then, if content is "true" or "false" -> xsd:boolean

otherwise -> xsd:string.

Otherwise content is a valid Number and thus ->

xsd:double.

xsd:base64Binary flash.utils.ByteArray mx.utils.Base64Decoder is used.

xsd:boolean Boolean If content is "true" or "1" then true, otherwise

false.

xsd:date Date If no time zone information is present, local time is

assumed.

xsd:dateTime Date If no time zone information is present, local time is

assumed.

xsd:decimal Number Content is created via Number(content) and is

thus limited to the range of Number.

Number.NaN, Number.POSITIVE_INFINITY and

Number.NEGATIVE_INFINITY are not allowed.

xsd:double Number Content is created via Number(content) and is

thus limited to the range of Number.

xsd:duration String Content is returned with whitespace collapsed.

xsd:float Number Content is converted through Number(content)

and is thus limited to the range of Number.

xsd:gDay uint Content is converted through uint(content).

xsd:gMonth uint Content is converted through uint(content).

xsd:gMonthDay String Content is returned with whitespace collapsed.

xsd:gYear uint Content is converted through uint(content).

xsd:gYearMonth String Content is returned with whitespace collapsed.

xsd:hexBinary flash.utils.ByteArray mx.utils.HexDecoder is used.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 50
Accessing Server-Side Data with Flex

XML schema type Decoded ActionScript 3 Notes

types

xsd:integer Number Content is decoded via parseInt().

and derivatives: Number.NaN, Number.POSITIVE_INFINITY and

Number.NEGATIVE_INFINITY are not allowed.
xsd:byte

xsd:int

xsd:long

xsd:negativeInteger

xsd:nonNegativeInteger

xsd:nonPositiveInteger

xsd:positiveInteger

xsd:short

xsd:unsignedByte

xsd:unsignedInt

xsd:unsignedLong

xsd:unsignedShort

xsd:string String The raw content is simply returned as a string.

and derivatives:

xsd:ID

xsd:IDREF

xsd:IDREFS

xsd:ENTITY

xsd:ENTITIES
xsd:language

xsd:Name

xsd:NCName

xsd:NMTOKEN

xsd:NMTOKENS

xsd:normalizedString

xsd:token

xsd:time Date If no time zone information is present, local time is

assumed.

xsi:nil null

The following table shows the default decoding mappings from SOAP-encoded types to ActionScript 3 types.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 51
Accessing Server-Side Data with Flex

SOAPENC type Decoded ActionScript Notes

type

soapenc:Array Array SOAP-encoded arrays are special cases. If

makeObjectsBindable is true, the result is wrapped in
mx.collections.Ar
an ArrayCollection; otherwise a simple array is returned.
rayCollection

soapenc:base64 flash.utils.ByteA Decoded in the same manner as xsd:base64Binary.

rray

soapenc:* Object Any other SOAP-encoded type is processed as if it were in

the XSD namespace based on the localName of the
type's QName.

The following table shows the default decoding mappings from custom data types to ActionScript 3 data types.

Custom type Decoded ActionScript 3 type Notes

Apache Map Object SOAP representation of java.util.Map. Keys

must be representable as strings.
http://xml.apache.o
rg/xml-soap:Map

Apache Rowset Array of objects

http://xml.apache.o
rg/xml-soap:Rowset

ColdFusion QueryBean Array of objects If makeObjectsBindable is true, the resulting

array is wrapped in an ArrayCollection.
http://rpc.xml.cold mx.collections.ArrayColl
fusion:QueryBean ection of objects

XML Schema element support

The following XML schema structures or structure attributes are only partially implemented in Flex 3:
<choice>
<all>
<union

The following XML Schema structures or structure attributes are ignored and are not supported in Flex 3:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 52
Accessing Server-Side Data with Flex

<attribute use="required"/>

<element
substitutionGroup="..."
unique="..."
key="..."
keyref="..."
field="..."
selector="..."/>

<simpleType>
<restriction>
<minExclusive>
<minInclusive>
<maxExclusiv>
<maxInclusive>
<totalDigits>
<fractionDigits>
<length>
<minLength>
<maxLength>
<enumeration>
<whiteSpace>
<pattern>
</restriction>
</simpleType>

<complexType
final="..."
block="..."
mixed="..."
abstract="..."/>

<any
processContents="..."/>
<annotation>

Customizing web service type mapping

When consuming data from a web service invocation, Flex usually creates untyped anonymous ActionScript objects
that mimic the XML structure in the body of the SOAP message. If you want Flex to create an instance of a specific
class, you can use an mx.rpc.xml.SchemaTypeRegistry object and register a QName object with a corresponding
ActionScript class.
For example, suppose you have the following class definition in a file named User.as:
package
{
public class User
{
public function User() {}

public var firstName:String;

public var lastName:String;
}
}

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 53
Accessing Server-Side Data with Flex

Next, you want to invoke a getUser operation on a web service that returns the following XML:
<tns:getUserResponse xmlns:tns="http://example.uri">
<tns:firstName>Ivan</tns:firstName>
<tns:lastName>Petrov</tns:lastName>
</tns:getUserResponse>

To make sure you get an instance of your User class instead of a generic Object when you invoke the getUser operation,
you need the following ActionScript code inside a method in your Flex application:
SchemaTypeRegistry.getInstance().registerClass(new QName("http://example.uri",
"getUserResponse"), User);

SchemaTypeRegistry.getInstance() is a static method that returns the default instance of the type registry. In
most cases, that is all you need. However, this registers a given QName with the same ActionScript class across all web
service operations in your application. If you want to register different classes for different operations, you need the
following code in a method in your application:
var qn:QName = new QName("http://the.same", "qname");
var typeReg1:SchemaTypeRegistry = new SchemaTypeRegistry();
var typeReg2:SchemaTypeRegistry = new SchemaTypeRegistry();
typeReg1.registerClass(qn, someClass);
myWS.someOperation.decoder.typeRegistry = typeReg1;

typeReg2.registerClass(qn, anotherClass);
myWS.anotherOperation.decoder.typeRegistry = typeReg2;

Using custom web service serialization

There are two approaches to take full control over how ActionScript objects are serialized into XML and how XML
response messages are deserialized. The recommended approach is to work directly with E4X.
If you pass an instance of XML as the only parameter to a web service operation, it is passed on untouched as the child
of the <SOAP:Body> node in the serialized request. Use this strategy when you need full control over the SOAP
message. Similarly, when deserializing a web service response, you can set the operation’s resultFormat property to
e4x. This returns an XMLList object with the children of the <SOAP:Body> node in the response message. From there,
you can implement the necessary custom logic to create the appropriate ActionScript objects.
The second and more tedious approach is to provide your own implementations of mx.rpc.soap.ISOAPDecoder and
mx.rpc.soap.ISOAPEncoder. For example, if you have written a class called MyDecoder that implements
ISOAPDecoder, you can have the following in a method in your Flex application:
myWS.someOperation.decoder = new MyDecoder();

When invoking someOperation, Flex calls the decodeResponse() method of the MyDecoder class. From that point
on it is up to the custom implementation to handle the full SOAP message and produce the expected ActionScript
objects.

Using RemoteObject components

You can use a Flex RemoteObject component to call methods on a ColdFusion component or Java class. You can also
use RemoteObject components with PHP and .NET objects in conjunction with third-party software, such as the open
source projects AMFPHP and SabreAMF, and Midnight Coders WebORB. For more information, see the following
websites:
• AMFPHP http://amfphp.sourceforge.net/

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 54
Accessing Server-Side Data with Flex

• SabreAMF http://www.osflash.org/sabreamf
• Midnight Coders WebORB http://www.themidnightcoders.com/
As with HTTPService and WebService components, you can use a RemoteObject component to display the result
of a database query in a Flex application and insert data into a database. When the result has been returned to the
Flex application, you can display it in one or more user interface controls.
For API reference information about the RemoteObject component, see mx.rpc.remoting.mxml.RemoteObject.

Sample RemoteObject application

MXML code
The Flex application in the following example uses a RemoteObject component to call a ColdFusion component. The
ColdFusion component queries a MySQL database table called users. It returns the query result to the Flex application
where it is bound to the dataProvider property of a DataGrid control and displayed in the DataGrid control. The
Flex application also sends the user name and e-mail address of new users to the ColdFusion component, which
performs an insert into the user database table.
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*" layout="absolute"
creationComplete="userRequest.returnRecords()">
<mx:Form x="22" y="10" width="493">
<mx:HBox>
<mx:Label text="Username"/>
<mx:TextInput id="username"/>
</mx:HBox>
<mx:HBox>
<mx:Label text="Email Address"/>
<mx:TextInput id="emailaddress"/>
</mx:HBox>
<mx:Button label="Submit" click="clickHandler()"/>
</mx:Form>
<mx:DataGrid id="dgUserRequest" x="22" y="128">
<mx:columns>
<mx:DataGridColumn headerText="User ID" dataField="userid"/>
<mx:DataGridColumn headerText="User Name" dataField="username"/>
</mx:columns>
</mx:DataGrid>
<mx:TextInput x="22" y="292" id="selectedemailaddress"
text="{dgUserRequest.selectedItem.emailaddress}"/>
<mx:RemoteObject
id="userRequest"
destination="ColdFusion"
source="flexapp.returnusers">

<mx:method name="returnRecords" result="returnHandler(event)"

fault="mx.controls.Alert.show(event.fault.faultString)"/>
<mx:method name="insertRecord" result="insertHandler()"
fault="mx.controls.Alert.show(event.fault.faultString)"/>
</mx:RemoteObject>

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 55
Accessing Server-Side Data with Flex

<mx:Script>
<![CDATA[
import mx.rpc.events.ResultEvent;

private function returnHandler(e:ResultEvent):void

{
dgUserRequest.dataProvider = e.result;
}
private function insertHandler():void
{
userRequest.returnRecords();
}
private function clickHandler():void
{
userRequest.insertRecord(username.text, emailaddress.text);
}
]]>
</mx:Script>
</mx:Application>

In this application, the RemoteObject component’s destination property is set to Coldfusion and the source
property is set to the fully qualified name of the ColdFusion component.
In contrast, when working with LiveCycle Data Services ES or BlazeDS, you specify a fully qualified class name in the
source property of a remoting service destination in a configuration file, which by default is the remoting-config.xml
file. You specify the name of the destination in the RemoteObject component’s destination property. The
destination class also must have a no-args constructor. You can optionally configure a destination this way when
working with ColdFusion instead of by using the source property on the RemoteObject component.

ColdFusion component
The Flex application calls the following ColdFusion component. This ColdFusion code performs SQL database inserts
and queries and returns query results to the Flex application. The ColdFusion page uses the cfquery tag to insert data
into the database and query the database, and it uses the cfreturn tag to format the query results as a ColdFusion
query object.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 56
Accessing Server-Side Data with Flex

<cfcomponent name="returnusers">
<cffunction name="returnRecords" access="remote" returnType="query">

<cfquery name="alluserinfo" datasource="flexcf">

SELECT userid, username, emailaddress FROM users
</cfquery>
<cfreturn alluserinfo>
</cffunction>
<cffunction name="insertRecord" access="remote" returnType="void">

<cfargument name="username" required="true" type="string">

<cfargument name="emailaddress" required="true" type="string">
<cfquery name="addempinfo" datasource="flexcf">
INSERT INTO users (username, emailaddress) VALUES (
<cfqueryparam value="#arguments.username#" cfsqltype="CF_SQL_VARCHAR"
maxlength="255">,
<cfqueryparam value="#arguments.emailaddress#" cfsqltype="CF_SQL_VARCHAR"
maxlength="255"> )
</cfquery>
<cfreturn>
</cffunction>
</cfcomponent>

Calling RemoteObject components in ActionScript

In the following ActionScript example, calling the useRemoteObject() method declares the service, sets the
destination, sets up result and fault event listeners, and calls the service’s getList() method.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 57
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\ROInAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
import mx.controls.Alert;
import mx.rpc.remoting.RemoteObject;
import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;

[Bindable]
public var empList:Object;
public var employeeRO:RemoteObject;

public function useRemoteObject(intArg:int, strArg:String):void {

employeeRO = new RemoteObject();
employeeRO.destination = "SalaryManager";
employeeRO.getList.addEventListener("result", getListResultHandler);
employeeRO.addEventListener("fault", faultHandler);
employeeRO.getList(deptComboBox.selectedItem.data);
}

public function getListResultHandler(event:ResultEvent):void {

// Do something
empList=event.result;
}

public function faultHandler (event:FaultEvent):void {

// Deal with event.fault.faultString, etc.
Alert.show(event.fault.faultString, 'Error');
}
]]>
</mx:Script>
<mx:ComboBox id="deptComboBox"/>
</mx:Application>

Accessing Java objects in the source path

The RemoteObject component lets you access stateless and stateful Java objects that are in the LiveCycle Data Services
ES, BlazeDS, or ColdFusion web application's source path. You can place stand-alone class files in the web application's
WEB-INF/classes directory to add them to the source path. You can place classes contained in Java Archive (JAR) files
in the web application's WEB-INF/lib directory to add them to the source path. You specify the fully qualified class
name in the source property of a remoting service destination in the LiveCycle Data Services ES, BlazeDS, or
ColdFusion services-config.xml file, or a file that it includes by reference, such as the remoting-config.xml file. The
class also must have a no-args constructor. For ColdFusion, you can optionally set the RemoteObject component’s
destination property to Coldfusion and the source property to the fully qualified name of a ColdFusion
component or Java class.
When you configure a remoting service destination to access stateless objects (the request scope), Flex creates a new
object for each method call instead of calling methods on the same object. You can set the scope of an object to the
request scope (default value), the application scope, or the session scope. Objects in the application scope are available
to the web application that contains the object. Objects in the session scope are available to the entire client session.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 58
Accessing Server-Side Data with Flex

When you configure a remote object destination to access stateful objects, Flex creates the object once on the server
and maintains state between method calls. If storing the object in the application or session scope causes memory
problems, you should use the request scope.

Accessing EJBs and other objects in JNDI

You can access Enterprise JavaBeans (EJBs) and other objects stored in the Java Naming and Directory Interface
(JNDI) by calling methods on a destination that is a service facade class that looks up an object in JNDI and calls its
methods.
You can use stateless or stateful objects to call the methods of Enterprise JavaBeans and other objects that use JNDI.
For an EJB, you can call a service facade class that returns the EJB object from JNDI and calls a method on the EJB.
In your Java class, you use the standard Java coding pattern, in which you create an initial context and perform a JNDI
lookup. For an EJB, you also use the standard coding pattern in which your class contains methods that call the EJB
home object's create() method and the resulting EJB's business methods.
The following example uses a method called getHelloData() on a facade class destination:
<mx:RemoteObject id="Hello" destination="roDest">
<mx:method name="getHelloData"/>
</mx:RemoteObject>

On the Java side, the getHelloData() method could encapsulate everything necessary to call a business method on
an EJB. The Java method in the following example performs the following actions:
• Creates new initial context for calling the EJB
• Performs a JNDI lookup that gets an EJB home object
• Calls the EJB home object's create() method
• Calls the EJB's sayHello() method
...
public void getHelloData() {
try{
InitialContext ctx = new InitialContext();
Object obj = ctx.lookup("/Hello");
HelloHome ejbHome = (HelloHome)
PortableRemoteObject.narrow(obj, HelloHome.class);
HelloObject ejbObject = ejbHome.create();
String message = ejbObject.sayHello();
}
catch (Exception e);
}
...

Reserved method names

The Flex remoting library uses the following method names; do not use these as your own method names:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 59
Accessing Server-Side Data with Flex

addHeader()
addProperty()
deleteHeader()
hasOwnProperty()
isPropertyEnumerable()
isPrototypeOf()
registerClass()
toLocaleString()
toString()
unwatch()
valueOf()
watch()

Also, you should not begin method names with an underscore (_) character.
RemoteObject methods (operations) are usually accessible by simply naming them after the service variable. However,
naming conflicts can occur if an operation name happens to match a defined method on the service. You can use the
following method in ActionScript on a RemoteObject component to return the operation of the given name:
public function getOperation(name:String):Operation

Serialization between ActionScript and Java

LiveCycle Data Services ES and Flex let you serialize data between ActionScript (AMF 3) and Java in both directions.

Data conversion from ActionScript to Java

When method parameters send data from a Flex application to a Java object, the data is automatically converted from
an ActionScript data type to a Java data type. When LiveCycle Data Services ES searches for a suitable method on the
Java object, it uses further, more lenient conversions to find a match.
Simple data types on the client, such as Boolean and String values, typically exactly match a remote API. However, Flex
attempts some simple conversions when searching for a suitable method on a Java object.
An ActionScript Array can index entries in two ways. A strict Array is one in which all indices are Numbers. An
associative Array is one in which at least one index is based on a String. It is important to know which type of Array
you are sending to the server, because it changes the data type of parameters that are used to invoke a method on a Java
object. A dense Array is one in which all numeric indices are consecutive, with no gap, starting from 0 (zero). A sparse
Array is one in which there are gaps between the numeric indices; the Array is treated like an object and the numeric
indices become properties that are deserialized into a java.util.Map object to avoid sending many null entries.
The following table lists the supported ActionScript (AMF 3) to Java conversions for simple data types:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 60
Accessing Server-Side Data with Flex

ActionScript type (AMF 3) Deserialization to Java Supported Java type binding

Array (dense) java.util.List java.util.Collection, Object[ ] (native array)

If the type is an interface, it is mapped to the following

interface implementations

• List becomes ArrayList

• SortedSet becomes TreeSet

• Set becomes HashSet

• Collection becomes ArrayList

A new instance of a custom Collection implementation is

bound to that type.

Array (sparse) java.util.Map java.util.Map

Boolean java.lang.Boolean Boolean, boolean, String

String of "true" or
"false"

flash.utils.ByteArray byte []

flash.utils.IExternalizable java.io.Externalizable

Date java.util.Date java.util.Date, java.util.Calendar, java.sql.Timestamp,

java.sql.Time, java.sql.Date
(formatted for
Coordinated Universal
Time (UTC))

int/uint java.lang.Integer java.lang.Double, java.lang.Long, java.lang.Float,

java.lang.Integer, java.lang.Short, java.lang.Byte,
java.math.BigDecimal, java.math.BigInteger, String,
primitive types of double, long, float, int, short, byte

null null primitives

Number java.lang.Double java.lang.Double, java.lang.Long, java.lang.Float,

java.lang.Integer, java.lang.Short, java.lang.Byte,
java.math.BigDecimal, java.math.BigInteger, String, 0
(zero) if null is sent, primitive types of double, long, float,
int, short, byte

Object (generic) java.util.Map If a Map interface is specified, creates a new

java.util.HashMap for java.util.Map and a new
java.util.TreeMap for java.util.SortedMap.

String java.lang.String java.lang.String, java.lang.Boolean, java.lang.Number,

java.math.BigInteger, java.math.BigDecimal, char[],
enum, any primitive number type

typed Object typed Object typed Object

when you use

[RemoteClass]
metadata tag that
specifies remote class
name. Bean type must
have a public no args
constructor.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 61
Accessing Server-Side Data with Flex

ActionScript type (AMF 3) Deserialization to Java Supported Java type binding

undefined null null for Object, default values for primitives

XML org.w3c.dom.Document org.w3c.dom.Document

XMLDocument org.w3c.dom.Document org.w3c.dom.Document

(legacy XML type) You can enable legacy XML support for the
XMLDocument type on any channel defined in the
services-config.xml file. This setting is only important for
sending data from the server back to the client; it controls
how org.w3c.dom.Document instances are sent to
ActionScript. For more information, see Configuring AMF
serialization on a channel.

Primitive values cannot be set to null in Java. When passing Boolean and Number values from the client to a Java
object, Flex interprets null values as the default values for primitive types; for example, 0 for double, float, long, int,
short, byte, \u0000 for char, and false for boolean. Only primitive Java types get default values.
LiveCycle Data Services ES handles java.lang.Throwable objects like any other typed object. They are processed with
rules that look for public fields and bean properties, and typed objects are returned to the client. The rules are like
normal bean rules except they look for getters for read-only properties. This lets you get more information from a Java
exception. If you require legacy behavior for Throwable objects, you can set the legacy-throwable property to true
on a channel; for more information, see Configuring AMF serialization on a channel.
You can pass strict Arrays as parameters to methods that expect an implementation of the java.util.Collection or native
Java Array APIs.
A Java Collection can contain any number of Object types, whereas a Java Array requires that entries are the same type
(for example, java.lang.Object[ ], and int[ ]).
LiveCycle Data Services ES also converts ActionScript strict Arrays to appropriate implementations for common
Collection API interfaces. For example, if an ActionScript strict Array is sent to the Java object method public void
addProducts(java.util.Set products), LiveCycle Data Services ES converts it to a java.util.HashSet instance
before passing it as a parameter, because HashSet is a suitable implementation of the java.util.Set interface. Similarly,
LiveCycle Data Services ES passes an instance of java.util.TreeSet to parameters typed with the java.util.SortedSet
interface.
LiveCycle Data Services ES passes an instance of java.util.ArrayList to parameters typed with the java.util.List interface
and any other interface that extends java.util.Collection. Then these types are sent back to the client as
mx.collections.ArrayCollection instances. If you require normal ActionScript Arrays sent back to the client, you must
set the legacy-collection element to true in the serialization section of a channel-definition's properties; for
more information, see Configuring AMF serialization on a channel.

Explicitly mapping ActionScript and Java objects

For Java objects that LiveCycle Data Services ES does not handle implicitly, values found in public bean properties with
get/set methods and public variables are sent to the client as properties on an Object. Private properties, constants,
static properties, and read-only properties, and so on, are not serialized. For ActionScript objects, public properties
defined with the get/set accessors and public variables are sent to the server.
LiveCycle Data Services ES uses the standard Java class, java.beans.Introspector, to get property descriptors for a Java
bean class. It also uses reflection to gather public fields on a class. It uses bean properties in preference to fields. The
Java and ActionScript property names should match. Native Flash Player code determines how ActionScript classes
are introspected on the client.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 62
Accessing Server-Side Data with Flex

In the ActionScript class, you use the [RemoteClass(alias=" ")] metadata tag to create an ActionScript object that
maps directly to the Java object. The ActionScript class to which data is converted must be used or referenced in the
MXML file for it to be linked into the SWF file and available at run time. A good way to do this is by casting the result
object, as the following example shows:
var result:MyClass = MyClass(event.result);

The class itself should use strongly typed references so that its dependencies are also linked.
The following example shows the source code for an ActionScript class that uses the [RemoteClass(alias=" ")]
metadata tag:
package samples.contact {
[Bindable]
[RemoteClass(alias="samples.contact.Contact")]
public class Contact {
public var contactId:int;

public var firstName:String;

public var lastName:String;

public var address:String;

public var city:String;

public var state:String;

public var zip:String;

}
}

You can use the [RemoteClass] metadata tag without an alias if you do not map to a Java object on the server, but
you do send back your object type from the server. Your ActionScript object is serialized to a special Map object when
it is sent to the server, but the object returned from the server to the clients is your original ActionScript type.
To restrict a specific property from being sent to the server from an ActionScript class, use the [Transient] metadata
tag above the declaration of that property in the ActionScript class.

Data conversion from Java to ActionScript

An object returned from a Java method is converted from Java to ActionScript. LiveCycle Data Services ES also handles
objects found within objects. LiveCycle Data Services ES implicitly handles the Java data types in the following table.

Java type ActionScript type (AMF 3)

enum (JDK 1.5) String

java.lang.String String

java.lang.Boolean, boolean Boolean

java.lang.Integer, int int

If value < 0xF0000000 || value > 0x0FFFFFFF, the value is promoted to

Number due to AMF encoding requirements.

java.lang.Short, short int

If i < 0xF0000000 || i > 0x0FFFFFFF, the value is promoted to Number.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 63
Accessing Server-Side Data with Flex

Java type ActionScript type (AMF 3)

java.lang.Byte, byte[] int

If i < 0xF0000000 || i > 0x0FFFFFFF, the value is promoted to Number.

java.lang.Byte[] flash.utils.ByteArray

java.lang.Double, double Number

java.lang.Long, long Number

java.lang.Float, float Number

java.lang.Character, char String

java.lang.Character[], char[] String

java. math.BigInteger String

java.math.BigDecimal String

java.util.Calendar Date

Dates are sent in the Coordinated Universal Time (UTC) time zone. Clients
and servers must adjust time accordingly for time zones.

java.util.Date Date

Dates are sent in the UTC time zone. Clients and servers must adjust time
accordingly for time zones.

java.util.Collection (for example, mx.collections.ArrayCollection

java.util.ArrayList)

java.lang.Object[] Array

java.util.Map Object (untyped). For example, a java.util.Map[] is converted to an Array (of

Objects).

java.util.Dictionary Object (untyped)

org.w3c.dom.Document XML object

null null

java.lang.Object (other than Typed Object

previously listed types)
Objects are serialized using Java bean introspection rules and also include
public fields. Fields that are static, transient, or nonpublic, as well as bean
properties that are nonpublic or static, are excluded.

Note: You can enable legacy XML support for the flash.xml.XMLDocument type on any channel that is defined in the
services-config.xml file.
Note: In Flex 1.5, java.util.Map was sent as an associative or ECMA Array. This is no longer a recommended practice.
You can enable legacy Map support to associative Arrays, but Adobe recommends against doing this.

Configuring AMF serialization on a channel

You can support legacy AMF type serialization used in earlier versions of Flex and configure other serialization
properties in channel definitions in the services-config.xml file.
The following table describes the properties that you can set in the <serialization> element of a channel definition:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 64
Accessing Server-Side Data with Flex

Property Description

enable-small-messages Default value is true. If enabled, messages are sent using an alternative
smaller form if one is available and the endpoint supports it.

ignore-property-errors Default value is true. Determines if the endpoint should throw an error when
an incoming client object has unexpected properties that cannot be set on
the server object.

log-property-errors Default value is false. When true, unexpected property errors are logged.

legacy-collection Default value is false. When true, instances of java.util.Collection are

returned as ActionScript Arrays. When false, instance of
java.util.Collection are returned as mx.collections.ArrayCollection.

legacy-map Default value is false. When true, java.util.Map instances are serialized as an
ECMA Array or associative array instead of an anonymous Object.

legacy-xml Default value is false. When true, org.w3c.dom.Document instances are

serialized as flash.xml.XMLDocument instances instead of intrinsic XML (E4X
capable) instances.

legacy-throwable Default value is false. When true, java.lang.Throwable instances are

serialized as AMF status-info objects (instead of normal bean serialization,
including read-only properties).

legacy-externalizable Default value is false. When true, java.io.Externalizable types (that extend
standard Java classes like Date, Number, String) are not serialized as custom
objects (for example, MyDate is serialized as Date instead of MyDate). Note
that this setting overwrites any other legacy settings. For example, if
legacy-collection is true but the collection implements
java.io.Externalizable, the collection is returned as custom object without
taking the legacy-collection value into account.

type-marshaller Specifies an implementation of flex.messaging.io.TypeMarshaller that

translates an object into an instance of a desired class. Used when invoking
a Java method or populating a Java instance and the type of the input object
from deserialization (for example, an ActionScript anonymous Object is
always deserialized as a java.util.HashMap) doesn't match the destination
API (for example, java.util.SortedMap). Thus, the type can be marshalled into
the desired type.

restore-references Default value is false. An advanced switch to make the deserializer keep
track of object references when a type translation has to be made; for
example, when an anonymous Object is sent for a property of type
java.util.SortedMap, the Object is first deserialized to a java.util.Map as
normal, and then translated to a suitable implementation of SortedMap
(such as java.util.TreeMap). If other objects pointed to the same anonymous
Object in an object graph, this setting restores those references instead of
creating SortedMap implementations everywhere. Notice that setting this
property to true can slow down performance significantly for large
amounts of data.

instantiate-types Default value is true. Advanced switch that when set to false stops the
deserializer from creating instances of strongly typed objects and instead
retains the type information and deserializes the raw properties in a Map
implementation, specifically flex.messaging.io.ASObject. Notice that any
classes under flex.* package are always instantiated.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 65
Accessing Server-Side Data with Flex

XML schema type ActionScript type

ComplexType Anonymous Object or any other typed object with

expected properties defined

sequence Array

boolean Boolean

string String

normalizedString String

all number types Number, int, uint

date Date

dateTime Date

time Date

Base64Binary flash.utils.ByteArray

hexBinary

flash.utils.ByteArray

anyType (in WSDL) Converts the ActionScript types to the following Schema
types:

• uint to unsignedInt

• int to int

• Number to double

• Boolean to boolean

• String to string

• XMLDocument to schema

• Date to dateTime

• Array to array. If no type information is available, if no

type information is available, the first item in the Array
is used to determine the type

SOAP type ActionScript type

base64 flash.utils.ByteArray

number types Number

boolean Boolean

Array Array

string String

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 66
Accessing Server-Side Data with Flex

Apache Axis type ActionScript type

Map Object

RowSet Can only receive RowSets; can’t send them.

Document Can only receive Documents; can’t send them.

Element flash.xml.XMLNode

Using custom serialization between ActionScript and Java

If the standard mechanisms for serializing and deserializing data between ActionScript on the client and Java on the
server do not meet your needs, you can write your own serialization scheme. You implement the ActionScript-based
flash.utils.IExternalizable interface on the client and the corresponding Java-based java.io.Externalizable interface on
the server.
A typical reason to use custom serialization is to avoid passing all of the properties of either the client-side or server-
side representation of an object across the network tier. When you implement custom serialization, you can code your
classes so that specific properties that are client-only or server-only are not passed over the wire. When you use the
standard serialization scheme, all public properties are passed back and forth between the client and the server.
On the client side, the identity of a class that implements the flash.utils.IExternalizable interface is written in the
serialization stream. The class serializes and reconstructs the state of its instances. The class implements the
writeExternal() and readExternal() methods of the IExternalizable interface to get control over the contents and
format of the serialization stream, but not the class name or type, for an object and its supertypes. These methods
supersede the native AMF serialization behavior. These methods must be symmetrical with their remote counterpart
to save the class's state.
On the server side, a Java class that implements the java.io.Externalizable interface performs functionality that is
analogous to an ActionScript class that implements the flash.utils.IExternalizable interface.
Note: You should not use types that implement the IExternalizable interface with the HTTPChannel if precise by-
reference serialization is required. When you do this, references between recurring objects are lost and appear to be cloned
at the endpoint.
The following example shows the complete source code for the client (ActionScript) version of a Product class that
maps to a Java-based Product class on the server. The client Product implements the IExternalizable interface and the
server Product implements the Externalizable interface.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 67
Accessing Server-Side Data with Flex

// Product.as
package samples.externalizable {

import flash.utils.IExternalizable;
import flash.utils.IDataInput;
import flash.utils.IDataOutput;

[RemoteClass(alias="samples.externalizable.Product")]
public class Product implements IExternalizable {
public function Product(name:String=null) {
this.name = name;
}

public var id:int;

public var name:String;
public var properties:Object;
public var price:Number;

public function readExternal(input:IDataInput):void {

name = input.readObject() as String;
properties = input.readObject();
price = input.readFloat();
}

public function writeExternal(output:IDataOutput):void {

output.writeObject(name);
output.writeObject(properties);
output.writeFloat(price);
}
}
}

The client Product uses two kinds of serialization. It uses the standard serialization that is compatible with the
java.io.Externalizable interface and AMF 3 serialization. The following example shows the writeExternal() method
of the client Product, which uses both types of serialization:
public function writeExternal(output:IDataOutput):void {
output.writeObject(name);
output.writeObject(properties);
output.writeFloat(price);
}

As the following example shows, the writeExternal() method of the server Product is almost identical to the client
version of this method:
public void writeExternal(ObjectOutput out) throws IOException {
out.writeObject(name);
out.writeObject(properties);
out.writeFloat(price);
}

In the client Product's writeExternal() method, the flash.utils.IDataOutput.writeFloat() method is an

example of standard serialization methods that meet the specifications for the Java
java.io.DataInput.readFloat() methods for working with primitive types. This method sends the price
property, which is a Float, to the server Product.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 68
Accessing Server-Side Data with Flex

The examples of AMF 3 serialization in the client Product's writeExternal() method is the call to the
flash.utils.IDataOutput.writeObject() method, which maps to the java.io.ObjectInput.readObject()
method call in the server Product's readExternal() method. The flash.utils.IDataOutput.writeObject()
method sends the properties property, which is an Object, and the name property, which is a String, to the server
Product. This is possible because the AMFChannel endpoint has an implementation of the java.io.ObjectInput
interface that expects data sent from the writeObject() method to be formatted as AMF 3.
In turn, when the readObject() method is called in the server Product's readExternal() method, it uses AMF 3
deserialization; this is why the ActionScript version of the properties value is assumed to be of type Map and name
is assumed to be of type String.
The following example shows the complete source of the server Product class:
// Product.java
package samples.externalizable;

import java.io.Externalizable;
import java.io.IOException;
import java.io.ObjectInput;
import java.io.ObjectOutput;
import java.util.Map;

/**
* This Externalizable class requires that clients sending and
* receiving instances of this type adhere to the data format
* required for serialization.
*/
public class Product implements Externalizable {
private String inventoryId;
public String name;
public Map properties;
public float price;

public Product()
{
}

/**
* Local identity used to track third party inventory. This property is
* not sent to the client because it is server-specific.
* The identity must start with an 'X'.
*/
public String getInventoryId() {
return inventoryId;
}

public void setInventoryId(String inventoryId) {

if (inventoryId != null && inventoryId.startsWith("X"))
{
this.inventoryId = inventoryId;
}
else
{
throw new IllegalArgumentException("3rd party product
inventory identities must start with 'X'");
}
}

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 69
Accessing Server-Side Data with Flex

/**
* Deserializes the client state of an instance of ThirdPartyProxy
* by reading in String for the name, a Map of properties
* for the description, and
* a floating point integer (single precision) for the price.
*/
public void readExternal(ObjectInput in) throws IOException,
ClassNotFoundException {
// Read in the server properties from the client representation.
name = (String)in.readObject();
properties = (Map)in.readObject();
price = in.readFloat();
setInventoryId(lookupInventoryId(name, price));
}
/**
* Serializes the server state of an instance of ThirdPartyProxy
* by sending a String for the name, a Map of properties
* String for the description, and a floating point
* integer (single precision) for the price. Notice that the inventory
* identifier is not sent to external clients.
*/
public void writeExternal(ObjectOutput out) throws IOException {
// Write out the client properties from the server representation
out.writeObject(name);
out.writeObject(properties);
out.writeFloat(price);
}

private static String lookupInventoryId(String name, float price) {

String inventoryId = "X" + name + Math.rint(price);
return inventoryId;
}
}

The following example shows the server Product's readExternal() method:

public void readExternal(ObjectInput in) throws IOException,
ClassNotFoundException {
// Read in the server properties from the client representation.
name = (String)in.readObject();
properties = (Map)in.readObject();
price = in.readFloat();
setInventoryId(lookupInventoryId(name, price));
}

The client Product's writeExternal() method does not send the id property to the server during serialization
because it is not useful to the server version of the Product object. Similarly, the server Product's writeExternal()
method does not send the inventoryId property to the client because it is a server-specific property.
Notice that the names of a Product's properties are not sent during serialization in either direction. Because the state
of the class is fixed and manageable, the properties are sent in a well-defined order without their names, and the
readExternal() method reads them in the appropriate order.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 70
Accessing Server-Side Data with Flex

Explicit parameter passing and parameter binding

There are two distinct ways to call HTTPService, WebService, and RemoteObject components: explicit parameter
passing and parameter binding. When you use explicit parameter passing, you provide input to a service in the form
of parameters to an ActionScript function. This way of calling a service closely resembles the way that you call methods
in Java. You cannot use Flex data validators automatically in combination with explicit parameter passing.
Parameter binding lets you copy data from user-interface controls or models to request parameters. Parameter binding
is available only for data access components that you declare in MXML. You can apply validators to parameter values
before submitting requests to services. For more information about data binding and data models, see Data binding
and Storing Data. For more information about data validation, see Validating Data.
When you use parameter binding, you declare RemoteObject method parameter tags nested in an <mx:arguments>
tag under an <mx:method> tag, HTTPService parameter tags nested in an <mx:request> tag, or WebService operation
parameter tags nested in an <mx:request> tag under an <mx:operation> tag. You use the send() method to send
the request.

Explicit parameter passing with RemoteObject and WebService components

The way you use explicit parameter passing with RemoteObject and WebService components is very similar. The
following example shows MXML code for declaring a RemoteObject component and calling a service by using explicit
parameter passing in the click event listener of a Button control. A ComboBox control provides data to the service.
Simple event listeners handle the service-level result and fault events.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 71
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\RPCParamPassing.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
verticalGap="10">
<mx:Script>
<![CDATA[
import mx.controls.Alert;
[Bindable]
public var empList:Object;
]]>
</mx:Script>

<mx:RemoteObject
id="employeeRO"
destination="SalaryManager"
result="empList=event.result"
fault="Alert.show(event.fault.faultString, 'Error');"/>

<mx:ComboBox id="dept" width="150">

<mx:dataProvider>
<mx:ArrayCollection>
<mx:source>
<mx:Object label="Engineering" data="ENG"/>
<mx:Object label="Product Management" data="PM"/>
<mx:Object label="Marketing" data="MKT"/>
</mx:source>
</mx:ArrayCollection>
</mx:dataProvider>
</mx:ComboBox>

<mx:Button label="Get Employee List" click="employeeRO.getList(dept.selectedItem.data);"/>

</mx:Application>

Explicit parameter passing with HTTPService components

Explicit parameter passing with HTTPService components is different than it is with RemoteObject and WebService
components. You always use an HTTPService component’s send() method to call a service. This is different from
RemoteObject and WebService components, on which you call methods that are client-side versions of the methods
or operations of the RPC service.
When you use explicit parameter passing, you can specify an object that contains name-value pairs as a send()
method parameter. A send() method parameter must be a simple base type; you cannot use complex nested objects
because there is no generic way to convert them to name-value pairs.
If you do not specify a parameter to the send() method, the HTTPService component uses any query parameters
specified in an <mx:request> tag.
The following examples show two ways to call an HTTP service by using the send() method with a parameter. The
second example also shows how to call the cancel() method to cancel an HTTP service call.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 72
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\RPCSend.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script>
<![CDATA[
public function callService():void {
// Cancel all previous pending calls.
myService.cancel();

var params:Object = new Object();

params.param1 = 'val1';
myService.send(params);
}
]]>
</mx:Script>

<mx:HTTPService
id="myService"
destination="Dest"
useProxy="true"/>
<!-- HTTP service call with a send() method that takes a variable as its parameter. The value
of the variable is an Object. -->
<mx:Button click="myService.send({param1: 'val1'});"/>

<!-- HTTP service call with an object as a send() method parameter that provides query
parameters. -->
<mx:Button click="callService();"/>
</mx:Application>

Parameter binding with RemoteObject components

When you use parameter binding with RemoteObject components, you always declare methods in a RemoteObject
component’s <mx:method> tag.
An <mx:method> tag can contain an <mx:arguments> tag that contains child tags for the method parameters. The
name property of an <mx:method> tag must match one of the service’s method names. The order of the argument tags
must match the order of the service’s method parameters. You can name argument tags to match the actual names of
the corresponding method parameters as closely as possible, but this is not necessary.
Note: If argument tags inside an <mx:arguments> tag have the same name, service calls fail if the remote method is not
expecting an array as the only input source. There is no warning about this when the application is compiled.
You can bind data to a RemoteObject component’s method parameters. You reference the tag names of the parameters
for data binding and validation.
The following example shows a method with two parameters bound to the text properties of TextInput controls. A
PhoneNumberValidator validator is assigned to arg1, which is the name of the first argument tag.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 73
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\ROParamBind1.mxml. -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:RemoteObject
id="ro"
destination="roDest">

<mx:method name="setData">
<mx:arguments>
<arg1>{text1.text}</arg1>
<arg2>{text2.text}</arg2>
</mx:arguments>
</mx:method>
</mx:RemoteObject>
<mx:TextInput id="text1"/>
<mx:TextInput id="text2"/>

<mx:PhoneNumberValidator source="{ro.setData.arguments}" property="arg1"/>

</mx:Application>

Flex sends the argument tag values to the method in the order that the MXML tags specify.
The following example uses parameter binding in a RemoteObject component’s <mx:method> tag to bind the data of
a selected ComboBox item to the employeeRO.getList operation when the user clicks a Button control. When you
use parameter binding, you call a service by using the send() method with no parameters.
<?xml version="1.0"?>
<!-- fds\rpc\ROParamBind2.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" verticalGap="10">
<mx:Script>
<![CDATA[
import mx.controls.Alert;
import mx.utils.ArrayUtil;
]]>
</mx:Script>
<mx:RemoteObject
id="employeeRO"
destination="roDest"
showBusyCursor="true"
fault="Alert.show(event.fault.faultString, 'Error');">
<mx:method name="getList">
<mx:arguments>
<deptId>{dept.selectedItem.data}</deptId>
</mx:arguments>
</mx:method>
</mx:RemoteObject>
<mx:ArrayCollection id="employeeAC"
source="{ArrayUtil.toArray(employeeRO.getList.lastResult)}"/>

<mx:HBox>
<mx:Label text="Select a department:"/>
<mx:ComboBox id="dept" width="150">

<mx:dataProvider>

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 74
Accessing Server-Side Data with Flex

<mx:ArrayCollection>
<mx:source>
<mx:Object label="Engineering" data="ENG"/>
<mx:Object label="Product Management" data="PM"/>
<mx:Object label="Marketing" data="MKT"/>
</mx:source>
</mx:ArrayCollection>
</mx:dataProvider>
</mx:ComboBox>
<mx:Button label="Get Employee List"
click="employeeRO.getList.send()"/>
</mx:HBox>
<mx:DataGrid dataProvider="{employeeAC}" width="100%">
<mx:columns>
<mx:DataGridColumn dataField="name" headerText="Name"/>
<mx:DataGridColumn dataField="phone" headerText="Phone"/>
<mx:DataGridColumn dataField="email" headerText="Email"/>
</mx:columns>
</mx:DataGrid>
</mx:Application>

If you are unsure whether the result of a service call contains an array or an individual object, you can use the
toArray() method of the mx.utils.ArrayUtil class to convert the result to an array, as this example shows. If you pass
the toArray() method to an individual object, it returns an array with that object as the only Array element. If you
pass an array to the method, it returns the same array. For information about working with ArrayCollection objects,
see Data providers and collections.

Parameter binding with HTTPService components

When an HTTP service takes query parameters, you can declare them as child tags of an <mx:request> tag. The
names of the tags must match the names of the query parameters that the service expects.
The following example uses parameter binding in an HTTPService component’s <mx:request> tag to bind the data
of a selected ComboBox item to the employeeSrv request when the user clicks a Button control. When you use
parameter binding, you call a service by using the send() method with no parameters. This example shows a url
property on the HTTPService component, but the way you call a service is the same whether you connect to the service
directly or go through a destination.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 75
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- fds\rpc\HttpServiceParamBind.mxml. Compiles -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" verticalGap="20">
<mx:Script>
<![CDATA[
import mx.utils.ArrayUtil;
]]>
</mx:Script>

<mx:HTTPService
id="employeeSrv"
url="employees.jsp">
<mx:request>
<deptId>{dept.selectedItem.data}</deptId>
</mx:request>
</mx:HTTPService>
<mx:ArrayCollection
id="employeeAC"
source=
"{ArrayUtil.toArray(employeeSrv.lastResult.employees.employee)}"/>
<mx:HBox>
<mx:Label text="Select a department:"/>
<mx:ComboBox id="dept" width="150">
<mx:dataProvider>
<mx:ArrayCollection>
<mx:source>
<mx:Object label="Engineering" data="ENG"/>
<mx:Object label="Product Management" data="PM"/>
<mx:Object label="Marketing" data="MKT"/>
</mx:source>
</mx:ArrayCollection>
</mx:dataProvider>
</mx:ComboBox>
<mx:Button label="Get Employee List" click="employeeSrv.send();"/>
</mx:HBox>
<mx:DataGrid dataProvider="{employeeAC}"
width="100%">
<mx:columns>
<mx:DataGridColumn dataField="name" headerText="Name"/>
<mx:DataGridColumn dataField="phone" headerText="Phone"/>
<mx:DataGridColumn dataField="email" headerText="Email"/>
</mx:columns>
</mx:DataGrid>
</mx:Application>

If you are unsure whether the result of a service call contains an array or an individual object, you can use the
toArray() method of the mx.utils.ArrayUtil class to convert it to an array, as the previous example shows. If you pass
the toArray() method to an individual object, it returns an array with that object as the only Array element. If you
pass an array to the method, it returns the same array. For information about working with ArrayCollection objects,
see Data providers and collections.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 76
Accessing Server-Side Data with Flex

Parameter binding with WebService components

When you use parameter binding with a WebService component, you always declare operations in the WebService
component’s <mx:operation> tags. An <mx:operation> tag can contain an <mx:request> tag that contains the
XML nodes that the operation expects. The name property of an <mx:operation> tag must match one of the web
service operation names.
You can bind data to parameters of web service operations. You reference the tag names of the parameters for data
binding and validation.
The following example uses parameter binding in a WebService component’s <mx:operation> tag to bind the data of
a selected ComboBox item to the employeeWS.getList operation when the user clicks a Button control. The
<deptId> tag corresponds directly to the getList operation’s deptId parameter. When you use parameter binding, you
call a service by using the send() method with no parameters. This example shows a destination property on the
WebService component, but the way you call a service is the same whether you connect to the service directly or go
through a destination.
<?xml version="1.0"?>
<!-- fds\rpc\WebServiceParamBind.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" verticalGap="10">
<mx:Script>
<![CDATA[
import mx.utils.ArrayUtil;
import mx.controls.Alert;
]]>
</mx:Script>

<mx:WebService
id="employeeWS"
destination="wsDest"
showBusyCursor="true"
fault="Alert.show(event.fault.faultString)">
<mx:operation name="getList">
<mx:request>
<deptId>{dept.selectedItem.data}</deptId>
</mx:request>
</mx:operation>
</mx:WebService>
<mx:ArrayCollection
id="employeeAC"
source="{ArrayUtil.toArray(employeeWS.getList.lastResult)}"/>
<mx:HBox>
<mx:Label text="Select a department:"/>
<mx:ComboBox id="dept" width="150">
<mx:dataProvider>

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 77
Accessing Server-Side Data with Flex

<mx:ArrayCollection>
<mx:source>
<mx:Object label="Engineering" data="ENG"/>
<mx:Object label="Product Management" data="PM"/>
<mx:Object label="Marketing" data="MKT"/>
</mx:source>
</mx:ArrayCollection>
</mx:dataProvider>
</mx:ComboBox>
<mx:Button label="Get Employee List"
click="employeeWS.getList.send()"/>
</mx:HBox>
<mx:DataGrid dataProvider="{employeeAC}" width="100%">
<mx:columns>
<mx:DataGridColumn dataField="name" headerText="Name"/>
<mx:DataGridColumn dataField="phone" headerText="Phone"/>
<mx:DataGridColumn dataField=" to email" headerText="Email"/>
</mx:columns>
</mx:DataGrid>
</mx:Application>

You can also manually specify an entire SOAP request body in XML with all of the correct namespace information
defined in an <mx:request> tag. To do this, you must set the value of the format attribute of the <mx:request> tag
to xml, as the following example shows:
<?xml version="1.0"?>
<!-- fds\rpc\WebServiceSOAPRequest.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" verticalGap="10">
<mx:WebService id="ws" wsdl="http://api.google.com/GoogleSearch.wsdl"
useProxy="true">
<mx:operation name="doGoogleSearch" resultFormat="xml">
<mx:request format="xml">
<ns1:doGoogleSearch xmlns:ns1="urn:GoogleSearch"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<key xsi:type="xsd:string">XYZ123</key>
<q xsi:type="xsd:string">Balloons</q>
<start xsi:type="xsd:int">0</start>
<maxResults xsi:type="xsd:int">10</maxResults>
<filter xsi:type="xsd:boolean">true</filter>
<restrict xsi:type="xsd:string"/>
<safeSearch xsi:type="xsd:boolean">false</safeSearch>
<lr xsi:type="xsd:string" />
<ie xsi:type="xsd:string">latin1</ie>
<oe xsi:type="xsd:string">latin1</oe>
</ns1:doGoogleSearch>
</mx:request>
</mx:operation>
</mx:WebService>
</mx:Application>

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 78
Accessing Server-Side Data with Flex

Handling service events

Calls to a remote service are asynchronous. After you invoke an asynchronous call, your application does not wait for
the result, but continues to execute. Therefore, you typically use events to signal that the service call has completed.
When a service call completes, the WebService and HTTPService components dispatch one of the following events:
• A result event indicates that the result is available. A result event generates an mx.rpc.events.ResultEvent object.
You can use the result property of the ResultEvent object to access the data returned by the service call.
• A fault event indicates that an error occurred. A fault event generates an mx.rpc.events.FaultEvent object. You
can use the fault property of the FaultEvent object to access information about the failure.
You can also handle the invoke event, which is broadcast when an RPC component makes the service call. This
event is useful if operations are queued and invoked at a later time.
You can handle these events at three different levels in your application:
• Handle them at the component level. Specify event handlers for the fault and result events for the component.
By default, these event handlers are invoked for all service calls.
• For the WebService component only, handle them at the operation level. These event handlers override any event
handler specified at the component level. The HTTPService component does not support multiple operations, so
you use this technique only with the WebService component.
• Handle them at the call level. The send() method returns an AsyncToken object. You can assign event handlers to
the AsyncToken object to define event handlers for a specific service call.

Handling events at the component level

Handle events at the component level by using the fault and result properties of the component to specify the event
handlers, as the following example shows:
<?xml version="1.0"?>
<!-- ds\rpc\RPCIntroExample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script>
<![CDATA[

import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;
import mx.controls.Alert;

public function handleResult(event:ResultEvent):void {

// Handle result by populating the DataGrid control.
// The operation returns an Array containing product ID, name, and price.
myDG.dataProvider=event.result;
}

public function handleFault(event:FaultEvent):void {

// Handle fault.
Alert.show(event.fault.faultString, "Fault");
}
]]>
</mx:Script>

<!-- Define a WebService component and connect to a service destination. -->

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 79
Accessing Server-Side Data with Flex

<mx:WebService
id="adbe_news"
useProxy="true"
destination="ws-catalog"
result="handleResult(event);"
fault="handleFault(event);"/>

<!-- Call the getProducts() operation of the web service.

The operation takes no parameters. -->
<mx:Button click="adbe_news.getProducts();"/>

<!-- Define a DataGrid control to diplay the results of the web service. -->
<mx:DataGrid id="myDG" width="100%" height="100%">
<mx:columns>
<mx:DataGridColumn dataField="productId" headerText="Product Id"/>
<mx:DataGridColumn dataField="name" headerText="Name"/>
<mx:DataGridColumn dataField="price" headerText="Price"/>
</mx:columns>
</mx:DataGrid>

</mx:Application>

In this example, all operations that you invoke through the WebService component use the same event handlers.

Handling events at the operation level for the WebService component

For the WebService component, you can handle events at the operation level. These event handlers override any event
handler specified at the component level. When you do not specify event listeners for an operation, the events are
passed to the component level.
In the following MXML example, the WebService component defines default event handlers, and the operation
specifies its own handlers:
<?xml version="1.0"?>
<!-- ds\rpc\RPCResultFaultMXML.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script>
<![CDATA[
import mx.rpc.soap.SOAPFault;
import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;
import mx.controls.Alert;

public function getProductsResult(event:ResultEvent):void {

// Handle result.
}

public function getProductsFault(event:FaultEvent):void {

// Handle operation fault.
Alert.show(event.fault.faultString, "Error");
}

public function defaultResult(event:ResultEvent):void {

// Handle result.
}

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 80
Accessing Server-Side Data with Flex

public function defaultFault(event:FaultEvent):void {

// Handle service fault.
if (event.fault is SOAPFault) {
var fault:SOAPFault=event.fault as SOAPFault;
var faultElement:XML=fault.element;
// You could use E4X to traverse the raw fault element
// returned in the SOAP envelope.
}
Alert.show(event.fault.faultString, "Error");
}
]]>
</mx:Script>

<mx:WebService id="WeatherService"
destination="ws-catalog"
result="defaultResult(event);"
fault="defaultFault(event);">
<mx:operation name="getProducts"
fault="getProductsFault(event);"
result="getProductsResult(event);">
</mx:operation>
</mx:WebService>

<mx:Button click="WeatherService.getProducts.send();"/>
</mx:Application>

Handling events at the call level

Sometimes, an application requires different event handlers for calls to the same service. For example, a service call
uses one event handler at application startup, and a different handler for calls during application execution.
To define event handlers for a specific service call, you can use the AsyncToken object returned by the send() method.
You then register event handlers on the AsyncToken object, rather than on the component, as the following
ActionScript code shows:
<?xml version="1.0"?>
<!-- ds\rpc\RPCAsynchEventHandler.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script>
<![CDATA[
import mx.rpc.soap.SOAPFault;
import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;
import mx.controls.Alert;
import mx.rpc.AsyncToken;
import mx.rpc.AsyncResponder;

// Define an instance of the AsyncToken class.

public var serviceToken:AsyncToken;
// Call the service, and then
// assign the event handlers to the AsyncToken object.
public function setCustomHandlers():void {
// send() returns an instance of AsyncToken.
serviceToken = WeatherService.getProducts.send();
var asynchRes:AsyncResponder =

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 81
Accessing Server-Side Data with Flex

new AsyncResponder(getProductsResult, getProductsFault);

serviceToken.addResponder(asynchRes);
}

// Use the token argument to pass additional information to the handler.

public function getProductsResult(event:ResultEvent, token:Object = null):void {
// Handle result.
}

// Use the token argument to pass additional information to the handler.

public function getProductsFault(event:FaultEvent, token:Object = null):void {
// Handle operation fault.
Alert.show(event.fault.faultString, "Error");
}

public function defaultResult(event:ResultEvent):void {

// Handle result.
}

public function defaultFault(event:FaultEvent):void {

// Handle service fault.
if (event.fault is SOAPFault) {
var fault:SOAPFault=event.fault as SOAPFault;
var faultElement:XML=fault.element;
// You could use E4X to traverse the raw fault element
// returned in the SOAP envelope.
}
Alert.show(event.fault.faultString, "Error");
}
]]>
</mx:Script>

<mx:WebService id="WeatherService"
destination="ws-catalog"
result="defaultResult(event);"
fault="defaultFault(event);">
<mx:operation name="getProducts"/>
</mx:WebService>

<!-- Call the service using the default event handlers. -->
<mx:Button label="Use Default Handlers" click="WeatherService.getProducts.send();"/>

<!-- Call the service using the custom event handlers. -->
<mx:Button label="Use Custom Handlers" click="setCustomHandlers();"/>

</mx:Application>

Notice that some properties are assigned to the token after the call to the remote service is made. In a multi-threaded
language, there would be a race condition where the result comes back before the token is assigned. This situation is
not a problem in ActionScript because the remote call cannot be initiated until the currently executing code finishes.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 82
Accessing Server-Side Data with Flex

Handling service results

Most service calls return data to the application. The way to access that data depends on which component you use:
• HTTPService
Access the data by using the HTTPService.lastResult property, or in a result event by using the
ResultEvent.result property.

• WebService and RemoteObject

The WebService and RemoteObject components create an Operation object for each operation supported by the
associated web service. Access the data by using the Operation.lastResult property for the specific operation,
or in a result event by using the ResultEvent.result property.
By default, the resultFormat property value of the HTTPService component and of the Operation class is object,
and the data that is returned is represented as a simple tree of ActionScript objects. Flex interprets the XML data
that a web service or HTTP service returns to appropriately represent base types, such as String, Number, Boolean,
and Date. To work with strongly typed objects, populate those objects using the object tree that Flex creates.
WebService and HTTPService components both return anonymous Objects and Arrays that are complex types. If
makeObjectsBindable is true, which it is by default, Objects are wrapped in mx.utils.ObjectProxy instances and
Arrays are wrapped in mx.collections.ArrayCollection instances. RemoteObject components return strongly typed
objects.
Note: ColdFusion is not case-sensitive, so it internally represents all of its data in uppercase. Keep in mind case
sensitivity when consuming a ColdFusion web service.
When consuming data from a web service invocation, you can create an instance of a specific class instead of an
Object or an Array. If you want Flex to create an instance of a specific class, use an mx.rpc.xml.SchemaTypeRegistry
object and register a QName object with a corresponding ActionScript class. For more information, see
“Customizing web service type mapping” on page 52.

Processing results in an event handler

Because calls to a remote service are asynchronous, you typically use events to signal that the service call has completed.
A result event indicates that the result is available. The event object passed to the event handler is of type ResultEvent.
Use the result property of the ResultEvent object to access the data returned by the service call, as the following
example shows:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 83
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- ds\rpc\RPCResultEvent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script>
<![CDATA[
import mx.collections.ArrayCollection;

import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;
import mx.controls.Alert;

// Handle result by populating the DataGrid control.

// The operation returns an Array containing product ID, name, and price.
public function handleResult(event:ResultEvent):void {
// Make sure that the result can be cast to the correct type.
if (event.result is ArrayCollection)
{
// Cast the result to the correct type.
myDG.dataProvider=event.result as ArrayCollection;
}
else
myDG.dataProvider = null;
}

public function handleFault(event:FaultEvent):void {

// Handle fault.
Alert.show(event.fault.faultString, "Fault");
}
]]>
</mx:Script>

<!-- Define a WebService component and connect to a service destination. -->

<mx:WebService
id="adbe_news"
useProxy="true"
destination="ws-catalog"
result="handleResult(event);"
fault="handleFault(event);"/>

<!-- Call the getProducts() operation of the web service.

The operation takes no parameters. -->
<mx:Button click="adbe_news.getProducts();"/>

<!-- Define a DataGrid control to diplay the reults of the web service. -->
<mx:DataGrid id="myDG" width="100%" height="100%">
<mx:columns>
<mx:DataGridColumn dataField="productId" headerText="Product Id"/>
<mx:DataGridColumn dataField="name" headerText="Name"/>
<mx:DataGridColumn dataField="price" headerText="Price"/>
</mx:columns>
</mx:DataGrid>

</mx:Application>

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 84
Accessing Server-Side Data with Flex

The data type of the ResultEvent.result property is Object. Therefore, the event handler inspects the
ResultEvent.result property to make sure that it can be cast to the required type. In this example, you want to cast
it to ArrayCollection so that you can use it as the data provider for the DataGrid control. If the result cannot be cast to
the ArrayCollection, set the data provider to null.

Handling results as XML with the E4X result format

You can set the resultFormat property value of HTTPService components and WebService components to e4x to
specify that the returned data is of type XML. Using a resultFormat of e4x is the preferred way to work with XML.
You can also set the resultFormat property to xml to specify that the returned data is of type flash.xml.XMLNode,
which is a legacy object for working with XML. Also, you can set the resultFormat property of HTTPService
components to flashvars or text to create results as ActionScript objects that contain name-value pairs or as raw
text, respectively. For more information, see Adobe LiveCycle ES ActionScript Reference.
When working with web service results that contain .NET DataSets or DataTables, it is best to set the resultFormat
property to object to take advantage of specialized result handling for these data types. For more information, see
“Handling web service results that contain .NET DataSets or DataTables” on page 87.
Note: If you want to use E4X syntax on service results, set the resultFormat property of your HTTPService or
WebService component to e4x. The default value is object.
When you set the resultFormat property of a WebService operation to e4x, you sometimes have to handle
namespace information contained in the body of the SOAP envelope that the web service returns. The following
example shows part of a SOAP body that contains namespace information. This data was returned by a web service
that retrieves stock quotes. The namespace information is in boldface text.
<soap:Body>
<GetQuoteResponse xmlns="http://ws.invesbot.com/">
<GetQuoteResult>
<StockQuote xmlns="">
<Symbol>ADBE</Symbol>
<Company>ADOBE SYSTEMS INC</Company>
<Price>&lt;big&gt;&lt;b&gt;35.90&lt;/b&gt;&lt;/big&gt;</Price>
</StockQuote>
</GetQuoteResult>
</GetQuoteResponse>
...
</soap:Body>

This soap:Body tag contains namespace information. Therefore, if you set the resultFormat property of the
WebService operation to e4x, create a namespace object for the http://ws.invesbot.com/namespace. The following
example shows an application that does that:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 85
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- ds\rpc\WebServiceE4XResult1.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns="*">

<mx:Script>
<![CDATA[
import mx.controls.Alert;

private namespace invesbot = "http://ws.invesbot.com/";

use namespace invesbot;
]]>
</mx:Script>

<mx:WebService
id="WS"
destination="stockservice" useProxy="true"
fault="Alert.show(event.fault.faultString, 'Error');">
<mx:operation name="GetQuote" resultFormat="e4x">
<mx:request>
<symbol>ADBE</symbol>
</mx:request>
</mx:operation>
</mx:WebService>

<mx:HBox>
<mx:Button label="Get Quote" click="WS.GetQuote.send();"/>
<mx:Text text="{WS.GetQuote.lastResult.GetQuoteResult.StockQuote.Price}"/>
</mx:HBox>
</mx:Application>

Optionally, you can create a variable for a namespace and access it in a binding to the service result, as the following
example shows:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 86
Accessing Server-Side Data with Flex

<?xml version="1.0"?>
<!-- ds\rpc\WebServiceE4XResult2.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns="*">

<mx:Script>
<![CDATA[
import mx.controls.Alert;

public var invesbot:Namespace =

new Namespace("http://ws.invesbot.com/");
]]>
</mx:Script>

<mx:WebService
id="WS"
destination="stockservice" useProxy="true"
fault="Alert.show(event.fault.faultString, 'Error');">
<mx:operation name="GetQuote" resultFormat="e4x">
<mx:request>
<symbol>ADBE</symbol>
</mx:request>
</mx:operation>
</mx:WebService>

<mx:HBox>
<mx:Button label="Get Quote" click="WS.GetQuote.send()"/>
<mx:Text text="{WS.GetQuote.lastResult.invesbot::GetQuoteResult.StockQuote.Price}"/>
</mx:HBox>
</mx:Application>

You use E4X syntax to access elements and attributes of the XML that is returned in a lastResult object. You use
different syntax, depending on whether there is a namespace or namespaces declared in the XML.

No namespace specified
The following example shows how to get an element or attribute value when no namespace is specified on the element
or attribute:
var attributes:XMLList = XML(event.result).Description.value;

The previous code returns xxx for the following XML document:
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<Description>
<value>xxx</value>
</Description>
</RDF>

Any namespace specified

The following example shows how to get an element or attribute value when any namespace is specified on the element
or attribute:
var attributes:XMLList = XML(event.result).*::Description.*::value;

The previous code returns xxx for either one of the following XML documents:
XML document one:

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 87
Accessing Server-Side Data with Flex

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description>
<rdf:value>xxx</rdf:value>
</rdf:Description>
</rdf:RDF>

XML document two:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:cm="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<cm:Description>
<rdf:value>xxx</rdf:value>
</cm:Description>
</rdf:RDF>

Specific namespace specified

The following example shows how to get an element or attribute value when the declared rdf namespace is specified
on the element or attribute:
var rdf:Namespace = new Namespace("http://www.w3.org/1999/02/22-rdf-syntax-ns#");
var attributes:XMLList = XML(event.result).rdf::Description.rdf::value;

The previous code returns xxx for the following XML document:
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description>
<rdf:value>xxx</rdf:value>
<nsX:value>yyy</nsX:value>
</rdf:Description>
</rdf:RDF>

The following example shows an alternate way to get an element or attribute value when the declared rdf namespace
is specified on the element or attribute:
namespace rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
use namespace rdf;
var attributes:XMLList = XML(event.result).rdf::Description.rdf::value;

The previous code also returns xxx for the following XML document:
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description>
<rdf:value>xxx</rdf:value>
</rdf:Description>
</rdf:RDF>

Handling web service results that contain .NET DataSets or DataTables

Web services written with the Microsoft .NET Framework can return special .NET DataSet or DataTable objects to the
client. A .NET web service provides a very basic WSDL document without information about the type of data that it
manipulates. When the web service returns a DataSet or a DataTable, data type information is embedded in an XML
Schema element in the SOAP message, which specifies how the rest of the message should be processed. To best handle
results from this type of web service, you set the resultFormat property of a Flex WebService operation to object.
You can optionally set the WebService operation’s resultFormat property to e4x, but the XML and e4x formats are
inconvenient because you must navigate through the unusual structure of the response and implement workarounds
if you want to bind the data, for example, to a DataGrid control.

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 88
Accessing Server-Side Data with Flex

When you set the resultFormat property of a Flex WebService operation to object, a DataTable or DataSet returned
from a .NET webservice is automatically converted to an object with a Tables property, which contains a map of one
or more dataTable objects. Each dataTable object from the Tables map contains two properties: Columns and Rows.
The Rows property contains the data. The event.result object gets the following properties corresponding to DataSet
and DataTable properties in .NET. Arrays of DataSets or DataTables have the same structures described here, but are
nested in a top-level Array on the result object.

Property Description

result.Tables Map of table names to objects that contain table data.

result.Tables["someTable"].Columns Array of column names in the order specified in the DataSet or

DataTable schema for the table.

result.Tables["someTable"].Rows Array of objects that represent the data of each table row. For
example, {columnName1:value, columnName2:value,
columnName3:value}.

The following MXML application populates a DataGrid control with DataTable data returned from a .NET web
service.
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns="*" xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
<mx:WebService
id="nwCL"
wsdl="http://localhost/data/CustomerList.asmx?wsdl"
result="onResult(event)"
fault="onFault(event)" />
<mx:Button label="Get Single DataTable" click="nwCL.getSingleDataTable()"/>
<mx:Button label="Get MultiTable DataSet" click="nwCL.getMultiTableDataSet()"/>
<mx:Panel id="dataPanel" width="100%" height="100%" title="Data Tables"/>

<mx:Script>
<![CDATA[
import mx.controls.Alert;
import mx.controls.DataGrid;
import mx.rpc.events.FaultEvent;
import mx.rpc.events.ResultEvent;

private function onResult(event:ResultEvent):void {

// A DataTable or DataSet returned from a .NET webservice is
// automatically converted to an object with a "Tables" property,
// which contains a map of one or more dataTables.
if (event.result.Tables != null)
{
// clean up panel from previous calls.
dataPanel.removeAllChildren();

for each (var table:Object in event.result.Tables)

{
displayTable(table);
}

// Alternatively, if a table's name is known beforehand,

// it can be accessed using this syntax:
var namedTable:Object = event.result.Tables.Customers;

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 89
Accessing Server-Side Data with Flex

//displayTable(namedTable);
}
}

private function displayTable(tbl:Object):void {

var dg:DataGrid = new DataGrid();
dataPanel.addChild(dg);
// Each table object from the "Tables" map contains two properties:
// "Columns" and "Rows". "Rows" is where the data is, so we can set
// that as the dataProvider for a DataGrid.
dg.dataProvider = tbl.Rows;
}

private function onFault(event:FaultEvent):void {

Alert.show(event.fault.toString());
}
]]>
</mx:Script>

</mx:Application>

The following example shows the .NET C# class that is the backend web service implementation called by the Flex
application; this class uses the Microsoft SQL Server Northwind sample database:
:
<%@ WebService Language="C#" Class="CustomerList" %>
using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Web.Services.Description;
using System.Data;
using System.Data.SqlClient;
using System;

public class CustomerList : WebService {

[WebMethod]
public DataTable getSingleDataTable() {
string cnStr = "[Your_Database_Connection_String]";
string query = "SELECT TOP 10 * FROM Customers";
SqlConnection cn = new SqlConnection(cnStr);
cn.Open();
SqlDataAdapter adpt = new SqlDataAdapter(new SqlCommand(query, cn));
DataTable dt = new DataTable("Customers");

adpt.Fill(dt);
return dt;
}

Prerelease Adobe Confidential - 01/06/2009

 CREATING DATA-DRIVEN APPLICATIONS WITH FLEX 4 90
Accessing Server-Side Data with Flex

[WebMethod]
public DataSet getMultiTableDataSet() {
string cnStr = "[Your_Database_Connection_String]";
string query1 = "SELECT TOP 10 CustomerID, CompanyName FROM Customers";
string query2 = "SELECT TOP 10 OrderID, CustomerID, ShipCity,
ShipCountry FROM Orders";
SqlConnection cn = new SqlConnection(cnStr);
cn.Open();

SqlDataAdapter adpt = new SqlDataAdapter(new SqlCommand(query1, cn));

DataSet ds = new DataSet("TwoTableDataSet");
adpt.Fill(ds, "Customers");

adpt.SelectCommand = new SqlCommand(query2, cn);

adpt.Fill(ds, "Orders");

return ds;
}
}

Prerelease Adobe Confidential - 01/06/2009

 91

Index
A W
argument binding 70 web services
RPC-oriented, document-oriented 41
B SOAP headers 41
binding WSDL 40
RPC components, parameter 70 WebService components
additional features 35
C
crossdomain.xml file 36

D
data
results, data service 82
types, converting 59, 62

E
Enterprise JavaBeans 58

J
Java Naming and Directory Interface 58
JNDI, accessing 58

M
mx.rpc.events.InvokeEvent event 27, 36, 54

N
namespaces
handling in RPC components 84

P
parameter binding 70

R
RemoteObject components
stateful objects 58

S
serialization
ActionScript to Java 59
Java to ActionScript 62
legacy AMF type serialization 63
SOAP 35

Prerelease Adobe Confidential - 01/06/2009