Macromedia FLASH REMOTING MX User Manual
Using Flash Remoting for Flash MX 2004 ActionScript 2.0
Trademarks
Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain, Authorware,
Authorware Star, Backstage, Bright Tiger, Clustercats, ColdFusion, Contribute, Design In Motion, Director, Dream Templates,
Dreamweaver, Drumbeat 2000, EDJE, EJIPT, Extreme 3D, Fireworks, Flash, Flash Lite, Flex, Fontographer, FreeHand,
Generator, HomeSite, JFusion, JRun, Kawa, Know Your Site, Knowledge Objects, Knowledge Stream, Knowledge Track,
LikeMinds, Lingo, Live Effects, MacRecorder Logo and Design, Macromedia, Macromedia Action!, Macromedia Breeze,
Macromedia Flash, Macromedia M Logo and Design, Macromedia Spectra, Macromedia xRes Logo and Design, MacroModel,
Made with Macromedia, Made with Macromedia Logo and Design, MAGIC Logo and Design, Mediamaker, Movie Critic,
Open Sesame!, Roundtrip, Roundtrip HTML, Shockwave, Sitespring, SoundEdit, Titlemaker, UltraDev, Web Design 101, what
the web can be, and Xtra are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United
States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned
within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be
registered in certain jurisdictions including internationally.
Third-Party Information
This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not
responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your
own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia
endorses or accepts any responsibility for the content on those third-party sites.
Apple Disclaimer
APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE
ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY
PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES.
THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC
LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO
STATE.
Copyright © 2004 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced,
translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of
Macromedia, Inc.
Acknowledgments
Project Management: Erick Vera
Writing: Robert Berry
Editing: Barbara Milligan, Antonio Padial, Lisa Stanziano
Production Management: Patrice O’Neill
Media Design and Production: Adam Barnett and John Francis
First Edition: June 2004
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103
CONTENTS
INTRODUCTION: About Flash Remoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Who should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
About Flash Remoting documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
What’s new in Flash Remoting for Flash MX 2004 ActionScript 2.0. . . . . . . . . . . 10
Developer resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Contacting Macromedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
CHAPTER 1: Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
About Flash Remoting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Flash Remoting data flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Understanding the Flash Remoting service adapters . . . . . . . . . . . . . . . . . . . . . 16
Building Flash applications with Flash Remoting . . . . . . . . . . . . . . . . . . . . . . . . . 16
Understanding the Flash Remoting development environment. . . . . . . . . . . . . 16
Using Flash Remoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Migrating existing applications to Flash Remoting for Flash MX 2004
ActionScript 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Making the minimum changes to your application for ActionScript 2.0. . . . . . 22
Taking full advantage of Flash Remoting for Flash MX 2004 ActionScript 2.0. 23
Migrating the DataGrid application to Flash Remoting for Flash MX 2004
ActionScript 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Example: migrating the DataGrid application . . . . . . . . . . . . . . . . . . . . . . . . . 24
CHAPTER 2: Using Flash Remoting ActionScript . . . . . . . . . . . . . . . . . . . . . . . . 29
Flash Remoting application structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Flash Remoting ActionScript classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Properties and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Importing Flash Remoting ActionScript classes . . . . . . . . . . . . . . . . . . . . . . . . 35
Configuring Flash Remoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Establishing the Flash Remoting gateway connection . . . . . . . . . . . . . . . . . . . . 37
Specifying a service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Authenticating a user to the application server . . . . . . . . . . . . . . . . . . . . . . . . . 40
Calling service functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Specifying functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Calling functions using named arguments in ColdFusion. . . . . . . . . . . . . . . . . 43
3
Handling service results and errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Using the RelayResponder object for a service . . . . . . . . . . . . . . . . . . . . . . . . . 44
Using PendingCall and RelayResponder objects for a specific service function . 45
Using the ResultEvent class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Using the FaultEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Using the Flash Remoting ActionScript API in the
CustomerInfoExampleAPI application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
onReveal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
updateDetails(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
refreshCustomerData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
onCustGrid_Change() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
onCustCat_Change() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
onCategoryData(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
onCustomerData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
onCustomerFault(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
onCategoryFault() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
CHAPTER 3: Using the RemotingConnector component
(Flash Professional only). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
RemotingConnector parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Creating an instance of the RemotingConnector component . . . . . . . . . . . . . . 56
Using the RemotingConnector in the CustomerInfoExampleCon application. . . . 57
onReveal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
updateDetails(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
onCustGrid_Change() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
onCustomerData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
onCategoryData(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
onCustomerDataFault() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
onCategoryDataFault(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
CHAPTER 4: Using Flash Remoting Data in ActionScript . . . . . . . . . . . . . . . . . . 63
About Flash Remoting and data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Understanding Action Message Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Converting from ActionScript to application server data types . . . . . . . . . . . . . . . 65
Converting from application server data types to ActionScript . . . . . . . . . . . . . . . 67
ColdFusion to ActionScript data conversion issues . . . . . . . . . . . . . . . . . . . . . . . . 69
About working with objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Working with ActionScript typed objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Working withJava serializable objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
About working with RecordSet objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
About record sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
RecordSet methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using RecordSet methods and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Delivering RecordSet data to Flash applications in ColdFusion MX . . . . . . . . . 81
Using Flash UI components with RecordSet objects . . . . . . . . . . . . . . . . . . . . . 83
About working with XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4 Contents
CHAPTER 5: The NetConnection Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Using the NetConnection Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Enabling debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Disabling debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
NetConnection events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Specific event information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Common event information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Client event messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Application server event messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Flash Communication Server events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Using the NetConnection Debugger in ActionScript. . . . . . . . . . . . . . . . . . . . . . . 94
Using the Netdebug.initialize() method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Using the NetDebug.trace() method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Using connection-specific debugging methods . . . . . . . . . . . . . . . . . . . . . . . . . 95
Configuring debugger output in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . 96
CHAPTER 6: Using Flash Remoting with ColdFusion MX . . . . . . . . . . . . . . . . . . 97
Using Flash Remoting with ColdFusion pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Determining the Flash service name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Using the Flash scope to pass parameters to ColdFusion pages . . . . . . . . . . . . . 98
Accessing ActionScript objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Using Flash Remoting with ColdFusion components . . . . . . . . . . . . . . . . . . . . . 105
Determining the Flash service name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Returning results to ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Passing parameters to ColdFusion components. . . . . . . . . . . . . . . . . . . . . . . . 106
Accessing ActionScript objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Using component metadata with the Flash Remoting service . . . . . . . . . . . . . 109
Using Flash Remoting with server-side ActionScript . . . . . . . . . . . . . . . . . . . . . . 111
Using CF.http() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Using CF.query() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Calling web services from Flash Remoting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Invoking web service methods using Flash Remoting . . . . . . . . . . . . . . . . . . . 115
Securing access to ColdFusion from Flash Remoting. . . . . . . . . . . . . . . . . . . . . . 116
Assigning security roles to component functions. . . . . . . . . . . . . . . . . . . . . . . 117
Handling errors with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
CHAPTER 7: Using Flash Remoting for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
About Flash Remoting for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
How Flash Remoting for Java works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Where Flash Remoting fits into the Java application architecture . . . . . . . . . . 120
Calling Java classes or JavaBeans from ActionScript. . . . . . . . . . . . . . . . . . . . . . . 121
Making a Java class or JavaBean available to Flash Remoting . . . . . . . . . . . . . 121
Getting a reference to a Java class or JavaBean in ActionScript . . . . . . . . . . . . 122
Invoking Java methods in ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Looking at a Flash application that calls a JavaBean . . . . . . . . . . . . . . . . . . . . 123
Contents 5
Calling Enterprise JavaBeans (EJBs) from Flash. . . . . . . . . . . . . . . . . . . . . . . . . . 128
Getting a reference to an EJBHome object in ActionScript. . . . . . . . . . . . . . . 128
Invoking EJB methods in ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Looking at a Flash application that calls an EJB . . . . . . . . . . . . . . . . . . . . . . . 129
Calling servlets and JSPs from Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Coding a servlet to use with Flash Remoting . . . . . . . . . . . . . . . . . . . . . . . . . 132
Getting a reference to a web application in ActionScript. . . . . . . . . . . . . . . . . 132
Calling a servlet or JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Calling JMX MBeans from Flash (JRun only) . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Getting a reference to an MBean in ActionScript . . . . . . . . . . . . . . . . . . . . . . 135
Invoking MBean methods in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Calling server-side ActionScript from Flash (JRun only) . . . . . . . . . . . . . . . . . . . 135
Getting a reference to a server-side ActionScript file . . . . . . . . . . . . . . . . . . . . 136
Invoking server-side ActionScript functions . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Handling function results in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Using Flash Remoting with JRun security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Looking at the ActionScript authentication code . . . . . . . . . . . . . . . . . . . . . . 139
Looking at the JRun security settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Passing XML objects between Flash and Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Sending an ActionScript XML object to Java . . . . . . . . . . . . . . . . . . . . . . . . . 140
Returning an XML object from Java to Flash . . . . . . . . . . . . . . . . . . . . . . . . . 141
Viewing Flash Remoting log entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
CHAPTER 8: Using Flash Remoting for Microsoft .NET. . . . . . . . . . . . . . . . . . . 143
Flash Remoting for Microsoft .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Where Flash Remoting fits into the Microsoft .NET framework . . . . . . . . . . 144
Understanding the Flash Remoting for Microsoft .NET directory structure . . 145
Setting up a Flash Remoting ASP.NET application. . . . . . . . . . . . . . . . . . . . . 146
Calling ASP.NET pages from Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Making an ASP.NET page available to Flash Remoting . . . . . . . . . . . . . . . . . 147
Getting a reference to an ASPX-based service in ActionScript. . . . . . . . . . . . . 147
Invoking ASPX pages in ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Using the Flash Remoting custom server control in ASPX pages. . . . . . . . . . . 149
Using the Flash Remoting namespace in code-behind files . . . . . . . . . . . . . . . 150
Using ASP.NET state management with Flash Remoting . . . . . . . . . . . . . . . . 151
Using ASP.NET exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Using ADO.NET objects with Flash Remoting. . . . . . . . . . . . . . . . . . . . . . . . . . 153
Displaying a RecordSet object in Flash with ActionScript . . . . . . . . . . . . . . . . . . 155
Calling web services from Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Invoking web service methods using Flash Remoting . . . . . . . . . . . . . . . . . . . 157
Invoking a remote web service from Flash. . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Calling ASP.NET assemblies from Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Calling assemblies from Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Returning an ActionScript object from an assembly . . . . . . . . . . . . . . . . . . . . 160
Viewing Flash Remoting log entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6 Contents
APPENDIX A: Using NetServices and Connection Classes . . . . . . . . . . . . . . . . 163
Creating a gateway connection using the NetServices object . . . . . . . . . . . . . . . . 163
Specifying the gateway in the NetServices
createGatewayConnection() method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Using the NetServices setDefaultGatewayUrl() method . . . . . . . . . . . . . . . . . 164
Authenticating a user to the application server . . . . . . . . . . . . . . . . . . . . . . . . 165
Creating the service object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Handling results for a Connection object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Directing all results for a service to a single responder object . . . . . . . . . . . . . 167
Directing results for a service to specific responder objects . . . . . . . . . . . . . . . 168
Handling errors for a Connection object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
The error object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Error-handling hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Error-handling strategies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Contents 7
8 Contents
INTRODUCTION
About Flash Remoting
Macromedia Flash Remoting for Flash MX 2004 ActionScript 2.0 provides a communications
channel between Macromedia Flash applications and a wide range of business logic and data from
ColdFusion, Microsoft
services. Using Flash Remoting is intended for Macromedia Flash and application server developers
who want to build Rich Internet Applications.
This chapter contains the following sections:
• “Who should read this book” on page 9
• “About Flash Remoting documentation” on page 9
• “What’s new in Flash Remoting for Flash MX 2004 ActionScript 2.0” on page 10
• “Developer resources” on page 11
• “Contacting Macromedia” on page 12
Who should read this book
This book is intended for developers who have previous experience with Flash MX or
Flash MX 2004 and an application server, including Macromedia ColdFusion MX, Java,
or Microsoft .NET.
If you are not familiar with Macromedia Flash MX or Macromedia Flash MX 2004, read the
documentation set. If you are not familiar with application server development, read the
documentation included with your server.
®
.NET, Java, and Simple Object Access Protocol (SOAP)-based web
About Flash Remoting documentation
The Macromedia Flash Remoting documentation is designed to provide support for the complete
spectrum of participants. Organized to help you quickly locate the information that you need, the
Flash Remoting documentation is provided in the Flash Help system. From the Help menu you
can open the Help panel or press F1 as a shortcut to access Flash Help. Then select Using Flash
Remoting or the Flash Remoting ActionScript Dictionary, depending on the information that
you are seeking.
Flash Remoting documentation is available in Acrobat format (PDF) on the Flash Remoting
product CD-ROM.
9
Use the following sources to help you understand and use the tools and technologies that Flash
Remoting encompasses.
• Flash MX 2004 Help is the comprehensive information source for all Flash MX 2004 features.
To open Flash MX 2004 Help in your browser, either select Help > Using Flash, or click the
Help button in any dialog box, or the question mark icon in inspectors, windows, and panels.
• The ActionScript Dictionary describes the syntax and use of ActionScript elements in
Macromedia Flash MX 2004 and Macromedia Flash MX Professional 2004. To access the
ActionScript Dictionary in Flash MX 2004, select Help > ActionScript Dictionary from the
Help menu.
• ColdFusion MX documentation is carefully crafted to assist you in every facet of ColdFusion
use. To access the ColdFusion MX documentation, activate the ColdFusion MX Administrator
and click the Documentation link.
For information on other application servers, see the documentation for those products.
What’s new in Flash Remoting for Flash MX 2004 ActionScript 2.0
Flash Remoting for Flash MX 2004 ActionScript 2.0 consists of the following two principal
features:
• The Remoting Connector component
The RemotingConnector component is a new component that allows you to work directly
with the new data binding features in Flash MX 2004 Professional. Simply drag the
RemotingConnector onto the Stage and use the Component inspector to set up schema and
bindings. In addition, the RemotingConnector component provides a simple API consistent
with other connectors found in Flash MX 2004 Professional.
For more information on using the Remoting Connector, see Chapter 2, “Using Flash
Remoting ActionScript,” on page 29.
• ActionScript 2.0 API
The Flash Remoting ActionScript API has been updated to comply with ActionScript 2.0. The
ActionScript 2.0 version of the API consists of the following significant features:
■ Enforcement of strict data typing, which requires you to declare the data types of variables
and prohibits you from assigning different types of data to them.
■ Enforcement of case sensitivity, which means that myvar and myVar are two different
variables, though they were considered the same variable with different spellings in
ActionScript 1.0.
■ A new Service class, which allows you to create a gateway connection and at the same time
obtain a reference to a service and its methods. It includes the
returns the connection and also allows you to set credentials for authorization on the remote
server.
Note: The NetServices class is still supported but has been deprecated in favor of the new
Service and Connection classes
connection property, which
10 Introduction: About Flash Remoting
■ A new Connection class that helps you create and use Flash Remoting connections.
Note: The Connection class supersedes the former NetConnection class.
■ A new PendingCall object returned on each call to a service method that is invoked using
the Service object. The PendingCall object contains the
to specify the methods to handle the results of the service call
■ A new RelayResponder class, which specifies the methods to which the result and fault
responder property, which you use
.
outcomes of a service call are relayed.
■ A RecordSet object that contains new properties (columnNames, items, and length), new
methods (
getLocalLength(), getRemoteLength(), isEmpty(), and sortItems()), and the new
modelChanged event.
clear(), contains(), editField(), getEditingData(), getIterator(),
For more information on the ActionScript 2.0 Flash Remoting API, see Flash Remoting
ActionScript Dictionary Help.
If you are migrating existing applications to Flash Remoting for Flash MX 2004 ActionScript 2.0,
see “Migrating existing applications to Flash Remoting for Flash MX 2004 ActionScript 2.0”
on page 22.
Developer resources
Macromedia is committed to setting the standard for customer support in developer education,
documentation, technical support, and professional services. The Macromedia website is designed
to give you quick access to the entire range of online resources. The following table shows the
locations of these resources:
Resource Description URL
Macromedia
website
Information on
Flash Remoting
Macromedia
Flash Remoting
Support Center
Flash Remoting
Online Forum
Installation
support
Training Information about classes, on-site
General information about
Macromedia products and services.
Detailed product information on
Flash Remoting and related topics.
Professional support programs that
Macromedia offers.
Access to experienced Flash and
application server developers
through participation in the Online
Forums, where you can post
messages and read replies on many
subjects relating to Flash Remoting.
Support for installation-related
issues for all Macromedia products.
training, and online courses offered
by Macromedia.
www.macromedia.com
www.macromedia.com/go/flashremoting
www.macromedia.com/go/
flashremoting_support
www.macromedia.com/go/flash_forum
www.macromedia.com/support/email/
isupport
www.macromedia.com/go/flash_training
Developer resources 11
Resource Description URL
Developer
resources
Macromedia
Alliance
All the resources that you need to
stay on the cutting edge of Flash
and application server development,
including online discussion groups,
Knowledge Base, technical papers,
and more.
Connection with the growing
network of solution providers,
application developers, resellers,
and hosting services creating
solutions with Flash Remoting.
www.macromedia.com/go/devnet
www.macromedia.com/go/partners
One of the best ways to solve particular programming problems is to tap into the vast expertise of
the Flash and application server developer communities on the Macromedia Online Forums at
www.macromedia.com/go/flash_forum. Other developers on the forum can help you figure out
how to do just about anything with Flash Remoting. The search facility can also help you search
messages from the previous 12 months, or beyond, allowing you to learn how others have solved a
problem that you might be facing.
Contacting Macromedia
Corporate headquarters Macromedia, Inc.
600 Townsend Street
San Francisco, CA 94103
Tel: 415.252.2000
Fax: 415.626.0554
Website: www.macromedia.com
Technical support Macromedia offers a range of telephone and web-based support options.
Sales Toll Free: 888.939.2545
Go to www.macromedia.com/go/flashremoting_support for a complete
description of technical support services.
You can post comments to the Flash Remoting Support Forum
(www.macromedia.com/go/flash_forum) at any time.
Tel: 617.219.2100
Fax: 617.219.2101
E-mail: sales@macromedia.com
12 Introduction: About Flash Remoting
CHAPTER 1
Getting Started
Macromedia Flash Remoting for Flash MX 2004 ActionScript 2.0 is an application server
gateway that provides a network communications channel between Flash applications and remote
services. In this chapter, you learn the basics of Flash Remoting, including the Flash Remoting
architecture and how to build a Hello World Flash Remoting application. If you already use Flash
Remoting, this chapter explains the requirements to migrate an existing application to Flash
Remoting for Flash MX 2004 ActionScript 2.0.
This section contains the following sections:
• “About Flash Remoting” on page 13
• “Using Flash Remoting” on page 17
• “Building Flash applications with Flash Remoting” on page 16
• “Migrating existing applications to Flash Remoting for Flash MX 2004 ActionScript 2.0”
on page 22
About Flash Remoting
Macromedia Flash Remoting is an application server gateway that provides a network
communications channel between Flash applications and remote services. Remote services consist
of application server technologies, such as JavaBeans, a Macromedia ColdFusion component or
page, an ASP.NET page, or a web service. Service functions represent a reference to a specific
remote service from ActionScript in a Flash application.
When compared to other techniques for connecting Flash applications to external data providers,
such as HTTP functions like
Flash Remoting provides the following advantages:
getURL and loadVariables and XML functions like XMLSocket,
• Ease of use Flash Remoting offers automatic data type conversion from native remote
service code, such as Java, CFML, and C#, to ActionScript and back again. Also, Flash
Remoting automatically performs logging, debugging, and security integration.
• Performance Flash Remoting serializes messages between Flash applications and remote
services using the Action Message Format (AMF is a binary format modeled on the Simple
Object Access Protocol (SOAP) format). Using AMF, Flash Remoting encodes data types as
they travel between the Flash application and the remote service over HTTP.
13
• Extensibility Flash Remoting is designed to integrate with established application design
patterns and best practices to build well-designed Flash applications.
When compared to traditional HTML-based browser applications, Flash applications provide
unique abilities to create dynamic and sophisticated user interactions, including the following:
• Macromedia Flash Player runtime to execute code, transmit data, and invoke remote services
• Separation of client-side presentation logic from the server-side application logic
• Efficient use of bandwidth provided by the AMF protocol
• Easy deployment on multiple platforms and devices
On the server side, Flash Remoting runs as a servlet in Java application servers, an assembly in
.NET servers, and a native service in ColdFusion MX. Depending on the application server
platform, Flash Remoting on the server contains a series of filters that perform logging, error
handling, and security authentication, as well as automatically mapping the service function
request to the appropriate server technology.
Using Flash Remoting, you can build sophisticated Flash applications, such as a message board,
shopping cart, or product catalog. The following figure depicts a simplified representation of the
Flash Remoting architecture:
Flash Remoting data flow
You typically initiate a service request by making a choice that requires Flash to request data from
the server. For example, a sports fan might ask to see what seats are available in a particular section
of an arena. The Flash Player uses the Action Message Format (AMF), to send the request over
HTTP to Flash Remoting. Flash Remoting receives the service function request and dispatches it
to the appropriate application server or web service call.
14 Chapter 1: Getting Started
Once the application server or web service satisfies the service request, it returns the result to Flash
Remoting, which in turn encapsulates the data in an ActionScript object, and returns it as an
AMF message to the Flash application. In this example, the available seats are returned as a record
set that lists the section, row, seat, and ticket price for each of the available seats.
The Flash Remoting architecture facilitates the flow of messages between the client and server
in a way that conforms to established design patterns and frameworks such as the
model-view-controller (MVC) architecture. The following figure depicts the MVC architecture
in the context of Flash Remoting:
In the MVC architecture, the model, view, and controller have the following roles:
• Model The model represents the data of an application and the processing of that data and
other logic. In a web application, this typically consists of the application server program and
the database.
• View The view represents the user interface, which usually consists of user controls and
information display.
• Controller The controller represents the logic that handles user input and changes the model
or view accordingly. Depending on your application design, the controller can be located on
the client, the server, or a combination of both. To minimize the amount of network traffic
and to take advantage of the Flash runtime, Flash Remoting implements the controller
in Flash.
Flash Remoting MX enables the separation of the controller from the model by providing a
communication channel between Flash applications and application servers or web services. By
encapsulating the data in an ActionScript object, Flash Remoting reduces the number of service
requests necessary to retrieve smaller pieces of data.
About Flash Remoting 15
For more information about using software design patterns with Flash Remoting, see Software
Design Patterns for Flash Remoting on the Macromedia website at www.macromedia.com/
devnet/mx/flashremoting/articles/facades.html.
Understanding the Flash Remoting service adapters
Flash Remoting automatically maps incoming requests to the appropriate service adapters, each of
which provide a direct connection to a specific application server technology. When an HTTP
request arrives at the server and contains AMF, Flash Remoting maps the request to the
appropriate adapter by name. To avoid naming conflicts, you specify the directory structure, fully
qualified class or package name, or Web Service Description Language (WSDL) URL of the web
service in ActionScript.
Building Flash applications with Flash Remoting
Flash applications that use Flash Remoting resemble other client-server development platforms,
including traditional HTML-based web applications. For example, Flash applications usually
appear in the context of a browser window, much like HTML pages. In addition, Flash
applications can contain controls for displaying text and graphics, gathering user input, and
communicating with a remote server, much like HTML.
Understanding the Flash Remoting development environment
Because Flash Remoting connects two distinct and separate runtime environments, you build
Flash Remoting applications in two programming languages: ActionScript and the programming
language of your application server. Therefore, building Flash applications with Flash Remoting
demands knowledge of at least two different development environments:
• Flash To create Flash applications that use Flash Remoting, you use the Flash authoring
environment to design the user interface and write the client-side ActionScript.
• An application server tool For ColdFusion, Java, or .NET development, you typically use a
text editor or an integrated development environment (IDE) that supports the associated
programming languages and APIs. Macromedia Dreamweaver MX 2004 supports ColdFusion,
J S P, a n d A S P. N E T d e v e l o p m e n t .
Note: For Java or .NET development, you need a Java or .NET compiler to create executable
code.
Because of the separation between the client and server environments, you might develop Flash
Remoting applications as a team project. In traditional HTML-based web applications,
responsibilities usually fall into two general roles: designer and developer. The designer creates the
HTML user interface and the developer creates the application server logic.
When developing Flash applications using Flash Remoting, you might find it useful to organize
development roles as client-side designer, client-side developer, and server-side developer. Under
this division of labor, the client-side designer creates the Flash user interface, including layout,
animation, and effects. The client-side developer creates the ActionScript to connect to the
remote service and handle the results. Finally, the server-side developer builds the business logic
on the application server to serve as the remote service.
16 Chapter 1: Getting Started
Using Flash Remoting
Like a web browser request for an HTML page, a Flash application that uses Flash Remoting
connects to a remote service and makes a service function call. The service function call is a
client-initiated event. The Flash application makes a request to the remote service; the service
processes the request and returns the results.
It is important to note that the Flash application does not wait for the result; it handles the result
when the service function returns it. The Flash application makes requests from ActionScript to
the server and receives results asynchronously.
This means that the ActionScript code that immediately follows the service request executes
before the result of the call is returned from the server. The following example illustrates this
principle by invoking the
trace() function immediately after the service request and then again
when the result is returned by the server.
import mx.remoting.Service; // import Service class
import mx.rpc.FaultEvent; // import FaultEvent class
import mx.remoting.PendingCall // import PendingCall clsas
import mx.rpc.ResultEvent // import ResultEvent class
import mx.rpc.RelayResponder // import RelayResponder class
mx.remoting.debug.NetDebug.initialize();
var myService:Service = new Service("http://examples.macromedia.com/
flashservices/gateway",null,"petmarket.api.catalogservice",
null, null); // connect to remote service
var pc:PendingCall = myService.getCatagories({locale:”en_US”}); // call
service method
pc.responder = new RelayResponder(this, "getData_Result", "getData_Fault");
trace( "no response from server yet." );
function getData_Result( re:ResultEvent ):Void { // receive result
trace( "got the response" );
}
function getData_Fault( fe:FaultEvent ):Void { // receive fault
trace( "got the response" );
}
The output from these calls to the trace() function would appear in the following order:
no response from server yet
got the response
Notice that the first call to the trace() function executes before the result is returned from
the service.
For more information on how to receive and process asynchronous messages from Flash
Remoting, see “Handling service results and errors” on page 43.
Building Flash applications with Flash Remoting 17
Connecting to a service
The fundamental step in using Flash Remoting in your Flash application is connecting to a
remote service. In Flash Remoting for Flash MX 2004 ActionScript 2.0, you can connect to a
remote service either by using the RemotingConnector component or by using the Flash
Remoting ActionScript API to write code in the Actions panel.
To connect to a service using the RemotingConnector component (Flash Professional):
If you use Flash Professional, you perform these basic steps to use the RemotingConnector to
connect to a service.
1.
In the Components panel, select RemotingConnector from the Data Components section and
drag it onto the Stage.
2.
Set parameters in the Component inspector.
3.
Set bindings in the Component inspector.
4.
Write code in the Actions panel.
For more detailed information about connecting to a service by using the RemotingConnector
component, see Chapter 3, “Using the RemotingConnector component (Flash Professional
only),” on page 53. You should read the following sections, however, even if you plan to use the
RemotingConnector to connect to your remote services.
To connect to a service by writing ActionScript code:
1.
From the Window menu in Flash, select Other Panels > Common Libraries > Remoting.
2.
From the Library panel, drag the RemotingClasses library onto the Stage.
3.
To use the NetDebug class and the NetConnection Debugger, you must also drag the
RemotingDebugClasses library to the Stage.
4.
Write your code in the Actions panel.
For more information on writing ActionScript code for Flash Remoting, see the following
sections on building a Hello World application and Chapter 2, “Using Flash Remoting
ActionScript,” on page 29.
For more information on adding the RemotingDebugClasses library to your application, and on
removing it, see “Using the NetConnection Debugger” on page 87.
Building a Hello World application with Flash Remoting
In this section, you build a simple Flash application that uses the Flash Remoting ActionScript
API to connect to a remote service. You can choose among four different remote services,
including a ColdFusion page, a JavaBean, an ASPX page, and a web service. Flash applications
require minimal changes to call different remote services.
The following sections show you first how to build the remote service and then how to call the
remote service from your Flash application using Flash Remoting ActionScript.
18 Chapter 1: Getting Started
Building the remote service
Flash Remoting supports Java, ASP.NET, and ColdFusion-based remote services. For a simple
Hello World application, the following table lists the application server code by platform and
specifies where to save the file to make it available to Flash Remoting.
Application
server
ColdFusion MX
JRun 4
ASP.NET
Application server code File location
<cfset flash.result = "Hello from
ColdFusion MX!">
package com.remoteservices;
import java.io.Serializable;
public class FlashJavaBean
implements Serializable {
private String message;
public FlashJavaBean() {
message = "Hello from Java!";
}
public String helloWorldJava() {
return message;
}
}
<%@ Register TagPrefix="Macromedia"
Namespace="FlashGateway"
Assembly="flashgateway" %>
<%@ Page language="c#" debug="true" %>
<Macromedia:Flash ID="Flash"
runat="server">
Hello from .NET!
</Macromedia:Flash>
Save the ColdFusion page as
helloWorld.cfm in a folder named
remoteservices under your web root.
Save the compiled JavaBean class
file to classes/com/remoteservices
folder under the SERVER-INF
directory.
Save the ASPX page as
helloWorldNET.aspx in the
flashremoting directory under your
web root.
For more information about application server-specific code, see the following chapters:
• Chapter 6, “Using Flash Remoting with ColdFusion MX,” on page 97
• Chapter 7, “Using Flash Remoting for Java,” on page 119
• Chapter 8, “Using Flash Remoting for Microsoft .NET,” on page 143
Calling the remote service from Flash using Flash Remoting ActionScript
To build a Flash application that uses Flash Remoting, you write ActionScript in the Flash
authoring environment to connect to the remote service and call a service function.
To build a Flash application that calls remote services using Flash Remoting:
1.
In the Flash authoring environment, create a new Flash file and save it as serviceTest.fla.
2.
Drag the RemotingClasses library onto the Stage as described in “Connecting to a service”
on page 18.
3.
In the Document window, insert a text field.
Building Flash applications with Flash Remoting 19
4.
Highlight the text field and in the Property inspector, name the text field messageDisplay and
select Dynamic Text in the menu.
5.
Open the Actions panel and insert the following ActionScript code, replacing variables that
appear in italics with the values that correspond to the server you are using. These values are
provided following the code:
import mx.remoting.Service;
import mx.services.Log;
import mx.rpc.RelayResponder;
import mx.rpc.FaultEvent;
import mx.rpc.ResultEvent;
import mx.remoting.PendingCall;
import mx.remoting.RecordSet;
// connect to service and create service object
var howdyService:Service = new Service(
"gatewayUrl",
new Log(),
"serviceName",
null,
null );
// call the service helloWorld() method
var pc:PendingCall = howdyService.serviceFunctionName();
// tell the service what methods handle result and fault conditions
pc.responder = new RelayResponder( this, "serviceFunctionName_Result",
"serviceFunctionName_Fault" );
function serviceFunctionName_Result(result:ResultEvent)
{
// display successful result
messageDisplay.text = result.result;
}
function serviceFunctionName_Fault(fault:FaultEvent)
{
//display fault returned from service
messageDisplay.text = fault.fault.faultstring;
}
The ActionScript code creates a new Service object, howdyService, to create both the gateway
connection and a reference to the remote service. You specify the following variables:
■ The gatewayUrl, which depends on the location of the application server running Flash
Remoting. For example, the following
http://localhost:8500/flashservices/gateway. Specify the appropriate gatewayUrl
value for your remote service.
■ The Log object, to which debugging messages are sent. For more information, see the Log
class in Flash Remoting ActionScript Dictionary Help.
20 Chapter 1: Getting Started
gatewayUrl connects to a ColdFusion service:
■ The serviceName, which is the name of the remote service. To select the appropriate value
for this example, see the table that follows this section.
■ The two null values represent the connection and responder parameters, which are not
used in this case. For information about these parameters, see the constructor for the Service
class in Flash Remoting ActionScript Dictionary Help.
The
serviceFunctionName is the name of the service function that you call. To select the
appropriate value for this example, see the table that follows this section.
The call to the
PendingCall object, called
howdyService.serviceFunctionName() service function returns a
pc in this example. It contains a responder property which the
application sets with a RelayResponder object. The RelayResponder object specifies the object
(first parameter) that contains the methods that handle the values returned by the service
function. The second parameter in the RelayResponder constructor specifies the result handler
method and the third parameter specifies the fault handler method.
This example handles the results returned by the service function using callback functions
named
serviceFunctionName_Result() or serviceFunctionName_Fault(). If the call to
the service function succeeds, the
service function fails, the
_Fault function is called to handle the error.
_Result function is called and it processes the result. If the
The result, which is the value that you expect from the service function, is returned in a
ResultEvent object. The fault, which the service returns for an error condition, is returned in a
FaultEvent object.
For more information about connecting to remote services and handling results, see Chapter 2,
“Using Flash Remoting ActionScript,” on page 29.
6.
Save the file.
In the preceding ActionScript code, substitute the values from the following table for the
serviceName and serviceFunctionName variables, in accordance with the remote service that
you are using:
Remote service serviceName variable serviceFunctionName
variable
ColdFusion MX
JRun 4
ASP.NET
Web service
remoteservices helloWorld
com.remoteservices helloWorldJava
remoteservices helloWorldNET
http://services.xmethods.net/soap/
urn:xmethods-delayed-quotes.wsdl
getQuote
For more information about application server-specific service names and service function names,
see the following chapters:
• Chapter 6, “Using Flash Remoting with ColdFusion MX,” on page 97
• Chapter 7, “Using Flash Remoting for Java,” on page 119
• Chapter 8, “Using Flash Remoting for Microsoft .NET,” on page 143
Building Flash applications with Flash Remoting 21
Migrating existing applications to Flash Remoting for Flash MX 2004 ActionScript 2.0
If you are a new Flash Remoting user who has not yet written any Flash Remoting applications,
you can skip this section.
If you have written Flash Remoting applications using ActionScript 1.0 and you want to migrate
to Flash Remoting for Flash MX 2004 ActionScript 2.0, you have two choices regarding how to
migrate your applications. First, you can make the minimum changes possible to allow your
applications to run with ActionScript 2.0. Second, you can rewrite your application to take
advantage of the improvements in ActionScript 2.0. The following sections describe the tasks that
each choice entails.
Making the minimum changes to your application for ActionScript 2.0
This section describes the minimum changes that you must make to migrate an existing Flash
Remoting application to Flash Remoting for Flash MX 2004 ActionScript 2.0.
To make the minimum changes to your application for ActionScript 2.0:
1.
Drag the RemotingClasses library to the Stage as described in the section “Connecting to a
service” on page 18. If you use the NetDebug class in your program, you must also drag the
RemotingDebugClasses library to the Stage. You can delete the icons from the Stage, if you
want. They do not appear in the published application, however.
2.
Replace any Flash MX UI components with Flash MX 2004 UI components. Because
ActionScript 2.0 is case sensitive, most of the components have been modified for
case-sensitivity and logic issues.
3.
Change #include statements to the appropriate import statements. For example, if your
application contains the following statements:
#include “NetServices.as”
//…
var con:Connection = NetServices.createGatewayConnection(…);
you must change them to the following:
import mx.remoting.NetServices;
//…
var con:Connection = NetServices.createGatewayConnection(…);
To d e te r mi n e w h at import statements you need, see “Importing Flash Remoting ActionScript
classes” on page 35.
4.
If you use the NetDebug class in your program, you must include the following statement in
your application before connecting to a service:
mx.remoting.debug.NetDebug.initialize()
22 Chapter 1: Getting Started
5.
Adjust for and adhere to case sensitivity in ActionScript 2.0.
ActionScript 2.0 is case sensitive. For example,
myVar and myvar were treated as the same
variable in ActionScript 1.0 but they are treated as two distinct variables in ActionScript 2.0:
var myVar:Object = new Object();
var temp:Object = myvar;
trace(temp); // will print undefined
6.
Change *_result method names to *_Result. For example, you must change a method
named
getCategories_result() to getCategories_Result().
7.
Adhere to the following ActionScript 2.0 restrictions:
■ Do not increment an undefined value. Whereas incrementing an undefined value in
ActionScript 1.0 would set it to 1, doing so in ActionScript 2.0 will return "undefined".
■ In ActionScript 2.0, the expression Boolean("String") will return true and Boolean("")
will return
Boolean("1234") returned true.
■ The Object.constructor property must appear only on prototype objects.
8.
Change calls to the NetServices.setDefaultGatewayURL function to
NetServices.setDefaultGatewayUrl. Note the case difference between URL and Url.
false. In ActionScript 1.0, however, Boolean("String") returned false and
For an example of an Action 1.0 Flash Remoting example that has been converted with minimal
changes to comply with ActionScript 2.0, see “Migrating the DataGrid application to Flash
Remoting for Flash MX 2004 ActionScript 2.0” on page 24.
Taking full advantage of Flash Remoting for Flash MX 2004 ActionScript 2.0
To take full advantage of Flash Remoting for Flash MX 2004 ActionScript 2.0, you should make
the following changes to your existing applications in addition to making the changes noted in
the previous section:
• Use the new Flash Remoting API classes and methods:
■ Service class
■ PendingCall class
■ RelayResponder class
■ ResultEvent and FaultEvent classes
■ The new methods of the RecordSet class, including clear(), contains(), editField(),
getEditingData(), getIterator(), getLocalLength(), getRemoteLength(),
isEmpty(), sortItems() and sortItemsBy() methods.
• Consider using the RemotingConnector component.
• Adhere to strict data typing.
Migrating existing applications to Flash Remoting for Flash MX 2004 ActionScript 2.0 23
For more information on using Flash Remoting for Flash MX 2004 ActionScript 2.0 features, see
Chapter 2, “Using Flash Remoting ActionScript,” on page 29 and Flash Remoting ActionScript
Dictionary Help. For a simple example of a Flash Remoting application, see “Building a Hello
World application with Flash Remoting” on page 18. For an example of how to use the
RemotingConnector component in your application, see “Using the RemotingConnector in the
CustomerInfoExampleCon application” on page 57.
Migrating the DataGrid application to Flash Remoting for Flash MX 2004 ActionScript 2.0
This section presents two versions of the Remote DataGrid application to illustrate the minimum
number of changes that you must make to an existing Flash Remoting application to run it under
Flash Remoting for Flash MX 2004 ActionScript 2.0.
When migrating your existing Flash Remoting applications to the Flash Remoting for Flash MX
2004 ActionScript 2.0 API, follow these precautions:
• Use the Flash MX 2004 UI Components with the new Remoting API. Do not use Flash MX
components.
• Make sure your code is consistent in the use of uppercase and lowercase characters.
ActionScript 2.0 is case sensitive.
The DataGrid example uses Flash Remoting with a JavaBean. It simply populates a Flash
DataGrid with dynamic data, listing customers who belong to a selected category.
You can find the Remote DataGrid application in the following folder:
/Program Files/Macromedia/Flash MX 2004/en/First Run/RemotingSamples
See the Readme.htm file in this folder for information on how to set up and use this sample
application.
Example: migrating the DataGrid application
The following steps are the required steps to migrate the Remote DataGrid application from a
previous release (shown as Old API code below) to Flash Remoting for Flash MX 2004
ActionScript 2.0 (shown as New API code below).
1.
Replace all existing Flash MX UI components with Flash MX 2004 UI components, such as
DataGrid, ComboBox, TextInput, and TextArea. For information on Flash MX 2004 UI
components, see Flash MX 2004 Help.
2.
From the Window menu, select Other Panels > Common Libraries > Remoting and click it.
From the Library panel that opens, drag the RemotingClasses and the RemotingDebugClasses
libraries to the Stage.
24 Chapter 1: Getting Started
3.
In the ActionScript code in the Actions panel, change #include statements to import
statements:
// Old API
#include "NetDebug.as"
#include "NetServices.as"
// New API
import mx.remoting.*;
import mx.rpc.*;
These two import statements will import all of the Flash Remoting for Flash MX 2004
ActionScript 2.0 files. For information on importing specific Flash Remoting files, see
“Importing Flash Remoting ActionScript classes” on page 35.
4.
Initialize the NetDebugger (optional) and set up the DataGrid columns.
// New API
NetDebug.initialize();
// Old and New API
grid.columnNames = ["productId", "name", "categoryId", "price"];
5.
Create a gateway connection, establish a reference to a remote service, and set up a Responder
object to call for result-handling and fault-handling.
The old version of the program calls three functions to accomplish these tasks:
NetServices.setDefaultGatewayUrl() to specify the gateway URL,
NetServices.createGatewayConnection() to create the connection, and
connection.getService() to create a reference, catalogService, to the remote service.
The Flash Remoting API accomplishes all three tasks by invoking the constructor for the
Service object.
// Old API
NetServices.setDefaultGatewayUrl("http://localhost:8100/flashservices/
gateway");
connection = NetServices.createGatewayConnection();
//locate a remote service: the RemoteCatalog bean
catalogService = connection.getService("samples.remoting.RemoteCatalog",
this);
// New API
var myService:Service = new Service("http://localhost:8100/flashservices/
gateway",
new Log(Log.DEBUG),
"samples.remoting.RemoteCatalog",
null,
null);
Migrating existing applications to Flash Remoting for Flash MX 2004 ActionScript 2.0 25
The Service constructor both establishes the gateway URL and creates a reference to the
remote service that is being accessed. The Service constructor passes the following parameters
in this order:
■ The gatewayUrl, which in this case is "http://localhost:8100/flashservices/
gateway".
■ The Log, which is optional. For information about the Log, see the Log class in the Flash
Remoting ActionScript Dictionary.
■ The name of the service you are accessing, which is myServiceName in this case.
■ The last two parameters, which have null values in this case, are a Connection object and a
Responder object. For more information on these parameters, see the Service class in the
Flash Remoting ActionScript Dictionary.
Note: The next step describes an alternate way to create a reference to a service in the new API.
6.
Invoke a service method and establish result and fault handler methods.
// Old API
// invoke a service method
catalogService.getCategories();
function getCategories_Result(result)
{
category_array = result;
for (i=0; i< category_array.length; i++)
{
category_cb.addItem( category_array[i].name,
category_array[i].categoryId);
}
category_cb.setSelectedIndex(0);
}
function getCategories_Status(fault)
{
// do something here
}
// New API
// call getCategories service function and set the responder property of the
// PendingCall object (implied here) that is returned by the service
// function call. Sets the responder property with a RelayResponder object
// that specifies the result handling method (“gotCatResults”) and fault
// handling method (“gotCatStatus”) for the outcome returned by the service
// function.
myService.getCategories().responder = new RelayResponder(this,
"gotCatResults", "gotCatStatus");
function gotCatResults(result:ResultEvent)
{
26 Chapter 1: Getting Started
// maps result fields to the comboBox dataProvider; name is the label
// field and categoryId is the data field.
DataGlue.bindFormatStrings(combo, result.result, "#name#",
"#categoryId#");
// dispatch a change event for the dataGrid to be updated.
combo.dispatchEvent({type:"change", target:combo});
}
function gotCatStatus(fault:FaultEvent)
{
trace(" Error : "+ fault.fault.faultstring);
}
You can set up the Responder object in one of the following two ways:
■ The Service constructor passes its name, in which cases it becomes the default handler for
the result and fault outcomes of any method called for the service.
■ The call to the service method specifies the Responder object that will handle the result or
fault only for that specific method invocation. The example uses this approach, using a
RelayResponder object to specify the result handling and fault handling methods for the
getCategories() service function.
7.
Register a listener for the combo ComboBox and set up a responder object for the second service
method call to the
getProductsByCategory() function, which will fetch the detail records
based on the items selected in the ComboBox. The parameter for the
getProductsByCategory() function is the selectedItem.data field.
myChangeObj = new Object();
myChangeObj.change = function(evt:Object)
{
// the textArea should be set to empty once new categories are being fetched,
// so that it does not show any old data
details.text = "";
myService.getProductsByCategory(Number(evt.target.getValue())).responder
= new RelayResponder(_root, "catResult" , "catFault");
}
combo.addEventListener("change", myChangeObj);
function catResult(result)
{
// set up the grid.dataProvider based on the results from
// getProductsByCategory()
grid.dataProvider = result.result;
}
function catFault(error)
{
trace(" received fault ");
}
Migrating existing applications to Flash Remoting for Flash MX 2004 ActionScript 2.0 27
8.
Set up DataGrid’s listener object to update the details TextArea:
gridChange = new Object();
gridChange.change = function(evt)
{
// when the selectedIndex changes in DataGrid, a change event will be fired.
// The details should be updated.
details.text = evt.target.selectedItem.description;
}
grid.addEventListener("change", gridChange);
28 Chapter 1: Getting Started
CHAPTER 2
Using Flash Remoting ActionScript
This chapter explains how to write ActionScript 2.0 code that uses Macromedia Flash Remoting
for Flash MX 2004 to access application services. It explains how to configure connection
information, call service functions, and handle the results that the service returns. After reading
this chapter, you should be able to create a simple application that uses Flash Remoting to obtain
data from an application server.
This chapter describes two ways to access a remote service. The first and easiest way is to use the
RemotingConnector component. The second way is to use the methods of the Flash Remoting
API. The chapter leaves the discussion of the RemotingConnector component to the end because
whether you use it or the API, you need to understand the structure of a Flash Remoting
application and how to handle the results that the service returns.
The chapter also contains two extended examples, CustomerInfoExampleAPI and
CustomerInfoExampleCon, that are different versions of the same application. The
CustomerInfoExampleAPI example uses the Flash Remoting API to connect to and access a
service. The CustomerInfoExampleCon example uses the RemotingConnector component to
connect to and access the same service. For descriptions of these examples, see “Using the Flash
Remoting ActionScript API in the CustomerInfoExampleAPI application” on page 47 and
“Using the RemotingConnector in the CustomerInfoExampleCon application” on page 57.
This chapter contains the following sections:
• “Flash Remoting application structure” on page 30
• “Flash Remoting ActionScript classes” on page 32
• “Configuring Flash Remoting” on page 36
• “Calling service functions” on page 41
• “Handling service results and errors” on page 43
• “Using the Flash Remoting ActionScript API in the CustomerInfoExampleAPI application”
on page 47
• Chapter 3, “Using the RemotingConnector component (Flash Professional only),” on page 53
• “Using the RemotingConnector in the CustomerInfoExampleCon application” on page 57
29
Note: Flash Remoting applications require that Macromedia Flash Player 6 (6.0.79.0), or later, is
installed in the client browser. For information on how to detect the version of Flash Player that a user
is using and how to respond accordingly, see Configuring publish settings for Flash Player detection
in Using Flash Help. For additional information on ensuring that the correct version of Flash Player is
installed on the client’s computer, see the Flash Remoting Support Center on the Macromedia
website at www.macromedia.com/support/flash/flashremoting.
For information on handling Flash Remoting data, and particularly record sets, using
ActionScript, see Chapter 4, “Using Flash Remoting Data in ActionScript,” on page 63.
Flash Remoting application structure
Using Flash Remoting to call an application service is similar to calling a web service or making a
remote procedure call (RPC). In each case, you make a call in your program to some remote
service and you get a response from the service. As with web services and RPCs, data from the
remote service is converted from the native data type of the remote service (such as a Java or C#
data type) to a representation that is used to transfer the data over the network.
Unlike an RPC or web service request, a call made using Flash Remoting does not directly receive
the results of the service. Instead, you write a result-handler callback routine to handle the
returned data. Because the remote service call and the callback routine are separate, your service
call and result handling are asynchronous. In other words, the service request is like a function call
without a return, and the service result or response is like a Flash event, for which you write an
event handler method. The following figure shows this relationship:
To interact with application servers using Macromedia Flash Remoting, do the following in
your Flash application:
1.
From the Window menu in Flash, select Other Panels > Common Libraries > Remoting.
2.
From the Library panel, drag the RemotingClasses library onto the Stage.
3.
To use the NetDebug class and the NetConnection Debugger, you must also drag the
RemotingDebugClasses library to the Stage.
4.
In the Actions panel, import the ActionScript Flash Remoting classes.
30 Chapter 2: Using Flash Remoting ActionScript
Loading...