MACROMEDIA FLASH REMOTING MX Use 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.

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

3

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

4 Contents

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

Contents 5

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

6 Contents

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

Contents 7

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

8 Contents

9

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

®

.NET, Java, and Simple Object Access Protocol (SOAP)-based web

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.

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.

10 Introduction: About Flash Remoting

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

connection property, which

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

Developer resources 11

■ 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

responder property, which you use

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

outcomes of a service call are relayed.

■ A RecordSet object that contains new properties (columnNames, items, and length), new

methods (

clear(), contains(), editField(), getEditingData(), getIterator(),

getLocalLength(), getRemoteLength(), isEmpty(), and sortItems()), and the new

modelChanged event.

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

General information about

Macromedia products and services.

www.macromedia.com

Information on

Flash Remoting

Detailed product information on

Flash Remoting and related topics.

www.macromedia.com/go/flashremoting

Macromedia

Flash Remoting

Support Center

Professional support programs that

Macromedia offers.

www.macromedia.com/go/

flashremoting_support

Flash Remoting

Online Forum

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.

www.macromedia.com/go/flash_forum

Installation

support

Support for installation-related

issues for all Macromedia products.

www.macromedia.com/support/email/

isupport

Training Information about classes, on-site

training, and online courses offered

by Macromedia.

www.macromedia.com/go/flash_training

12 Introduction: About Flash Remoting

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

Developer

resources

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.

www.macromedia.com/go/devnet

Macromedia

Alliance

Connection with the growing

network of solution providers,

application developers, resellers,

and hosting services creating

solutions with Flash Remoting.

www.macromedia.com/go/partners

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.

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.

Sales Toll Free: 888.939.2545

Tel: 617.219.2100

Fax: 617.219.2101

E-mail: [email protected]

Resource Description URL

13

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

getURL and loadVariables and XML functions like XMLSocket,

Flash Remoting provides the following advantages:

• 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.

14 Chapter 1: Getting Started

• 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.

About Flash Remoting 15

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.

16 Chapter 1: Getting Started

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.

Building Flash applications with Flash Remoting 17

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.

18 Chapter 1: Getting Started

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.

Building Flash applications with Flash Remoting 19

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.

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.

Application

server

Application server code File location

ColdFusion MX

<cfset flash.result = "Hello from

ColdFusion MX!">

Save the ColdFusion page as

helloWorld.cfm in a folder named

remoteservices under your web root.

JRun 4

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;

}

Save the compiled JavaBean class

file to classes/com/remoteservices

folder under the SERVER-INF

directory.

ASP.NET

<%@ 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 ASPX page as

helloWorldNET.aspx in the

flashremoting directory under your

web root.

20 Chapter 1: Getting Started

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

gatewayUrl connects to a ColdFusion service:

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.

Page is loading ...

MACROMEDIA FLASH REMOTING MX Use Manual

This manual is also suitable for

MACROMEDIA FLASH REMOTING MX Use Manual

Related papers

Other documents