Macromedia Using ColdFusion MX with Flex 2 User Manual

Using ColdFusion MX with Flex 2

Trademarks

1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flash Video Encoder, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Adobe Systems Incorporated, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Adobe Systems Incorporated 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 Adobe Systems Incorporated 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 Adobe Systems Incorporated, and Adobe Systems Incorporated 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. Adobe Systems Incorporated provides these links only as a convenience, and the inclusion of the link does not imply that Adobe Systems Incorporated endorses or accepts any responsibility for the content on those thirdparty sites.

Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com).

Sorenson™ Spark™ video compression and decompression technology licensed from Sorenson Media, Inc.

Copyright © 2006 Adobe Macromedia Software LLC. 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 written approval from Adobe Systems Incorporated Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services.

Acknowledgments

Project Management: Randy Nielsen

Writing: Anne Sandstrom

Editing: Linda Adler

Production Management: Adam Bernett

Media Design and Production: Masayo Noda

Special thanks to Linda Adler, Randy Nielsen, Bill Sahlas, Farah Gron, Bob Powelll, Mike Nimer., Dean Harmon, and Tom J o r dh a l

First Edition: June, 2006

Adobe Systems Incorporated 601 Townsend St. San Francisco, CA 94103

Contents

Chapter 1: Using Flash Remoting Update . . . . . . . . . . . . . . . . . . . . 5

About Flash Remoting Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Using Flash Remoting Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Data translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Chapter 2: Using the Flex Messaging Event Gateway . . . . . . . . . 13

About Flex and ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Configuring a Flex Messaging event gateway . . . . . . . . . . . . . . . . . . . . . 15

Enabling communication with Flex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Sending outgoing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Handling incoming messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Using session and client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Data translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 3: Use ColdFusion Event Gateway Adapter . . . . . . . . . 25

Set up your development environment . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Create the Flex application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Import the required ActionScript classes . . . . . . . . . . . . . . . . . . . . . . 29

Create the ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Test the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 4: Using the Flex Data Service Assembler . . . . . . . . . . 35

About Flex and ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Application development and deployment process . . . . . . . . . . . . . . . .37

Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Enabling SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Data translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

Example application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 5: Using the ColdFusion Extensions for

Flex Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

About the ColdFusion Extensions for Flex Builder . . . . . . . . . . . . . . . . 74

Installing the ColdFusion Extensions for Flex Builder . . . . . . . . . . . . . . 74

Eclipse RDS Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

ColdFusion/Flex Application wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

ActionScript to CFC wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

CFC to ActionScript wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

RDS CRUD wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Services Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

4Contents

CHAPTER 1

Using Flash Remoting Update

You can use Macromedia Flash Remoting Update to create rich Internet applications in ColdFusion MX 7.0.2.

About Flash Remoting Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Using Flash Remoting Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

About Flash Remoting Update

The Flash Remoting Update lets you create rich Internet applications (RIAs) by using Adobe Flex Builder 2, with the advanced data retrieval features of ColdFusion, such as the c

cfldap, and cfquery tags. In addition, you can use Flash Remoting Update to create

Macromedia Flash Forms and Flash applications that contain features such as server call backs and customized user interface.

You can use Flash Remoting Update with all configurations of ColdFusion MX 7.0.2 (server, multiserver, and J2EE) on all the platforms that ColdFusion MX 7.0.2 supports.

To use Flash Remoting Update, you must have the following installed:

■ Flex Builder 2

■ Flash Player 9

■ ColdFusion MX 7.0.2

fpop,

Using Flash Remoting Update

To specify a CFC to connect to, you do one of the following:

■ Specify the CFC, including the path from the web root, in the MXML.

■ Create a named resource for each CFC that you connect to. This is similar to registering a

data source.

To specify the CFC in the MXML:

■ Specify the CFC, including the path from the web root, in the MXML; for example:

<mx:RemoteObject

id="myCfc" destination="ColdFusion" source="myApplication.components.User"/>

The destination “ColdFusion” is preconfigured in the services-config.xml file, which is located in the ColdFusion webroot\WEB-INF\flex directory, with the wildcard source. To use the source attribute in MXML, you can use any destination by specifying the

source="*". If you specify a source other than “*”, that source definition overrides

the source specified in the MXML.

To create a named resource for each CFC that you connect to:

1. Edit the services-config.xml file by adding an entry for each CFC that you connect to, for

example:

<lowercase-keys>true</lowercase-keys> </properties>

</destination>

The source attribute specifies the dot notation to the CFC from the web root (the classpath to the CFC).

2. Restart the ColdFusion server.

* as the

6 Using Flash Remoting Update

To use the CFC resource in your Flex Builder 2 project:

1. For each Flex Builder 2 project, set the Flex compiler property by doing the following:

a. Select Project > Properties.

b. Select the Flex complier option.

c. Enter the following in the Additional Compiler Argument text box:

--services=C:\CFusionMX7\wwwroot\WEB-INF\flex\services-config.xml

In the mxml file, you use the <mx:RemoteObject> tag to connect to your CFC named

resource. With this connection you can call any remote method on the CFC.

3. Use the destination attribute of the <mx:RemoteObbject> tag to point to the name that

you defined in the services-config.xml file; for example:

<mx:RemoteObject

id="a_named_reference_to_use_in_mxml" destination="CustomID" result="my_CFC_handler(event)"/>

Call a CFC method, for example, as the following example shows:

<mx:Button label="reload" click="my_CFC.getUsers()"/>

In this example, when a user presses a button, the Click event calls the CFC method

getUsers.

5. Specify a handler for the return result of the CFC method call for the <mx:RemoteObject>

tag, as the following example shows.

private function my_CFC_handler( event:ResultEvent ) { // Show alert with the value that is returned from the CFC. mx.controls.Alert.show(ObjectUtil.toString(event.result)); }

Using Flash Remoting Update 7

Flash Remoting Update and authentication

The Flash client passes the username and password, which are set in the Flash client, to the CFC. To authenticate users when using Flash Remoting Update, you can then use the

cflogin tag to authenticate the user.

Flash Remoting Update supports the same authentication mechanism as any HTTP request from the browser, including getting and setting cookies. This mechanism allws you to take advantage of the same authentication systems you use for any normal HTTP request. To take advantage of this functionality in a Flash application, you need to set the HTTP authorization headers by specifying the user’s username and password with the RemoteObject

setRemoteCredentials method. When ColdFusion receives the Flash Remoting /http

request, ColdFusion populates the cflogin.name and cflogin.password variables (inside the

cflogin tag) with these values. For more information, see the documentation for the cflogin tag.

Example application

The following sample application lets you test authentication. It consists of a Flex application, and a ColdFusion application that consists of an Application.cfm file and the ColdFusion component that the Flex application calls.

The Flex application appears as follows:

The Flex application above lets you enter a username and password. It creates a remote object to the CFC. Because the application creates a remote object that is managed by a CFC, you

can set a username and password for the authentication mechanism of the remote service.

When you click the Login button, the application calls the setRemoteCredentials method, using the username and password entered in the text boxes. This sets the properties in the

mx:RemoteObject tag, which are passed in all future requests.

8 Using Flash Remoting Update

When you click the Logout button, the application calls the setRemoteCredentials method, which sets the username and password to null, and logs out the user on the client side. In addition, the application calls the

logoutuser method, which handles server side

logout.

When you click the Get Secure Data button, the application calls the MXML file, which, in turn, calls the

getData function in the CFC. The getData function in

getData method in the

the CFC returns a string for purposes of this simple test application, but could be modified to return data such as the results of a query.

The Flex application also includes the

serverFault and serverResult methods, which

display an alert box to indicate whether the login was successful or not.

The MXML file appears as follows:

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*"

layout="absolute"> <mx:Script>

<![CDATA[

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

private function logIn():void{

cf.setRemoteCredentials(this.username.text, this.password.text);

}

private function logOut():void {

cf.setRemoteCredentials(null, null);

cf.logoutuser(); } private function getData():void {

cf.getData(); } private function serverFault(event:FaultEvent):void{

Alert.show( ObjectUtil.toString(event.fault) );

Alert.show( "error" ); } private function serverResult(event:ResultEvent):void{

Alert.show( ObjectUtil.toString(event));

Alert.show( "success" ); }

]]>

</mx:Script>

Using Flash Remoting Update 9

<mx:RemoteObject id="cf"

destination="ColdFusion" source="CFIDE.samples.LoginTest.logintest"> <mx:method name="getData" result="serverResult(event)"

fault="serverFault(event)" />

<mx:method name="logoutuser" />

</mx:RemoteObject>

<mx:Form x="10" y="10">

<mx:FormItem label="username">

<mx:TextInput id="username" text="admin"/>

</mx:FormItem> <mx:FormItem label="password">

<mx:TextInput id="password" text="adminpwd"/>

</mx:FormItem> <mx:FormItem direction="horizontal">

<mx:Button label="Login" click="logIn();"/> <mx:Button label="Logout" click="logOut()"/>

</mx:FormItem> <mx:Button label="Get Secure Data" click="getData();"/>

</mx:Form>

</mx:Application>

The Application.cfm file authenticates the user and identifies the user with the flexadmin role.

<cfapplication name="loginTest6" sessionmanagement="true"

setclientcookies="true">

</cflogin>

10 Using Flash Remoting Update

The CFC contains two functions: logoutuser and getData. The getData function authenticates the user against the flexadmin role and returns a string.The logoutuser function calls the <cflogout> tag to log the user out on the server.

</cfcomponent>

TIP

To make communication between the Flex application and the CFC secure, you can specify that the AMF channel in the ColdFusion destination definiton be secure in the WEB-INF\flex\services-config.xml file.

Data translation

The following table lists the ColdFusion data types and the corresponding ActionScript data type:

ColdFusion data type Flash data type

String String

Array [] = Array

Struct {} = untyped Object

Query Array of untyped Objects

CFC Class = typed Object (if a matching ActionScript class

exists, otherwise the CFC becomes a generic untyped Object (map) in ActionScript)

CFC Date ActionScript Date

CFC String ActionScript String

CFC Numeric ActionScript Numeric

ColdFusion XML Object ActionScript XML Object

Using Flash Remoting Update 11

12 Using Flash Remoting Update

CHAPTER 2

Using the Flex Messaging Event Gateway

You can develop an application that uses the Flex Messaging gateway type to send messages to and receive messages from an Adobe Flex application. To do so, you configure the Flex Messaging gateway. This document provides information about how to write and test an application that uses the event gateway.

You should be familiar with ColdFusion event gateway in ColdFusion MX Developer’s Guide. This document also assumes that you are familiar with Adobe Flex Data Services.

NOTE

Macromedia ColdFusion MX Standard Edition does not support event gateways.

About Flex and ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Configuring a Flex Messaging event gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Enabling communication with Flex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Sending outgoing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Handling incoming messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Using session and client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Data translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

About Flex and ColdFusion

ColdFusion includes the Flex Messaging event gateway, which uses the ColdFusion Event Gateway Adapter to send messages to and receive messages from Adobe Flex Data Services. This means that ColdFusion applications and Flex applications can publish to and consume events from the same event queue.

NOTE

To use the Flex Messaging event gateway to interact with a Flex application, the Flex application must be running on Flex Data Services.

How ColdFusion and Flex interact

You can send messages from a ColdFusion application to a Flex application, through the Flex Messaging event gateway. Conversely, you can send messages from a Flex application to a ColdFusion application.

Either the ColdFusion application or the Flex application can initiate sending a message. The following image shows the message handling process in which a message is sent from the Flex application to the ColdFusion application, and then from the ColdFusion application to the Flex application.

1. The Flex application generates a message.

2. The Flex Message Service passes the message to the ColdFusion Event Gateway Adapter.

3. The ColdFusion Event Gateway Adapter sends the message to the Flex Messaging event

gateway, by using Java Remote Method Invocation (Java RMI).

4. The Flex Messaging event gateway and the ActionScript translator convert ActionScript

3.0 data types to the appropriate ColdFusion values and add the message to the event gateway queue.

5. The ColdFusion server invokes the onIncomingMessage method of the Flex Messaging

event gateway listener CFC.

6. The ColdFusion application generates a message, which it sends to the ColdFusion server.

7. The ColdFusion server sends the message to the Flex Messaging event gateway.

14 Using the Flex Messaging Event Gateway

8. The Flex Messaging event gateway and the ActionScript translator convert ColdFusion

values to the appropriate ActionScript 3.0 data types, and then the gateway sends the message to the ColdFusion Event Gateway Adapter.

9. The ColdFusion Event Gateway Adapter sends the message to the Flex Message Service.

10. The Flex Message Service passes the message to the Flex application.

NOTE

The RMI registry, which facilitates communication between the ColdFusion Event Gateway Adapter and the Flex Messaging event gateway uses port 1099, which is the default port for Java RMI. You cannot change this port number. To ensure that the RMI registry provides registry service for both Flex Data Services and ColdFusion, start Flex first, and then start ColdFusion. If you stop Flex, you must restart Flex, and then restart the gateway.

Application development and deployment process

The following is a typical process for developing and deploying a ColdFusion application that communicates with a Flex application through the Flex Messaging event gateway:

1. Design your application.

2. Configure a Flex Messaging Event gateway instance.

3. Write your ColdFusion CFCs, CFM pages, and any other application elements.

4. Test your application by using Flex.

5. Make the application publicly available.

Configuring a Flex Messaging event gateway

Although you can configure an instance of a Flex Messaging event gateway by creating a configuration file, which you specify when you create the gateway instance, you can also provide the configuration information in the message sent from the Flex application. You use a configuration file to provide configuration information to the Flex Messaging event gateway to do one of the following:

■ Have the Flex Messaging event gateway send messages to Flex Data Services on a different

computer

■ Use the Flex Messaging event gateway with a specific Flex destination, and ignore any

destination specified in the message

■ Specify the IP addresses from which your ColdFusion application accepts messages

Configuring a Flex Messaging event gateway 15

The Flex Messaging event gateway configuration file is a simple Java properties file that contains the following properties:

Property Description

destination A hard-coded destination. If you specify this value, any destination

information in the message is ignored.

host The host name or IP address of the Flex Data Services server.

allowedIPs A comma- delimited list of IP addresses from which the Flex Messaging

event gateway accepts messages. If you do not specify a list of allowed IPs, only processes on the local computer can send messages to the gateway.

The following is an example configuration file:

# # Flex event gateway configuration #

# This is the destination of the messages. destination=Gateway1

# Hostname or IP address of the Flex Enterprise Server. host=127.0.0.1

# IP addresses from which the application will accept messages. allowedIPs=10.60.1.1,10.60.1.2.

If you create a configuration file, save it in the {cf.rootdir}/gateway/config/ directory, with the extension .cfg.

Enabling communication with Flex

To enable communication through the Flex Messaging event gateway, you copy and paste the information from the sample configuration files.

To enable communization through the Flex Messaging event gateway:

1. Copy the following <adapter-definition> section from the sample messaging-config.xml

file to the web application flex-messaging-service.xml file, into the <adapter> section:

<adapter-definition id="cfgateway"

class="coldfusion.flex.CFEventGatewayAdapter"/>

The sample messaging-config.xml file is located in the C:\fds2\resources\config\flex folder when you install Flex in the default location. The web application messaging-config.xml file is located in the C:\fds2\jrun4\servers\default\samples\WEB-INF\flex folder when you install Flex in the default location.

16 Using the Flex Messaging Event Gateway

2. Copy the following <destination> section from the sample messaging-config.xml file to the

web application messaging-config.xml file:

<destination id="ColdFusionGateway">

<properties> <!-Star ('*') means gatewayid is found in the 'gatewayid' message header. To restrict this destination to a specific gateway, enter its ID here

--> <gatewayid>*</gatewayid> <!-If ColdFusion is running on a different host, enter that here. Default is to look for ColdFusion on this computer. <gatewayhost>10.1.1.1</gatewayhost>

--> <!-List the IP addresses of CF machines allowed to send messages to this destination If not set, the default is to allow only this computer to connect. Do NOT use 127.0.0.1, it must be the actual IP address <allowedIPs>10.1.1.1,10.2.2.2</allowedIPs>

--> <!-Credentials to pass along in the headers as CFUsername/CFPassword. It is generally better to use setRemoteCredentials() API on client. <remote-username></remote-username> <remote-password></remote-password>

--> </properties> <!-These channels will work unless you want to pass value objects (objects that get translated to and from CFCs) in your messages. In that case, use the "cf-dataservice-rtmp" and "cf-polling-amf channels".

--> <channels>

</channels>

</destination>

Enabling communication with Flex 17

3. Change the ID of the destination so the destination ID for each ColdFusion destination

on that machine is unique. (For example, because ColdFusion finds the destination by locating its name in a machine wide registry, you should not specify the same destination ID in both the flex and the samples web application.)

4. To use the ColdFusion-specific channels (to support value objects), copy the following

channels from the sample services-config.xml file to the web application servicesconfig.xml file:

<channel-definition id="cf-polling-amf" class="mx.messaging.channels.AMFChannel"> <endpoint uri="http://{server.name}:{server.port}/{context.root}/messagebroker/

cfamfpolling"

class="flex.messaging.endpoints.AMFEndpoint"/> <properties> <serialization>  <instantiate-types>false</instantiate-types> </serialization> <polling-enabled>true</polling-enabled> <polling-interval-seconds>8</polling-interval-seconds> </properties> </channel-definition>

The sample services-config.xml file is located in the C:\fds2\resources\config folder when you install Flex in the default location. The web application services-config.xml file is located in the C:\fds2\jrun4\servers\default\samples\WEB-INF\flex folder when you install Flex in the default location.

18 Using the Flex Messaging Event Gateway

Sending outgoing messages

Your ColdFusion application sends a message to a Flex application by doing the following actions:

1. The ColdFusion application sends an outgoing message, in a cfreturn tag in the listener

CFC’s listener method, or by calling the ColdFusion

2. A method provided by the Flex Messaging gateway gets called when you send an outgoing

message.

In outgoing messages sent from CFML, the following structure members are translated to the Flex message:

Name Contents

body Body of the message. This is required.

CorrelationID Correlation identifier of the message.

Destination Flex destination of the message. This is required if it is not specified in the

configuration file.

Headers If the message contains any headers, the CFML structure that contains

the header names as keys and values.

LowercaseKeys If the value is set to yes, the structure keys are converted to lowercase

during creation of ActionScript types.

TimeToLive Number of milliseconds during which this message is valid.

SendGatewayMessage function.

In addition, the Flex Messaging event gateway automatically provides values for the following Flex message fields:

Name Contents

MessageID A UUID that identifies the message

Timestamp Time the message is sent

ClientID ID of the Flex Messaging event gateway instance

NOTE

A single instance of the Flex Messaging event gateway can send messages to any destination that is registered with the ColdFusion Event Gateway Adapter. However, if the destination is configured in the Flex Messaging gateway configuration file, the destination in the message is ignored.

Sending outgoing messages 19

Sending outgoing message example

The following example from a CFM page creates a structure that contains the message. The

destination is the destination ID specified in the messaging-config.xml file for the instance

of the Flex Messaging event gateway to send the message to. The message. The

sendGatewyMessage CFML function sends the message to the instance of the

body is the body of the

gateway.

Handling incoming messages

When a Flex application sends a message to a ColdFusion application, the Flex Messaging event gateway sends a CFEvent structure to the configured CFC, with the following information mapped to the data of the event:

Name Contents

body Body of the message.

ClientID ID of the client that sent the message.

CorrelationID Correlation identifier of the message.

Destination Flex destination of the message.

Headers If the message contains any headers, the CFML structure that contains the

header names as keys and values.

Timestamp Timestamp of the message.

onIncomingMessage function of the

The incoming message data structure also includes the values of

messageID and timeToLive

from the Flex message.

Incoming message handling example

The following example puts data that is contained in the body of the message from the Flex application into a structure. It then uses the contents of the structure to generate an e-mail message.

<cfcomponent displayname="SendEmail" hint="Handles incoming message from

Flex"> <cffunction name="onIncomingMessage" returntype="any"> <cfargument name="event" type="struct" required="true">

20 Using the Flex Messaging Event Gateway

<cfset messagebody = event.data.body>

<cfset mailfrom="#messagebody.emailfrom#"> <cfset mailto="#messagebody.emailto#"> <cfset mailsubject="#messagebody.emailsubject#"> <cfset mailmessage ="#messagebody.emailmessage#">

<cfmail from="#mailfrom#"

to="#mailto#" subject="#mailsubject#"> <cfoutput>#mailmessage#</cfoutput>

</cfmail>

</cffunction>

</cfcomponent>

If the Flex application sends the message in the header instead of in the body, you create and populate the structure, as the following example shows:

Using session and client variables

The Flex Messaging event gateway supports session and client variables. In messages sent from Flex to ColdFusion through the gateway, the clientID field of the incoming message is the key to the session. Flex assigns the clientID to the instance of each Flex application.

Using session and client variables 21

Authentication

Flex and ColdFusion provide the following authentication features for communicating through the Flex Messaging event gateway:

■ Restricting IP addresses that are allowed to send a message through the Flex Messaging

event gateway

■ Specifying remote credentials in Flex, and then authenticating those credentials in

ColdFusion

Restricting IP addresses

To restrict the IP addresses from which your ColdFusion application accepts messages, you must use a confiugration file, as specified in “Configuring a Flex Messaging event gateway”

on page 15. In addition to specifying the destination and host, you specify the comma-

delimited list of IP addresses from which your ColdFusion application accepts messages.

Also, you can specify the allowed IPs for when you send messages from Flex to ColdFusion. You do so in the destination definition in the messaging-config.xml file on the server on which your Flex application is running. The following example is a sample destination:

</properties> <channels>

</channels>

</destination>

NOTE

The local machine is not included in the list of allowed IPs by default.

Specifying remote credentials

The Flex application passes the username and password, which are set in the Flex application, to the CFC. To authenticate users, you can then use the tag in an Application.cfm or Application.cfc file that executes when a method in the CFC is called.

22 Using the Flex Messaging Event Gateway

cflogin tag. You put the cflogin

The session ID is the client ID assigned to your Flex application. Reloading the Flex application starts a new session with a new session ID.

To set credentials in a message in Flex, before sending the message through the gateway to the CFC, you use the

var msg:Message = new AsyncMessage(); msg.body = input.text; msg.headers.gatewayID = "Flex2CF";

msg.setRemoteCredentials("mycfusername", "mycfpassword");

setRemoteCredentials method, as follows:

To authenticate the credentials sent in the message, in an Application.cfm or Application.cfc file, you use the

<cfloginuser name="#cflogin.name#" password="#cflogin.password#"

</cfif>

</cflogin>

cflogin tag, as follows:

roles="#roles#">

Data translation

The following table lists the ColdFusion data types and the corresponding Adobe Flash or ActionScript data type:

ColdFusion data type Flash data type

String String

Array [] = Array

Struct {} = untyped Object

Query Array of untyped Objects

CFC Class = typed Object (if a matching ActionScript class

exists, otherwise the CFC becomes a generic untyped Object (map) in ActionScript)

CFC Date ActionScript Date

CFC String ActionScript String

CFC Numeric ActionScript Numeric

ColdFusion XML Object ActionScript XML Object

Data translation 23

24 Using the Flex Messaging Event Gateway

CHAPTER 3

Use ColdFusion Event Gateway Adapter

This tutorial shows you how to create a Flex application to send a message to a ColdFusion application and a ColdFusion component to send a message to a Flex application. The sample application does not take advantage of capabilities that are unique to Adobe Flex, instead, it describes the communication with ColdFusion applications that the ColdFusion Event Gateway Adapter enables.

To show the capabilities of the ColdFusion Event Gateway Adapter and the Flex Messaging event gateway, the sample application lets you enter information in a form in a Flex application. The Flex application sends the information through the ColdFusion Event Gateway Adapter and Flex Messaging event gateway to the ColdFusion application. The ColdFusion application then sends an e-mail message that contains the message to the recipient specified in the Flex application. Finally, the ColdFusion component sends a message to the Flex application, which displays the body of the message.

In this tutorial, you’ll complete the following tasks:

Set up your development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Create the Flex application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Create the ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Test the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Set up your development environment

The ColdFusion Event Gateway Adapter lets you create applications in which Flex Data Services and ColdFusion MX 7.0.2 communicate. Flex Data Services includes the ColdFusion Event Gateway Adapter. ColdFusion MX 7.0.2 includes the Flex Messaging event gateway.

To complete this tutorial, you must have the following products installed:

■ Flex Data Services

■ ColdFusion MX 7.0.2

Start Flex and ColdFusion

To set up your development environment, you must start Flex Data Services and ColdFusion. This tutorial assumes that both Flex Data Services 2 and ColdFusion are running on localhost (127.0.0.1) on your local computer. Because of the way in which the Remote Method Invocation (RMI) registry is created and maintained, Adobe recommends that you start Flex Data Services, and then start ColdFusion.

NOTE

The example ColdFusion application uses the cfmail tag. You must set up an e-mail server in the ColdFusion MX Administrator before testing the application.

Enable the ColdFusion Event Gateway Adapter

The messaging-config.xml file contains information about adapters and destinations, including network and server properties and channels. Generally, the file contains the following:

- service

- adapters

- adapter-definition

- destination

- properties

- network

- server

- channels

TIP

To become familiar with the messaging-config.xml file, view it in an XML editor so that you can expand and collapse sections.

26 Use ColdFusion Event Gateway Adapter

To ensure that Flex Data Services recognizes the ColdFusion Event Gateway Adapter, you edit the messaging-config.xml file, which is located in the C:\fds2\jrun4\servers\default\samples\WEB-INF\flex directory if you installed Flex Data Services using the default settings.

To enable communication through the Flex Messaging event gateway:

1. Copy the <adapter-definition> section in which id=”cfgateway” from the sample

messaging-config.xml file to the <adapter> section of the web application messagingconfig.xml file.

The sample messaging-config.xml file is located in the C:\fds2\resources\config\flex folder, and the web application messaging-config.xml file is located in the C:\fds2\jrun4\servers\default\samples\WEB-INF\flex folder when you install Flex in the default location.

2. Copy the <destination> section in which id=”ColdFusionGateway” from the sample

messaging-config.xml file to web application messaging-config.xml file.

3. Save the file.

Create an instance of the Flex Messaging event gateway

To be able to communicate with the ColdFusion application through the Flex Event Gateway, you must create an instance of the gateway.

1. Create a blank file handleemail.cfc in the C:\CFusionMX7\wwwroot\flexgatewayexamples

directory. (The flexgatewayexamples directory does not already exist.)

2. Start the ColdFusion MX Administrator.

3. Select Event Gateways > Gateway Instances.

4. Enter Flex2CF2 as the Gateway ID.

5. Select Flex Messaging - Flex as the Gateway Type.

6. Specify C:\CFusionMX7\wwwroot\flexgatewayexamples\handleemail.cfc as the CFC

Path.

7. Select Automatic as the Startup Mode.

8. Click Add Gateway Instance.

Set up your development environment 27

+ 63 hidden pages