Configuring a destination for the Data Service Adapter

To provide the information necessary for the Flex application to connect to the ColdFusion back-end application, you configure a destination. In the destination, you specify the ColdFusion Data Service adapter, the channels to use to transport messages to and from the destination, the CFC that contains the fill, get, sync, and count methods, and other settings.
To provide configuration information, you edit the following files:

  1. services-config.xmlYou specify channel definitions and enable ColdFusion-specific debugging output in the Flex console in this file. Change the port numbers in the services-config.xml file for the RTMP channels if you run more than one ColdFusion instance with the integrated LiveCycle Data Services ES.
  2. data-management-config.xmlThis file is added only when you install LiveCycle Data Services 2.6.1 manually. You specify adapters and destinations in this file.
    To ensure that Flex recognizes the LiveCycle Data Services ES assembler and can transport messages to and from the destination, by doing the following:
  • Specifying ColdFusion-specific channel definitions
  • Specifying the ColdFusion Data Service adapter
  • Specifying a destination
  • Enabling ColdFusion-specific debugging output

Enhanced Flash Remoting

ColdFusion 10 has introduced enhanced Flash Remoting.

  • Enhanced Flash Remoting supports Circular references for objects which are not supported in old Flash Remoting (ColdFusion 8).
  • Enhanced Flash Remoting is significantly faster than the old one
    The default ColdFusion 10 installation makes use of this Enhanced Flash Remoting. The structure inside the xml configuration files under WEB-INF/flex directory has been changed to support Enhanced Flash Remoting.
    ColdFusion 10 supports Old XML configurations files as well, but with these files it will not be using Enhanced Flash Remoting. To take advantage of Enhanced Flash Remoting, while migrating your old XML files to ColdFusion10, you should make sure that they comply with new XML structural changes. 
    If you are using LCDS with ColdFusion 10, then Flash Remoting works on LCDS 2.6.1. Ensure that you are on LCDS 2.6.1 to make use of the enhanced Flash Remoting. 
    ColdFusion 10 is backward compatible with old Flash Remoting as well, to support LCDS2.5 and prior releases.
    Now in a case, where you require to continue with LCDS 2.5 or prior versions, it will not be possible for you to use enhanced Flash Remoting offered by ColdFusion 10. In this scenario, you can continue working with LCDS2.5 and prior versions with old style XML configuration files. 
    To use the old style flash remoting with LCDS 2.5, first remove the existing ColdFusion 10 flex-.jar files from cfusion/lib by taking a backup of the files and placing the LCDS2.5 flex-.jar files in the cfusion\lib directory. After this, you can continue to use the old style (ColdFusion 8) XML configuration files by placing them under WEB-INF\Flex directory. Also make sure that WEB-INF\ flex\jar\cfdataserviceadapter.jar is also present. 
    For detailed steps on integrating LCDS2.5 with ColdFusion, see the technote on www.adobe.com.
    Another case here could be that you have integrated LCDS 2.6.1 with ColdFusion 10 and still you want to use old Flash Remoting. You can implement this scenario, but in this case you cannot take advantages offered by enhanced Flash Remoting.

Changes in the XML configuration files for Flash Remoting in ColdFusion 10

For ColdFusion 10, the structure of the services-config.xml file has changed. These structural changes are:

  • A new <coldfusion> tag has been added under the <properties> in <channel-definition>, where the <access>, <use-accessor>, <use-structs>, and <property-case> tags are defined.In old ColdFusion 8 style remoting, these tags used to be present in the destination, defined in data-management-config.xml file.
  • Previously, the <serialization>tag included:

    <serialization>
    <instantiate-types>false</instantiate-types>
    </serialization>

    However, now you need to either set the <instantiate-types> to true or remove it from the services-config.xml file.

  • The <enable-small-messages> flag must be set to falseunder the serialization property.

    Note: In case you create custom channel definition on your client side by overriding the XML-based channel configurations, you still need to set "enableSmallMessages" flag to false. This is shown in the following code example:

     

<mx:ChannelSet id="myChannelSet">
<mx:channels>
<mx:AMFChannel enableSmallMessages="false" url="http://localhost:8500/flex2gateway/cfamfpolling" id="cfAMFPolling" pollingEnabled="true" pollingInterval="8"/>
</mx:channels>
</mx:ChannelSet>

  • In ColdFusion 9, the endpoint class names have been changed from the endpoint classes in ColdFusion 8. The following table provides a list of channel-definitions and their corresponding endpoint classes:

Channel-definition ID

ColdFusion 10 Endpoint Class

ColdFusion 8 Endpoint Class

my-cfamf

coldfusion.flash.messaging.CFAMFEndPoint

flex.messaging.endpoints.AMFEndpoint

cf-polling-amf

coldfusion.flash.messaging.CFAMFEndPoint

flex.messaging.endpoints.AMFEndpoint

my-cfamf-secure

coldfusion.flash.messaging.SecureCFAMFEndPoint

flex.messaging.endpoints.SecureAMFEndpoint

cf-rtmp

coldfusion.flash.messaging.CFRTMPEndPoint

flex.messaging.endpoints.RTMPEndpoint

 

Note: For LiveCycle Data Services ES, the cf-polling-amf and cf-rtmp channel definitions are used.

  • ColdFusion 10 supports BlazeDS 4. The following table details the endpoint classes for BlazeDS:

Channel-definition ID

Endpoint Class

my-streaming-amf

coldfusion.flash.messaging.CFStreamingAMFEndPoint

secure-streaming-amf

coldfusion.flash.messaging.SecureCFStreamingAMFEndPoint

  • ColdFusion 10 supports LCDS 3 and LCDS 3.1.The following table details the endpoint classes for LCDS:

Channel-definition ID

Endpoint Class

my-nio-amf

coldfusion.flash.messaging.CFNIOAMFEndPoint secure-nio-amf

secure-nio-amf

coldfusion.flash.messaging.SecureCFNIOAMFEndPoint

secure-cf-rtmp

coldfusion.flash.messaging.SecureCFRTMPEndPoint

my-nio-amf-stream

coldfusion.flash.messaging.CFStreamingNIOAMFEndPoint

secure-nio-amf-stream

coldfusion.flash.messaging.SecureCFStreamingNIOAMFEndPoint

  • In ColdFusion 10, a channel-definition construct has been introduced in services-config.xml (CF_root/wwroot/WEB-INF/flex/) named serialize-array-to-arraycollection.This construct provides more flexibility and control for users to decide whether to serialize the ColdFusion array to ActionScript Array or ArrayCollection.To serialize, in the XML, set the value to true for the following:<serialize-array-to-arraycollection>false</serialize-array-to-arraycollection>

    Note: This construct is not considered when ColdFusion Array is sent to LCDS Flex Client. In this case, ColdFusion Array always gets translated to ActionScript ArrayCollection.

     

  • All the other files that need to be referenced from services-config.xml are now included in services-config.xml.
    In ColdFusion 8, the services-config.xml files looked similar to the following:

<channel-definition id="cf-polling-amf" class="mx.messaging.channels.AMFChannel">
<endpoint url="http://{server.name}:{server.port}{context.root}/
flex2gateway/cfamfpolling" class="flex.messaging.endpoints.AMFEndpoint"/>
<properties>
<polling-enabled>true</polling-enabled>
<serialization>
<instantiate-types>false</instantiate-types>
</serialization>
</properties>
</channel-definition>

<channel-definition id="cf-rtmp" class="mx.messaging.channels.RTMPChannel">
<endpoint url="rtmp://{server.name}:2048" class="flex.messaging.endpoints.RTMPEndpoint"/>
<properties>
<idle-timeout-minutes>20</idle-timeout-minutes>
<serialization>
<!-- This must be turned off for any CF channel -->
<instantiate-types>false</instantiate-types>
</serialization>
</properties>
</channel-definition>

The new services-config.xml file looks similar to this:

<channel-definition id="cf-polling-amf "class="mx.messaging.channels.AMFChannel">
<endpoint uri="http://{server.name}:{server.port}{context.root}
/flex2gateway/cfamfpolling" class="coldfusion.flash.messaging.CFAMFEndPoint" />
<properties>
<polling-enabled>true</polling-enabled>
<polli ng-interval-seconds>8</polling-interval-seconds>
<serialization>
<enable-small-messages>false</enable-small-messages>
</serialization>
<coldfusion>
<access>
<use-mappings>true</use-mappings>
<method-access-level>remote</method-access-level>
</access>
<use-accessors>true</use-accessors>
<use-structs>false</use-structs>
<property-case>
<force-cfc-lowercase>false</force-cfc-lowercase>
<force-query-lowercase>false</force-query-lowercase>
<force-struct-lowercase>false</force-struct-lowercase>
</property-case>
</coldfusion>
</properties>
</channel-definition>
<channel-definition id="cf-rtmp" class="mx.messaging.channels.RTMPChannel">
<endpoint uri="rtmp://{server.name}:2048" class="coldfusion.flash.messaging.CFRTMPEndPoint"/>
<properties>
<idle-timeout-minutes>20</idle-timeout-minutes>
<serialization>
<enable-small-messages>false</enable-small-messages>
</serialization>
<coldfusion>
<access>
<use-mappings>true</use-mappings>
<method-access-level>remote</method-access-level>
</access>
<use-accessors>true</use-accessors>
<use-structs>false</use-structs>
<property-case>
<force-cfc-lowercase>false</force-cfc-lowercase>
<force-query-lowercase>false</force-query-lowercase>
<force-struct-lowercase>false</force-struct-lowercase>
</property-case>
</coldfusion>
</properties>
</channel-definition>

Specifying ColdFusion-specific channel definitions

LiveCycle Data Services ES transports messages to and from destinations over message channels that are part of the Flex messaging system. When you configure a destination, you reference the messaging channels to use. To connect to a ColdFusion back-end application, ensure that the services-config.xml file contains definitions for the cf-polling-amf channel and the cf-rtmp channel in the channels section. If you are running LiveCycle Data Services ES in ColdFusion, the services-config.xml file is in the wwwroot\WEB-INF\flex directory and contains the channel definitions by default. If you are running LiveCycle Data Services ES remotely, the services-config.xml file is located in the under \WEB-INF\flex directory when you install LiveCycle Data Services ES in the default location.
The new channel definitions include the following:

<channel-definition id="cf-polling-amf" class="mx.messaging.channels.AMFChannel ">
<endpoint uri="http://{server.name}:{server.port}{context.root}
/flex2gateway/cfamfpolling"class="coldfusion.flash.messaging.CFAMFEndPoint" />
<properties>
<polling-enabled> true </polling-enabled>
<polling-interval-seconds>8</polling-interval-seconds>
<serialization>
<enable-small-messages>false</enable-small-messages>
</serialization>
<coldfusion>
<access>
<use-mappings>true</use-mappings>
<method-access-level>remote</method-access-level>
</access>
<use-accessors>true</use-accessors>
<use-structs>false</use-structs>
<property-case>
<force-cfc-lowercase>false</force-cfc-lowercase>
<force-query-lowercase>false</force-query-lowercase>
<force-struct-lowercase>false</force-struct-lowercase>
</property-case>
</coldfusion>
</properties>
</channel-definition>

 

Element

Description

access

Define the resolution rules and access level of the CFC being invoked

use-accessors

Whether the Value Object CFC has getters and setters. Set the value of use-accessors to true if there are getters and setters in the Value Object CFC. However, if you set use-accessors to true and there are no getters and setters in the value object CFC, ColdFusion sets the value of any property of the value object CFC in the this scope. If your CFC does not have any getters and setters, you can increase performance by setting this to false so that ColdFusion does not spend time looking for these methods. The default value is true.

use-structs

Whether to translate ActionScript to CFCs. Set the value of use-structs to true if you don't require any translation of ActionScript to CFCs. The assembler can still return structures to Flex, even if the value is false. The default value is false.

force-cfc-lowercaseforce-query-lowercaseforce-struct-lowercase

Whether to make property names, query column names, and structure keys lowercase when converting to ActionScript. Query column names must precisely match the case of the corresponding ActionScript variables. The default value is false.

use-mappings

A Boolean value specifying whether the source attribute can be relative to (start with) a ColdFusion mapping. The default value is true.

method-access-level

Specifies the access attribute values a CFC must have for ColdFusion to respond to the request. The following values are valid:

  • remote Flex can access only functions that specify remote access. (the default)
  • public Flex can access functions that specify both remote or public access.

Specifying the ColdFusion Data Service adapter

Flex provides adapters to connect to various back-end applications. To use the ColdFusion Data Service adapter, you specify it in the data management configuration file by copying the following adapter-definition to the adapters section of the data-management-config.xml file that is in the WEB-INF/flex folder of the server on which you want to run the Flex application. If you are running LiveCycle Data Services ES in ColdFusion, the data-management-config.xml file contains the adapter definitions by default.
The adapter definition includes the following line:

<adapter-definition id="coldfusion-dao" class="coldfusion.flex.CFDataServicesAdapter"/>

Specifying a destination

A destination is the server-side service or object that you call. You configure Data Management destinations in the data-management-config.xml file. 
The destination contains the following elements:

Element

Description

destination id

The ID must be unique for each destination.

adapter-ref

The name of the adapter to use. You use the ColdFusion adapter-ref element for any ColdFusion specific destinations.

channels-ref

Use the ColdFusion configured channels that have the instantiate-types flag set to false.

component

The name or path on the ColdFusion server.

scope

The scope, which can be application, session, or request. The application value specifies that there is only one instance; request specifies that there is a new CFC for each call. ColdFusion does not support session. (Do not confuse this setting with the ColdFusion variable scope; they are not related.)

hostname

The host name or IP address of the ColdFusion host. If you are running LiveCycle Data Services as part of ColdFusion you do not specify a host name or IP address; however, if you are running LiveCycle Data Services ES remotely, specify a host name or IP address.

identity

The ID of the ColdFusion Data Management server as configured in the ColdFusion Administrator.This is required only if you are accessing a ColdFusion server remotely using RMI and have more than one instance of ColdFusion on a machine.

remote-usernameremote-password

Credentials to pass to the assembler CFC for all clients. It is preferable to use the ActionScript setRemoteCredentials() API on the client.

identity property

The property or list of properties that are the primary key in the database.

query-row-type

Optional. If the assembler fill method returns a query, define an ActionScript type for each row in the query that the ArrayCollection returned.

fill-method

Whether to update the results of a fill operation after a create or update operation.

use-fill-contains

Optional. Whether the assembler has a fill-contains method. This method is used to determine whether to refresh the fill. If the specified method returns true, the fill is re-executed after a create or update operation. Set use-fill-contains to true only when auto-refresh is set to true. The default value is false.

auto-refresh

Optional. Whether to refresh the fill after a create or update operation. The default value is true.

ordered

Optional. Whether order is important for this filled collection. Allows performance optimization when order is not important. The default value is true.

The following code shows a sample destination:

<destination id="cfcontact">
<!-- Use the ColdFusion adapter for any CF specific destinations-->
<adapter ref="coldfusion-dao" />
<channels>
<channel ref="cf-polling-amf" />
</channels>

<properties>
<!--The component name or path on the CF server-->
<component>samples.contact.ContactAssembler</component>
<!--Either "application" or "request"-->
<scope>request</scope>
<!-- The hostname or IP address of the CF host. If Data Services is installed as
part of CF, you omit this. If Data Services runs outside of CF, you must
define this. <hostname>localhost</hostname>-->

<!--This is the ID of the ColdFusion Data Management service as configured in
the ColdFusion Administrator. Only needed if you have more than one instance of
CF on a machine and Data Services is not installed as part of CF.
<identity>default</identity> -->
<!--Credentials to pass to the assembler CFC for all clients. Generally better
to use setRemoteCredentials() API on client <remote-username></remote-username>
<remote-password></remote-password>-->
<metadata>
<identity property="contactId" />
<!--Optional, If the Assembler fill routine returns a query,you must define an
Actionscript type for the rows.-->
<query-row-type>samples.contact.Contact</query-row-type>
</metadata>

<network>
<!-- Add network elements here-->
</network>

<server>
<!-- The method declarations are ignored for CFC Assemblers, with the exception of
the fill-method settings. No parameters are defined here, unlike Java. Any arguments
provided via the AS call are passed along to the CFC, just use optional arguments
when defining the CFC.-->
<fill-method>
<!--Does the assembler have a "fill-contains" method? This method is used to
determine whether to refresh the fill. If the specified method returns true the fill
is re-executed after a create or update. Auto-refresh determines if the fill is
always refreshed if not specified. May only be used when auto-refresh is true.
Optional. Default is false.-->
<use-fill-contains>false</use-fill-contains>
<!-- Determines whether to refresh the fill on updates or creates. Optional. Default
value is true.-->
<auto-refresh>true</auto-refresh>
<!--Determines whether order is important for this filled collection. Allows for
performance optimization when order is not important. Optional. Default value is
true.-->

<ordered>true</ordered>

</fill-method>
</server>
</properties>
</destination>

Enabling ColdFusion-specific debugging output

You enable ColdFusion-specific debugging output in the Flex console by adding the following <pattern> tag in the <filters> tag in the logging section in the services-config.xml file:

<pattern>DataService.coldfusion</pattern>

For more information, see "Configuring the Data Service" in Developing Flex Applications, which is included in the Flex documentation.

Note: The ColdFusion Administrator lets you enable or disable LiveCycle Data Management support. If you are running more than one instance of ColdFusion, use a unique ID to specify each instance of ColdFusion for which you enable LiveCycle Data Management support. You do so by specifying the identity in the identity element in the data-management-config.xml file.

Get help faster and easier

New user?