Developing Flex Applications

lcds.book Page 1 Thursday, July 26, 2007 10:11 AM

Adobe® LiveCycle® Data Services ES Developer’s Guide


© 2007 Adobe Systems Incorporated. All rights reserved. Adobe® LiveCycle® Data Services ES Developer’s Guide If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA Adobe, the Adobe logo, Flex, Flex Builder, Flash Player, and LiveCycle are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. ActiveX and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Linux is a registered trademark of Linus Torvalds. Solaris is a registered trademark or trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States.


Contents

Chapter 1: About LiveCycle Data Services ES Documentation. . 15 Using this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Accessing related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Viewing online documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

PART 1: DEVELOPING DATA SERVICES APPLICATIONS Chapter 2: Taking the LiveCycle Data Services ES Test Drive. . 19 Getting started with the Test Drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 About the Test Drive sample applications . . . . . . . . . . . . . . . . . . . . . . . . 19 Sample 1: Accessing data using an HTTP service . . . . . . . . . . . . . . 20 Sample 2: Accessing data using a web service . . . . . . . . . . . . . . . . 20 Sample 3: Accessing data using Java RPC. . . . . . . . . . . . . . . . . . . . 20 Sample 4: Flex Programming Model 101 . . . . . . . . . . . . . . . . . . . . . . 20 Sample 5: Updating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Sample 6: Publish-subscribe messaging (data push use case) . . . 21 Sample 7: Publish-subscribe messaging (collaboration use case) . 21 Sample 8: Data Management Service . . . . . . . . . . . . . . . . . . . . . . . . 22 Chapter 3: Understanding LiveCycle Data Services ES . . . . . . 23 About LiveCycle Data Services ES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 About RPC services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Using RPC components with LiveCycle Data Services ES . . . . . . 25 About data management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 About messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Using LiveCycle Data Services ES with Adobe Flex Builder . . . . . . . .27 Chapter 4: Using the Messaging Framework . . . . . . . . . . . . . . . 29 Configuring message channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Using RTMP and secure RTMP channels . . . . . . . . . . . . . . . . . . . . . . 31 Using AMF and secure AMF channels . . . . . . . . . . . . . . . . . . . . . . . . 33 Using HTTP and secure HTTP channels . . . . . . . . . . . . . . . . . . . . . . 34

3


Configuring channel endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Working with session data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Using custom error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Chapter 5: Understanding RPC Components . . . . . . . . . . . . . . . .43 About RPC components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 RemoteObject components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 WebService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 HTTPService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Example: An RPC component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Handling results of RPC operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Comparing the RPC feature to other technologies . . . . . . . . . . . . . . . . 49 Client-side processing and server-side processing . . . . . . . . . . . . . 49 Data source access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Flash Professional data management . . . . . . . . . . . . . . . . . . . . . . . . . 50 Chapter 6: Creating RPC Clients . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Declaring an RPC component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Using an RPC component with a server-side destination . . . . . . . . 54 Configuring a destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Using a service without server-side configuration . . . . . . . . . . . . . . . 58 Calling a service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Using explicit parameter passing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Using parameter binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Setting properties for RemoteObject methods or WebService operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 Calling services in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 Handling service results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Handling results as XML with the e4x result format . . . . . . . . . . . . . 75 Binding a service result to other objects . . . . . . . . . . . . . . . . . . . . . . . 79 Handling result and fault events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Using a service with binding, validation, and event listeners . . . . . . . . 87 Handling asynchronous calls to services . . . . . . . . . . . . . . . . . . . . . . . . . 88 Using the Asynchronous Completion Token design pattern . . . . . . 89 Making a service call when another call is completed . . . . . . . . . . . 90 Using features specific to RemoteObject components . . . . . . . . . . . . 91 Accessing Java objects in the source path . . . . . . . . . . . . . . . . . . . . . 91 Accessing EJBs and other objects in JNDI . . . . . . . . . . . . . . . . . . . . 91 Reserved method names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Using features specific to WebService components . . . . . . . . . . . . . . 93 Reading WSDL documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 RPC-oriented operations and document-oriented operations . . . . 95 Stateful web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

4

Contents


Working with SOAP headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Chapter 7: Configuring RPC Services on the Server . . . . . . . . . 101 Understanding destination configuration . . . . . . . . . . . . . . . . . . . . . . . . 101 Message channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 Destination adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Default HTTP service destination . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Configuring destination properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104 Remote object properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104 Web service properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105 HTTP service properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106 Configuring the Proxy Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Chapter 8: Understanding Flex Messaging . . . . . . . . . . . . . . . . . 109 About messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 Using messaging in an application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Understanding the messaging architecture . . . . . . . . . . . . . . . . . . . . . . 112 Message Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Message channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 JMS message adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Chapter 9: Creating Messaging Clients . . . . . . . . . . . . . . . . . . . . 115 Using messaging in a Flex application. . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Working with Producer components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Creating a Producer component in MXML . . . . . . . . . . . . . . . . . . . . 116 Creating a Producer component in ActionScript . . . . . . . . . . . . . . . 118 Sending a message to a destination . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Adding extra information to a message . . . . . . . . . . . . . . . . . . . . . . .120 Resending messages and timing out requests . . . . . . . . . . . . . . . . . 121 Working with Consumer components . . . . . . . . . . . . . . . . . . . . . . . . . . .122 Creating a Consumer component in MXML . . . . . . . . . . . . . . . . . . .122 Creating a Consumer component in ActionScript . . . . . . . . . . . . . . 123 Subscribing to a destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 Filtering messages with a message selector . . . . . . . . . . . . . . . . . . .124 Using subtopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Using a pair of Producer and Consumer components in an application 131 Chapter 10: Configuring Messaging on the Server . . . . . . . . . . . 135 Understanding Message Service configuration . . . . . . . . . . . . . . . . . .135 Message Service destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Message channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Contents

5


Message Service adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Configuring Message Service destinations . . . . . . . . . . . . . . . . . . . . . . 138 Referencing message channels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Setting network properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Setting server properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Referencing Message Service adapters . . . . . . . . . . . . . . . . . . . . . . .141 Configuring the JMS adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Creating a custom Message Service adapter . . . . . . . . . . . . . . . . . . . . 146 Chapter 11: Understanding Data Management . . . . . . . . . . . . . . 149 About the Data Management Service. . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Comparing the Data Management Service and RPC approaches . . 150 Understanding the flow of data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Resolving data synchronization conflicts . . . . . . . . . . . . . . . . . . . . . 152 Securing data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Working with managed collections on the client . . . . . . . . . . . . . . . 153 Maintaining object identities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Chapter 12: Creating Distributed Data Clients . . . . . . . . . . . . . . 157 Creating a distributed data application . . . . . . . . . . . . . . . . . . . . . . . . . . 157 How the Data Management Service works . . . . . . . . . . . . . . . . . . . 158 Creating a DataService component . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Filling and releasing data from an ArrayCollection . . . . . . . . . . . . . 159 Working with single data items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 About the DataStore object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Connecting and disconnecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Caching data locally and offline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Automatically routing data messages. . . . . . . . . . . . . . . . . . . . . . . . . 172 Manually routing data messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Handling errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Controlling whether clients receive pushed changes . . . . . . . . . . . 175 Controlling pushed changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Providing authorization information . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Mapping client-side objects to Java objects . . . . . . . . . . . . . . . . . . . . . 177 Handling data synchronization conflicts. . . . . . . . . . . . . . . . . . . . . . . . . 180 Chapter 13: Configuring Data Management on the Server . . . . 183 About Data Management Service configuration . . . . . . . . . . . . . . . . . Data Management Service destinations . . . . . . . . . . . . . . . . . . . . . . Message channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Management Service data adapters. . . . . . . . . . . . . . . . . . . . .

6

Contents

184 185 185 186


Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186 Configuring Data Management Service destinations. . . . . . . . . . . . . .186 Referencing message channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Configuring network elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Using transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Uniquely identifying data items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189 Caching data items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190 Synchronizing data automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Chapter 14: Working with Data Adapters and Assemblers . . . . 193 Understanding data adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193 Using the Java adapter and assemblers . . . . . . . . . . . . . . . . . . . . . . . . .194 Using custom assemblers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194 Using the Hibernate assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Using the SQL assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Using the ActionScript object adapter. . . . . . . . . . . . . . . . . . . . . . . . . . 236 Managing hierarchical collections . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Using on-demand paging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251 Pushing data changes from the server to clients. . . . . . . . . . . . . . . . . 252 Chapter 15: Using Factories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Using the factory mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Chapter 16: Serializing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Serializing between ActionScript and Java . . . . . . . . . . . . . . . . . . . . . 259 Converting data from ActionScript to Java . . . . . . . . . . . . . . . . . . . 259 Explicitly mapping ActionScript and Java objects . . . . . . . . . . . . . 263 Converting data from Java to ActionScript . . . . . . . . . . . . . . . . . . . 265 Configuring AMF serialization on a channel . . . . . . . . . . . . . . . . . . 266 Using custom serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Chapter 17: Generating PDF Documents . . . . . . . . . . . . . . . . . . 273 About the PDF generation feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Using the PDF generation feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Writing the remote object (Java) class . . . . . . . . . . . . . . . . . . . . . . . 278 Configuring a Remoting Service destination . . . . . . . . . . . . . . . . . . 280 Chapter 18: Integrating Flex Applications with Portal Servers 283 Using a portal server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 Enabling a portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Caching of producer portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Contents

7


Deploying on a portal server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288 Deploying with a LiveCycle Data Services ES web application . .289 Deploying without a LiveCycle Data Services ES web application . . 289 Deploying on JBoss Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289 Deploying on WebLogic Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 Deploying on WebSphere Portal 5.1 or WAS 6.0 . . . . . . . . . . . . . .292 Chapter 19: Setting Quality of Service for Message Delivery . 295 About the quality of service feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 Using a custom queue processor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296 Creating a custom queue processor . . . . . . . . . . . . . . . . . . . . . . . . . . 297 Configuring a custom queue processor . . . . . . . . . . . . . . . . . . . . . . . 301 Chapter 20: Using Flex with JSP . . . . . . . . . . . . . . . . . . . . . . . . 303 About the Flex 2 Tag Library for JSP . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Using the Flex 2 Tag Library for JSP . . . . . . . . . . . . . . . . . . . . . . . . . . 304 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 Flex 2 Tag Library for JSP reference . . . . . . . . . . . . . . . . . . . . . . . . .307 Chapter 21: Using AJAX Data Services . . . . . . . . . . . . . . . . . . . 309 About AJAX Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 When to use AJAX Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Requirements for using AJAX Data Services. . . . . . . . . . . . . . . . . . 310 Running the AJAX Data Service sample . . . . . . . . . . . . . . . . . . . . . . 310 Using AJAX Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 Initializing AJAX Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Reading data with AJAX Data Services . . . . . . . . . . . . . . . . . . . . . . 313 Updating data with AJAX Data Services . . . . . . . . . . . . . . . . . . . . . . 315 FDMSLibrary methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Limitations of AJAX Data Services. . . . . . . . . . . . . . . . . . . . . . . . . . . 316 AJAX Data Services API reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Chapter 22: Using the Flex AJAX Bridge . . . . . . . . . . . . . . . . . 329 About the Flex AJAX Bridge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329 When to use the Flex AJAX Bridge . . . . . . . . . . . . . . . . . . . . . . . . . 330 Requirements for using the AJAX Bridge . . . . . . . . . . . . . . . . . . . . 330 Running the AJAX Bridge samples . . . . . . . . . . . . . . . . . . . . . . . . . 330 Using the AJAX Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Automatic memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . .333 Manually destroying objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333 Handling exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333 Limitations of the AJAX Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334

8

Contents


Chapter 23: Using Run-Time Configuration . . . . . . . . . . . . . . . 335 About run-time configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Configuring components with a bootstrap service . . . . . . . . . . . . . . . 337 Configuring components with a remote object . . . . . . . . . . . . . . . . . . 340 Using assemblers with run-time configuration. . . . . . . . . . . . . . . . . . . 342 Accessing dynamic components with a Flex client application . . . . 343 Chapter 24: Building Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 347 About the Flex development tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Compilers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 Loggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 About application files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Component classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 SWC files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Other assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 Chapter 25: Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . 353 Installation directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 LiveCycle Data Services ES installation directory structure . . . . 354 Flex 2 SDK installation directory structure . . . . . . . . . . . . . . . . . . . 354 Flex Builder installation directory structure . . . . . . . . . . . . . . . . . . . 355 Development directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 Flex file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 LiveCycle Data Services ES application directory structure . . . . 356 Flex 2 SDK directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Compiling an application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 About case sensitivity during a compile . . . . . . . . . . . . . . . . . . . . . . 366 Compiling a LiveCycle Data Services ES application . . . . . . . . . . 366 Compiling a Flex 2 SDK application . . . . . . . . . . . . . . . . . . . . . . . . . 366 Compiling a Flex Builder application . . . . . . . . . . . . . . . . . . . . . . . . . 368 Deployment directory structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 LiveCycle Data Services ES deployment directory structure . . . 368 Flex 2 SDK deployment directory structure . . . . . . . . . . . . . . . . . . 369 Chapter 26: Using the Flex Compilers . . . . . . . . . . . . . . . . . . . . . 371 About the Flex compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 About the application compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 About the component compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 About the command-line compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Command-line syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Contents

9


Using abbreviated option names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 Invoking the command-line compilers with Java . . . . . . . . . . . . . . . 381 About configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382 Locating configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382 Configuration file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383 About option precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386 Using the application compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 About the application compiler options . . . . . . . . . . . . . . . . . . . . . . .388 Basic example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Adding metadata to SWF files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Setting the file encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Editing application settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Using SWC files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 About incremental compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Using the component compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407 About the component compiler options. . . . . . . . . . . . . . . . . . . . . . .407 Compiling stand-alone components and classes . . . . . . . . . . . . . 409 Compiling components in packages. . . . . . . . . . . . . . . . . . . . . . . . . . 412 Compiling components using namespaces . . . . . . . . . . . . . . . . . . . 413 Adding utility classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 Adding nonsource classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Creating themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 Viewing errors and warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 Viewing warnings and errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 About deprecation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 About logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 About SWC files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 About included SWC files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .422 Distributing SWC files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .422 Using components in SWC files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423 About manifest files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423 Chapter 27: Using the Command-line Debugger . . . . . . . . . . . 425 About debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Using the command-line debugger. . . . . . . . . . . . . . . . . . . . . . . . . . .426 Command-line debugger limitations. . . . . . . . . . . . . . . . . . . . . . . . . .426 Command-line debugger shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . 427 Using the default browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 About the source files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428 Invoking the command-line debugger . . . . . . . . . . . . . . . . . . . . . . . . . .428 Starting a session with the stand-alone debugger version of Flash Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428 Starting a session in a browser with LiveCycle Data Services ES . . 429

10

Contents


Starting a session in a browser without LiveCycle Data Services ES 430 Configuring the command-line debugger . . . . . . . . . . . . . . . . . . . . . . . .431 Using the command-line debugger commands. . . . . . . . . . . . . . . . . . 432 Running the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 Setting breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 Accessing commands from a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Changing data values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 Viewing file contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 Printing stack traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 Getting status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 Handling faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 Getting help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 Terminating the session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

PART 2: ADMINISTERING DATA SERVICES APPLICATIONS Chapter 28: Using Configuration Files . . . . . . . . . . . . . . . . . . . . 447 About configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Application and server terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Applying license keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 Root variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 Configuration files layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 Flex 2 SDK configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .451 Command-line compiler configuration . . . . . . . . . . . . . . . . . . . . . . . .451 JVM configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 LiveCycle Data Services ES configuration. . . . . . . . . . . . . . . . . . . . . . 453 Compiler configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 JVM configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 Data services configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 Servlet configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 Logging configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 Server-side caching configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 Production mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 Configuring mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 Configuring directory browsing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 Flash Player configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 Chapter 29: Configuring Data Services . . . . . . . . . . . . . . . . . . . 465 About service configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 Securing destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 Passing credentials from client-side components . . . . . . . . . . . . . 477 Passing credentials to a remote service . . . . . . . . . . . . . . . . . . . . . . 478

Contents

11


Basic authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .479 Login adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 Using software clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 Processing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .484 Defining and referencing a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . .484 Monitoring and managing services . . . . . . . . . . . . . . . . . . . . . . . . . . . . .486 MBean creation and registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .486 MBean naming conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 Creating a custom MBean for a custom ServiceAdapter class . .488 About data services class loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 Web-tier compiler class loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 Data services class loading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 Using data services without the web-tier compiler . . . . . . . . . . . . 490 Chapter 30: Deploying Flex Applications . . . . . . . . . . . . . . . . . . 491 About deploying an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Deployment options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 Deploying Flex 2 SDK applications . . . . . . . . . . . . . . . . . . . . . . . . . 492 Deploying LiveCycle Data Services ES applications . . . . . . . . . . 495 Compiling for deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Enabling accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Preventing users from viewing your source code . . . . . . . . . . . . . 499 Enabling production mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 Disabling incremental compilation . . . . . . . . . . . . . . . . . . . . . . . . . . 499 Using a headless server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 Deployment checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 Types of network access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 Step 1. Create a list of server-side resources . . . . . . . . . . . . . . . . . 502 Step 2. Verify access from server to server inside your firewall . 503 Step 3. Verify access to your servers from outside the firewall . 503 Step 4. Configure the proxy server . . . . . . . . . . . . . . . . . . . . . . . . . . 504 Step 5. Create a cross-domain policy file . . . . . . . . . . . . . . . . . . . . 504 Chapter 31: Creating a Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . 507 About the wrapper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .507 About the Flex Builder wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 About the wrapper generated by LiveCycle Data Services ES . 508 About the HTML templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 Creating a wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 About the HTML page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 About the JavaScript file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 Adding features to the wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 Customizing the wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 Adding Express Install to your wrapper . . . . . . . . . . . . . . . . . . . . . . . 517

12

Contents


Adding history management to your wrapper . . . . . . . . . . . . . . . . . . 517 About the and tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 Unsupported properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 Requesting an MXML file without the wrapper . . . . . . . . . . . . . . . . . . 529 Chapter 32: Using Express Install. . . . . . . . . . . . . . . . . . . . . . . . . 531 About Express Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531 Editing your wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 Adding Express Install script to the wrapper . . . . . . . . . . . . . . . . . . 532 Understanding the Express Install script . . . . . . . . . . . . . . . . . . . . . 535 Configuring Express Install on LiveCycle Data Services ES . . . . . . 536 Alternatives to Express Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Chapter 33: Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 About logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 Using the debugger version of Flash Player . . . . . . . . . . . . . . . . . . . . . .541 Configuring the debugger version of Flash Player . . . . . . . . . . . . . 542 Determining Flash Player version in Flex . . . . . . . . . . . . . . . . . . . . . 544 Client-side logging and debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Configuring the debugger version of Flash Player to record trace() output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Using the global trace() method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Using the Logging API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 Compiler logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 Web-tier logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 Configuring web application logging . . . . . . . . . . . . . . . . . . . . . . . . . 559 Configuring web-tier compiler logging . . . . . . . . . . . . . . . . . . . . . . . .561 Server-side service logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 Chapter 34: Applying Flex Security . . . . . . . . . . . . . . . . . . . . . . 567 About the Flex security model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 Declarative and programmatic security approaches compared . 568 Client security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 Server security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 Loading assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Data compared to content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Loading remote assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Loading local assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Using J2EE authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 Using container-based authentication . . . . . . . . . . . . . . . . . . . . . . . 583 Using authentication to control access to Flex applications . . . . 584 Using secured services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Making other connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

Contents

13


Using RTMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 Using sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 Using the LocalConnection class . . . . . . . . . . . . . . . . . . . . . . . . . . . .588 Using SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .588 Using secure endpoints with LiveCycle Data Services ES . . . . . .589 Using secure endpoints without LiveCycle Data Services ES . . 590 Writing secure Flex applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 MXML tags with security restrictions . . . . . . . . . . . . . . . . . . . . . . . . 590 Disabling viewSourceURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 Remove sensitive information from SWF files . . . . . . . . . . . . . . . . . 591 Input validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 Using passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Storing persistent data with the SharedObject class . . . . . . . . . . 596 Configuring client security settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 About the mm.cfg file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 About the mms.cfg file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 About FlashPlayerTrust files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 Using the Settings Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .598 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 Chapter 35: Configuring JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 About JRun application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 Limitations of the JRun application server . . . . . . . . . . . . . . . . . . . . 601 About the default web applications. . . . . . . . . . . . . . . . . . . . . . . . . . 602 Starting and stopping JRun servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 Adding and removing servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 Configuring JRun servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606 Changing port numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606 Creating a web application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 Configuring the hot-deploy feature . . . . . . . . . . . . . . . . . . . . . . . . . . 608 Using virtual directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 Enabling and disabling directory browsing . . . . . . . . . . . . . . . . . . . 609 Configuring JRun logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 Using the sniffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

14

Contents


CHAPTER 1

1

About LiveCycle Data Services ES Documentation Adobe LiveCycle Data Services ES Developer’s Guide provides the tools for you to develop applications by using Adobe® LiveCycle® Data Services Enterprise Suite. It also provides information about the server-side administration of LiveCycle Data Services ES. This manual is intended for application developers who are learning LiveCycle Data Services ES or want to extend their programming knowledge for that component.

Contents Using this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Accessing related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Using this manual This manual can help anyone who is developing LiveCycle Data Services ES applications. However, this manual is most useful if you have basic experience using Adobe® Flex™, or have read Getting Started with Flex 2. Getting Started with Flex 2 provides an introduction to Flex and helps you develop the basic knowledge that makes using this manual easier.

Accessing related documentation The Flex documentation is designed to provide support for the complete spectrum of participants. It includes the following titles: Book

Description

Flex 2 Developer’s Guide

Describes how to develop Flex client applications.

Getting Started with Flex 2

Contains an overview of Flex features and application development procedures.

Building and Deploying Flex 2 Applications

Describes how to build and deploy Flex applications.

15


Book

Description

Creating and Extending Flex 2 Components

Describes how to create and extend Flex components.

Migrating Applications to Flex 2

Provides an overview of the migration process, as well as detailed descriptions of changes in Flex and ActionScript™.

Using Flex Builder 2

Contains comprehensive information about all Adobe® Flex™ Builder™ 2 features, for every level of Flex Builder users.

Adobe Flex 2 Language Reference

Provides descriptions, syntax, usage, and code examples for the Flex API.

Viewing online documentation All LiveCycle Data Services ES and Flex documentation is available online in HTML and Adobe® Portable Document Format (PDF) files from the Adobe website. It is also available from the Adobe Flex Builder Help menu.

Typographical conventions The following typographical conventions are used in this book: ■

Italic font indicates a value that should be replaced (for example, in a folder path).

■

Code font indicates

code.

■

Code font italic

indicates a parameter.

■

Boldface font indicates a verbatim entry.

16

About LiveCycle Data Services ES Documentation


PART 1

Developing Data Services Applications

1

The following topics describe how to develop Data Services applications: Chapter 2: Taking the LiveCycle Data Services ES Test Drive . . 19 Chapter 3: Understanding LiveCycle Data Services ES . . . . . . . .23 Chapter 4: Using the Messaging Framework. . . . . . . . . . . . . . . . . .29 Chapter 5: Understanding RPC Components . . . . . . . . . . . . . . . . .43 Chapter 6: Creating RPC Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Chapter 7: Configuring RPC Services on the Server . . . . . . . . . . 101 Chapter 8: Understanding Flex Messaging . . . . . . . . . . . . . . . . . . 109 Chapter 9: Creating Messaging Clients. . . . . . . . . . . . . . . . . . . . . . 115 Chapter 10: Configuring Messaging on the Server . . . . . . . . . . . . 135 Chapter 11: Understanding Data Management . . . . . . . . . . . . . . . 149 Chapter 12: Creating Distributed Data Clients . . . . . . . . . . . . . . . . 157 Chapter 13: Configuring Data Management on the Server . . . . . 183 Chapter 14: Working with Data Adapters and Assemblers . . . . . 193 Chapter 15: Using Factories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Chapter 16: Serializing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Chapter 17: Generating PDF Documents . . . . . . . . . . . . . . . . . . . 273 Chapter 18: Integrating Flex Applications with Portal Servers . 283 Chapter 19: Setting Quality of Service for Message Delivery . . 295 Chapter 20: Using Flex with JSP . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Chapter 21: Using AJAX Data Services . . . . . . . . . . . . . . . . . . . . 309 Chapter 22: Using the Flex AJAX Bridge . . . . . . . . . . . . . . . . . . . 329 Chapter 23: Using Run-Time Configuration. . . . . . . . . . . . . . . . . 335 Chapter 24: Building Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Chapter 25: Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Chapter 26: Using the Flex Compilers. . . . . . . . . . . . . . . . . . . . . . . 371 Chapter 27: Using the Command-line Debugger . . . . . . . . . . . . 425

17



CHAPTER 2

2

Taking the LiveCycle Data Services ES Test Drive To learn more about how Adobe LiveCycle Data Services ES works and what it can do, you can take the LiveCycle Data Services ES Test Drive. The Test Drive includes some sample applications that demonstrate basic features and best practices for developing applications with LiveCycle Data Services ES.

Contents Getting started with the Test Drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 About the Test Drive sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Getting started with the Test Drive Before you begin the LiveCycle Data Services ES Test Drive, you should be familiar with the Adobe Flex programming environment and how to use Flex to build rich Internet applications. For more information, see the Flex 2 Developer’s Guide. You must install LiveCycle Data Services ES to access the Test Drive. For installation instructions, see http://www.adobe.com/go/lcds_installation[ After you start the Integrated LiveCycle Data Services ES server, open a browser and go to http://:/samples. A link to the Test Drive appears at the top of the page. The page also includes links to other sample applications.

About the Test Drive sample applications The Test Drive includes several sample applications: a catalog with mobile phone product information (one with text only, and the other with images), and a chat client.

19


Sample 1: Accessing data using an HTTP service You can use the HTTPService component to send and receive HTTP requests by using HTTP GET or POST. The HTTPService component consumes different types of responses, but typically you use it to consume XML. HTTPService calls are asynchronous. You also use the component with any kind of server-side technology, such as JSP, Servlet, ASP, Ruby on Rails, and PHP. In the sample, when you click the Get Data button, the data grid is populated with XML data returned by a JSP file. It shows built-in data grid features such as sortable and movable columns. You can click the column head to sort data in ascending or descending order. Drag a column head to move a column of data to another location in the grid. You can also increase or decrease the width of the columns from the header row.

Sample 2: Accessing data using a web service With the WebService component, you can invoke SOAP-based web services deployed on your application server or the Internet. WebService component calls are also asynchronous. The sample also uses data grid column definitions. When you click the Get Data button, the grid is populated with data returned by a web service.

Sample 3: Accessing data using Java RPC Like HTTPService and WebService components, Java RPC calls are also asynchronous. With the RemoteObject component, you can directly invoke methods of Java objects deployed in your application server, and consume the return value. The return values can be a primitive data type, an object, a collection of objects, or an object graph. In the sample, when you click the Get Data button, the grid is populated with data returned by the getProducts() method of the ProductService Java class.

Sample 4: Flex Programming Model 101 Like in any other object-oriented programming language, a Flex application is made of a collection of classes. Using Flex, you can create classes using MXML or ActionScript. You typically create view classes in MXML, and Model and Controller classes in ActionScript. After you define a class, you can use it programmatically or declaratively (as a tag in MXML) without the need for an additional descriptor file. Public properties are automatically available as tag attributes.

20

Taking the LiveCycle Data Services ES Test Drive


In this sample, basic Flex features are displayed. When you click an image in the Catalog panel on the left side of the page, more information appears in the Product Details panel on the right.

Sample 5: Updating data In this sample, you can update data from one panel of data and see the changes quickly displayed in another panel. The panel on the left shows a data grid with sortable, movable columns. When you click on a row in the Catalog panel on the left, detailed information about that item appears in Details panel on the right. In the Details panel you can modify data in any field, click Update, and the change is passed from the client side to the server side.

Sample 6: Publish-subscribe messaging (data push use case) Flex supports publish-subscribe messaging through the LiveCycle Data Services ES Message Service. The Message Service manages a set of destinations that Flex clients can publish and subscribe to. Flex provides two components, Producer and Consumer, that you use to publish and subscribe to a destination, respectively. In the example, a Java component publishes simulated real-time values to a message queue. The Flex client subscribes to that queue and displays the values in real time. Click the Subscribe To 'Feed' destination button. Pushed values appear in the text field. Click the Unsubscribe To 'Feed' destination button to stop the feed.

Sample 7: Publish-subscribe messaging (collaboration use case) The sample builds on the concepts and APIs introduced in sample 6. The messaging and realtime infrastructure available in Flex lets you build collaboration and data push applications to in a scalable and reliable manner while preserving the lightweight web deployment model. Open the sample application in two different browser windows. Enter a message in the Send box at the lower edge of the page, and click the Send button. The message appears in the Chat windows in both clients.

About the Test Drive sample applications

21


Sample 8: Data Management Service In addition to the RPC services described in samples 1, 2, and 3, Data Management Service provides a different approach to synchronize data across tiers and between clients. You do not have to track changes to the data, or invoke remote services to notify the back end of the changes (such as create, update, delete) to the client side. The Data Management Service consists of a client-side API and server-side services. On the client side, the DataService component tracks changes to the data, and notifies the back end of the changes. On the server side, the Data Management Service receives the list of changes and passes it to server-side persistence components. Data Management Service also pushes the changes to other clients. In the sample, you can test persistence of the data, and the movable, sortable columns. After you click the Get Data button, the data grid is populated with data. Click in a cell, modify the data, and press Enter. The new value appears in that cell and the cursor jumps to the cell below it. You can also test data synchronization across clients. To do this, open the sample application in a second browser window and resize so you can see both. Modify data in one browser, and press Enter. Notice that the update is automatically pushed to the other browser window.

22

Taking the LiveCycle Data Services ES Test Drive


CHAPTER 3

3

Understanding LiveCycle Data Services ES Adobe LiveCycle Data Services ES provides powerful features for using external data in an Adobe Flex application. LiveCycle Data Services ES runs on standard J2EE platforms and servlet containers.

Contents About LiveCycle Data Services ES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 About RPC services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 About data management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 About messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Using LiveCycle Data Services ES with Adobe Flex Builder . . . . . . . . . . . . . . . . . . . 27

About LiveCycle Data Services ES LiveCycle Data Services ES provides a comprehensive set of data-enabling features, which are deployed in a Java web application. LiveCycle Data Services ES provides a messaging infrastructure for building data-rich Flex applications. This infrastructure underlies the LiveCycle Data Services ES features that are designed for moving data to and from applications: RPC services, the Data Management Service, and the Message Service.

23


The following table describes the types of services provided in LiveCycle Data Services ES: Services

Description

RPC services

Provides a call and response model for accessing external data. Lets you create applications that make asynchronous requests to remote services that process the requests, and then return data to your Flex application. For more information, see “About RPC services” on page 24.

Data Management Service

Provides data synchronization between application tiers, real-time data updates, on-demand data paging, data replication, occasionally connected application services, and integration with data sources through adapters. Lets you create applications that work with distributed data, and lets you manage large collections of data and nested data relationships, such as one-to-one and one-to-many relationships. For more information, see “About data management” on page 26.

Message Service Provides messaging services for collaborative and real-time applications. Lets you create applications that can send messages to and receive messages from other applications, including Flex applications and Java Message Service (JMS) applications. For more information, see “About messaging” on page 26.

About RPC services The RPC services are designed for applications in which a call and response model is a good choice for accessing external data. These services let you make asynchronous requests to remote services that process the requests, and then return data directly to your Flex application. A client-side RPC component, which you can create in MXML or ActionScript, calls a remote service, and then stores response data from the service in an ActionScript object from which you can easily obtain the data. The implementation of an RPC service can be an HTTP URL, which uses HTTP POST or GET; a SOAP-compliant web service; or a Java object in a Java web application. The client-side RPC components are the HTTPService, WebService, and RemoteObject components.

24

Understanding LiveCycle Data Services ES


The following diagram provides a simplified view of how RPC components interact with RPC services: Client tier User interface

HTTPService component - Send and receive data using HTTP GET or POST WebService component - Interact with web services using SOAP over HTTP RemoteObject component - Invoke methods on remote Java objects Result

Request

Data format: AMF, SOAP, or HTTP

RPC service implementations: Java object, web service, other

Resource tier

Server tier

Using RPC components with LiveCycle Data Services ES You use LiveCycle Data Services ES with RPC components when you provide enterprise functionality, such as proxying of service traffic from different domains, client authentication, whitelists of permitted RPC service URLs, server-side logging, localization support, and centralized management of RPC services. LiveCycle Data Services ES lets you use RemoteObject components to access remote Java objects without configuring them as SOAPcompliant web services; using Flex 2 SDK without LiveCycle Data Services ES or ColdFusion does not provide this functionality. When you use LiveCycle Data Services ES, instead of contacting services directly, RPC components contact destinations. Destinations are manageable service endpoints that you manage through a server-side XML-based configuration file.

About RPC services

25


You can use Flex 2 SDK without LiveCycle Data Services ES to create nonenterprise applications that call HTTP services or web services directly, without going through a serverside proxy service. You cannot use RemoteObject components without LiveCycle Data Services ES or ColdFusion. By default, Adobe Flash Player blocks access to any host that is not exactly equal to the one used to load an application. Therefore, if you do not use LiveCycle Data Services ES to proxy requests, an RPC service must either be on the server hosting your application, or the remote server that hosts the RPC service must define a crossdomain.xml file. A crossdomain.xml file is an XML file that provides a way for a server to indicate that its data and documents are available to SWF files served from certain domains, or from all domains. The crossdomain.xml file must be in the web root of the server that the Flex application is contacting. For more information, see Chapter 5, “Understanding RPC Components,” on page 43.

About data management The Data Management Service is a part of LiveCycle Data Services ES that lets you create applications that work with distributed data. By using the Data Management Service, you build applications that provide data synchronization, data replication, on-demand data paging, and occasionally connected application services. Additionally, you can manage large collections of data and nested data relationships, such as one-to-one and one-to-many relationships, and use data adapters to integrate with data resources. A client-side DataService component, which you can create in MXML or ActionScript, calls methods on a server-side Data Management Service destination to perform such activities as filling client-side data collections with data from remote data sources and synchronizing the client and server versions of data. For more information, see Chapter 11, “Understanding Data Management,” on page 149.

About messaging The messaging capability in LiveCycle Data Services ES is built on the same underlying messaging infrastructure as the RPC services and Data Management Service. By using messaging components, you create collaborative and real-time messaging applications. These components provide a client-side API for passing text and objects to and from messaging clients, and server-side configuration of message destinations.

26



You can create messaging components in MXML or ActionScript that connect to server-side message destinations, send messages to those destinations, and receive messages from other messaging clients. Components that send messages are called producers, and those that receive messages are called consumers. Messages are sent over transport channels, which use specific transport protocols, such as the Real-Time Messaging Protocol (RTMP) and Action Message Format (AMF). Messaging clients can be Flex applications or other types of applications, such as Java Message Service (JMS) applications. JMS is a Java API that lets applications create, send, receive, and read messages. JMS applications can publish and subscribe to the same message destinations as Flex applications. However, you can create a wide variety of messaging applications using just Flex messaging. For more information, see Chapter 8, “Understanding Flex Messaging,” on page 109.

Using LiveCycle Data Services ES with Adobe Flex Builder Flex Builder offers two ways to work with LiveCycle Data Services ES. You can either compile an application in Flex Builder or you can save your uncompiled application (MXML file) to a LiveCycle Data Services ES web application on the server and compile the application when the page is viewed. When you compile a LiveCycle Data Services ES project in Flex Builder, Flex Builder automatically saves the compiled application (SWF file) to a LiveCycle Data Services ES web application on the server whenever you compile the application. N OTE

You have several options for configuring a LiveCycle Data Services ES project in Flex Builder; select New > Flex Project, and select the configuration option in the Create A Flex Project dialog box.

When you create a LiveCycle Data Services ES project in Flex Builder, Flex Builder either creates a directory with same name as your project or uses an existing directory that has that name. That directory is a subdirectory of the root folder that you specify. A default application file (MXML file) of the same name is also created. Optionally, you can set a different MXML files as the default application file. N OTE

To set the default application file, select the file in the Flex Builder Navigator tree and right-click the Set As Default Application option.

Using LiveCycle Data Services ES with Adobe Flex Builder

27


For applications that compile locally, Flex Builder saves MXML files in the local Flex Builder project directory and saves SWF files and HTML wrapper files on the server. Creating a project that compiles locally is a good idea if you plan to deploy your finished application as a SWF file and HTML wrapper file rather than an MXML file. For applications that compile on the server, MXML files are saved on the server. No HTML wrapper file is generated and saved when the application is compiled. When using a Flex Builder project for a LiveCycle Data Services ES application, you manage resources such as server-side Java classes just as you do when not using Flex Builder. You can specify the location of additional client-side source files, such as ActionScript classes, in the source path panel of the Flex Builder project properties dialog; by default, Flex Builder includes the WEB-INF\flex\user_classes directory for applications that compile on the server. N OTE

Regardless of which option you choose for a LiveCycle Data Services ES project in Flex Builder, you must specify a valid LiveCycle Data Services ES root folder and root URL. These values should map the root of a LiveCycle Data Services ES web application. Before compiling your Flex application in Flex Builder, you must start the corresponding LiveCycle Data Services ES web application.

For more information about Flex Builder projects, see the Working with Projects topic in Using Flex Builder 2.

28



CHAPTER 4

4

Using the Messaging Framework Adobe LiveCycle Data Services ES uses a common messaging framework for all types of data services, including the Message Service, Proxy Service, Remoting Service, and Data Management Service. Some aspects of this messaging framework apply to all types of data services.

Contents Configuring message channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Working with session data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Using custom error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Configuring message channels LiveCycle Data Services ES transports messages to and from service destinations over message channels that are part of the Flex messaging system. You can pair any type of service with any type of channel. LiveCycle Data Services ES includes support for AMF, HTTP, and RTMP channels and for secure AMF, HTTP, and RTMP channels. If you require data security, use one of the secure channels. The secure AMF and HTTP channels transport data by using HTTP over Secure Socket Layer (HTTPS). The secure RTMP channel transports data by using RTMP over Transport Layer Security (TLS), which is called RTMPS. You create channel definitions in the Data Services configuration file. The endpoint URL of each channel definition must be unique. You can configure an AMF or HTTP polling channel to repeatedly poll the AMF or HTTP endpoint to create client-pull message consumers. The interval at which the polling occurs is configurable on the channel. You can also manually poll by calling the polling() method of a channel for which polling is enabled; for example, you might want set the polling interval to a high number so that the channel does not automatically poll, and call the polling() method to poll manually based on an event, such as a button click.

51


The following example shows an AMF channel definition. The channel configuration is preceded by a destination that references it. ... ... ... ... ...

You can also assign channels on the client at run time by creating a ChannelSet object that contains one or more Channel objects, and assigning the ChannelSet to a service component, as the following MXML example shows: ... ...

The following example shows ActionScript code creating a ChannelSet: ... // Create a ChannelSet. var cs:ChannelSet = new ChannelSet(); // Create a Channel. var customChannel:Channel = new AMFChannel("my-polling-amf", endpointUrl); // Add the Channel to the ChannelSet. cs.addChannel(customChannel); // Assign the ChannelSet to a RemoteObject instance. myRemoteObject.channelSet = cs; ...

52

Using the Messaging Framework


When you configure channels at run time, you can dynamically control the endpoint URL. You can add any number of Channel objects to a ChannelSet; the ChannelSet object searches through the set to find a channel to which it can connect. It is a best practice to specify an id property that the destination recognizes, but you can pass null to skip id property checking. In addition to the searching behavior provided by the ChannelSet class, the Channel class defines a failoverURIs property. This property lets you configure a Channel object in ActionScript that causes failover across this array of endpoint URLs when it tries to connect to its destination. The connection process involves searching for the first channel and trying to connect to it. If this fails, and the channel defines failover URIs, each is attempted before the channel gives up and the ChannelSet object searches for the next available channel. If no channel in the set can connect, any pending unsent messages generate faults on the client.

Using RTMP and secure RTMP channels You use the standard and secure RTMP channels to connect to an RTMP endpoint that supports real-time messaging and server-pushed broadcasts. You can also configure these channels for near–real-time messaging. RTMPT connections are HTTP connections for the client to the server over which RTMP data is tunneled. When a direct RTMP connection is unavailable, the standard and secure channels use RTMPT and tunneled RTMPS connections, respectively, on the RTMP endpoint. Because of the RTMPT fallback strategy, existing applications that define a set of channels for a destination where an AMF polling channel is used as fallback for an RTMP channel, no longer need to do so. Applications can instead reference the single RTMP channel, and it falls back to RTMPT or tunneled RTMPS internally on the client automatically when necessary. N OTE

You cannot use server.port or context.root tokens in RTMP endpoint configuration. You can use the server.name token, but not when using clustering. If you have a firewall in place, you must open the port that you assign to the RTMP endpoint to allow RTMP traffic.

RTMP channel Use a standard RTMP channel only when transmitting data that does not require security. The following example shows an RTMP channel definition: 20

Configuring message channels

53


The optional max-worker-threads element in the properties section of a RTMP channel definition lets you set a fixed RTMP endpoint worker pool size. The default behavior is to use a cached thread pool that increases as needed with no upper limit. The following example shows a max-worker-threads element: 10 ...

You can use the optional rtmpt-poll-wait-millis-on-client element when clients are connected over RTMPT while performing adaptive polling. After receiving a server response, clients wait for an absolute time interval before issuing the next poll request rather than using an exponential back-off up to a maximum poll wait time of 4 seconds. Allowed values are integers in the range of 0 to 4000, for example: 0

Secure RTMP channel Use the secure RTMP channel to connect to the RTMP endpoint over Transport Layer Security (TLS). This channel supports real-time messaging and server-pushed broadcasts. This channel falls back to tunneled RTMPS when a direct connection is unavailable. The secure RTMP channel requires a digital certificate, and contains child elements for specifying a keystore filename and password. The following example shows a secure RTMP channel definition. The location of the keystore file may be different. 30 C:/somedir/flex/dataservices/apps/j2ee/dev/WEBINF/flex/keys/server.keystore password

54



You can create public and private key pairs and self-signed certificates with the Java keytool utility. The user name of self-signed certificates must be set to localhost or the IP address on which the RTMPS endpoint is available. For information about key and certificate creation and management, see the Java keytool documentation at http://java.sun.com. Optionally, you can store a keystore password in a separate file, possibly on removable media. You must specify only one keystore-password or keystore-password-file. The following example shows a keystore-password-file element: a:\password

You can also specify an alternate JVM algorithm instead of the default JVM algorithm when using SSL. The default JVM algorithm can be controlled by using the ssl.KeyManagerFactory.algorithm security property. In general, you should use the default algorithm and this property can be omitted. The following values are valid: ■

Default

explicitly uses the default JVM algorithm.

■

SunX509

uses the Sun algorithm; requires the Sun security

provider. ■

IbmX509

uses the IBM algorithm; requires the IBM security

provider.

Using AMF and secure AMF channels You use AMF-based channels to send AMF-encoded messages to the AMF endpoint, which supports AMF requests and responses sent over HTTP. You can use the AMF channel, the polling AMF channel, or the secure AMF channel. You can configure these channels for near–real-time messaging by setting specific endpoint properties; for more information, see “Configuring channel endpoints” on page 35.

AMF channel The following example shows an AMF channel definition:


55


Polling AMF channel When you use the polling AMF channel for publish-subscribe messaging, you set the polling property to true in the channel definition. You can also configure the polling interval in the channel definition. The following example shows an AMF polling channel definition with polling enabled: true 8

Secure AMF channel The secure AMF channel is similar to the AMF channel, but uses HTTPS instead of HTTP. It uses a different endpoint and class than the AMF channel. The following example shows a secure AMF channel definition:

Using HTTP and secure HTTP channels You use the HTTP and secure HTTP channels to connect to the HTTP endpoint, which supports HTTP requests and responses. These channels use a text-based (XML) message format. You can configure these channels for near–real-time messaging by setting specific endpoint properties; for more information, see “Configuring channel endpoints” on page 35.

HTTP channel The following example shows an HTTP channel definition:

56



You should not use types that implement the IExternalizable interface (used for custom serialization) with the HTTP channel if precise by-reference serialization is required; when you do this, references between recurring objects are lost and appear to be cloned at the endpoint. For more information about the IExternalizable interface, see Chapter 16, “Serializing Data,” on page 259. You can specify a URL in the redirectURL property in the properties section of a channel definition when using HTTP-based channel endpoints. This is a legacy feature that lets you redirect a request to another URL if the MIME type of the request wasn't correct.

Secure HTTP channel The secure HTTP channel is similar to the HTTP channel, but you use HTTPS instead of HTTP. Uses a different channel class than the HTTP channel. The following example shows a secure HTTP channel definition:

Configuring channel endpoints Using near–real-time messaging on HTTP and AMF endpoints As an alternative to using an RTMP channel, you can establish near–real-time messaging for any channel that uses an HTTP or AMF endpoint by setting the polling-enabled, polling-interval-millis, and wait-interval-millis properties in a channel definition. This applies to the HTTP, AMF, and polling AMF channels, and the secure HTTP and secure AMF channels. This is a viable alternative to using an RTMP channel when you only expect the number of client connections to be somewhere between 100 and 500. To achieve near–real-time messaging, set the following properties in the properties section of a channel definition in the services-config.xml file: property to true to enable polling.

■

polling-enabled

■

polling-interval-millis

property to 0 (zero). This is the number of milliseconds

between client poll request. ■

property to -1. This is the number of milliseconds that the server thread responding to a client poll request waits for messages from that client. wait-interval-millis


57


■

max-waiting-poll-requests property

to a value that is at least 10 less than the number of application server request-handling threads. How you set or determine the maximum number of threads for your application server depends on application server that you use; for more information, see your application server documentation.

When you use these settings, the client polls once and because the wait-interval is set to -1, the server waits to respond if there are no messages available and responds as soon as it has messages for the client. Using different settings for these properties results in different behavior. For example, setting the wait-interval-millis property to 0 (zero) and setting the polling-interval-millis property to a non-zero positive value results in normal polling. Setting the wait-intervalmillis property to a high value reduces the number of poll messages that the server needs to process, but you are limited by the number of threads on the server. The following example shows an AMF channel definition configured for near–real-time messaging: true 0 -1 0

Securing HTTP and RTMP endpoints You can protect HTTP-based and RTMP- based channel endpoints by using whitelists and blacklists that list specific firewall, router, or web server IP addresses. A whitelist contains client IP addresses that are permitted to access endpoints. A blacklist contains client IP addresses that are restricted from accessing endpoints.

58



The blacklist takes precedence over the whitelist in the event that the client IP address is a member of both the whitelist and blacklist. The whitelist and blacklist elements can contain 0-N ip-address and/or ip-addresspattern elements. The ip-address element supports simple IP address matching, allowing individual bytes in the address to be designated as a wildcard by using an asterisk character (*). The ip-address-pattern element supports regular expression pattern matching of IP addresses. This allows for powerful range-based IP address filtering. The following example shows a whitelist and a blacklist: 237.* 10.132.64.63 10.60.147.* 10\\.132\\.17\\.5[0-9]{1,2}

By default, the RTMP server that an RTMP endpoint starts up binds to all local network interface cards (NICs) on the specified port; the port is based on the endpoint URL. You can specify a xxx.xxx.xxx.xxx element in the RTMP channel's properties section to bind the RTMP server to a specific local NIC on startup. You use this element when your computer has an internally facing NIC and a public NIC. You can bind the RTMP server to just the internal NIC, for example, to protect it from public access. You can also use the config property to connect to a public port on a firewall or load balancer that forwards traffic to an internal port. This lets RTMP work smoothly with hardware load balancers or proxies that require access to the RTMP server over a standard port, but when the hop from the load balancer to the RTMP server must be a nonstandard port. By default, the RTMP server's accept socket uses a server platform default to control the size of the queue of pending connections to accept. You can use the accept-backlog element in the RTMP channel's properties section to control the size of this queue.

Working with session data LiveCycle Data Services ES provides the following classes for working with session data. These classes are included in the public LiveCycle Data Services ES Javadoc documentation. ■

flex.messaging.FlexContext

■

flex.messaging.FlexSession

Working with session data

59


■

flex.messaging.FlexSessionListener

■

flex.messaging.FlexSessionAttributeListener

■

flex.messaging.FlexSessionBindingEvent

■

flex.messaging.FlexSessionBindingListener

The FlexContext class is useful for getting access to the session and the HTTP pieces of the session, such as the HTTP servlet request and response. This lets you access HTTP data when you use a Flex application in the context of a larger web application where other classes, such as JSPs or Struts actions, might have stored information. The FlexSession class provides access to an ID and also provides setAttribute and functionality. This is useful for storing data on the server that doesn't have to go back to the client. However, FlexSession is not cluster-aware; if a client connects to a different server in the cluster, the client receives a new FlexSession. Nothing stored in the FlexSession attributes is persisted for clustering purposes. Consider the following caveats when using FlexSession: getAttribute

■

When using an RTMP channel, the FlexSession does not remain after a browser refresh, but it does remain when using an AMF or HTTP channel.

■

When using an RTMP channel, a FlexSession's attributes are not shared with other channels, but they are shared when using an AMF or HTTP channel.

■

When using an RTMP channel with authentication, you must log in again after a browser refresh, but this is not necessary when using an AMF or HTTP channel.

■

When using an RTMP channel with authentication, you must log in again after switching to an AMF or an HTTP channel.

The FlexSessionListener class is useful for monitoring who is connected. You add a listener by using the static method to track new connections being made. You receive a reference to the session that was added. Each session can then report when it is destroyed to those same listeners. You use this for monitoring connections that close, and also to clean up resources. The following example shows a Java class that calls FlexContext.getHttpRequest() to get an HTTPServletRequest object and calls FlexContext.getFlexSession() to get a FlexSession object. By exposing this class as a remote object, you can make it accessible to a Flex client application; you place the compiled class in the WEB_INF/classes directory or your LiveCycle Data Services ES web application. package myROPackage; import import import import import

60

flex.messaging.*; java.io.*; java.util.*; javax.servlet.*; javax.servlet.http.*;



public class SessionRO { public HttpServletRequest request; public FlexSession session; public UsefulRemoteObject() { request = FlexContext.getHttpRequest(); session = FlexContext.getFlexSession(); } public String getSessionId() throws Exception { String s = new String(); s = (String) session.getId(); return s; } public String getHeader(String h) throws Exception { String s = new String(); s = (String) request.getHeader(h); return h + "=" + s; } }

The following example shows a Remoting Service destination definition that exposes the SessionRO class as a remote object. You add this destination definition to your Remoting Service configuration file. ... myROPackage.SessionRO ...

The following examples shows an ActionScript snippet for calling the remote object from a Flex client application. You place this code inside a method declaration. ... ro = new RemoteObject(); ro.destination = "myRODestination"; ro.getSessionId.addEventListener("result", getSessionIdResultHandler); ro.getSessionId(); ...

Working with session data

61


Using custom error handling For use cases where you return additional information to the client as part of a message exception, you can use the extendedData property of the flex.messaging.MessageException class. This property is a HashMap, and provides a flexible way to return additional data to the client when a failure occurs. The public LiveCycle Data Services ES Javadoc documentation includes documentation for the flex.messaging.MessageException class. N OTE

LiveCycle Data Services ES serialization provides bean serialization of any Throwable type. This gives you the option of throwing your own Throwable exceptions with getters for the properties that you send to the client.

The following example shows a Java test class that adds extra data to an exception: package errorhandling; import java.util.HashMap; import java.util.Map; import flex.messaging.MessageException; public class TestException { public String generateMessageExceptionWithExtendedData(String extraData) { MessageException me = new MessageException("Testing extendedData."); Map extendedData = new HashMap(); // The method that invokes this expects an "extraData" slot in // this map. extendedData.put("extraData", extraData); me.setExtendedData(extendedData); me.setCode("999"); me.setDetails("Some custom details."); throw me; } }

The following example shows an ActionScript method that generates an exception with extra data:

Using custom error handling

63


64



CHAPTER 5

5

Understanding RPC Components Adobe Flex remote procedure call (RPC) components. Flex RPC components are based on a service-oriented architecture (SOA). RPC components let you interact with server-side RPC services to provide data to your applications. You can access data through HTTP (HTTP services), SOAP (web services), or Java objects (remote object services). Another common name for an HTTP service is a REST-style web service. REST stands for Representational State Transfer and is an architectural style for distributed hypermedia systems. For more information about REST, see www.ics.uci.edu/ ~fielding/pubs/dissertation/rest_arch_style.htm. In a typical Flex application, an RPC component sends data as input to one or more RPC services. When an RPC service executes, it returns its results data to the RPC component that made the request.

Contents About RPC components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Example: An RPC component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Handling results of RPC operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Comparing the RPC feature to other technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

About RPC components You can use Flex RPC components in MXML or ActionScript to work with three types of RPC services: remote object services, web services, and HTTP services. When you use LiveCycle Data Services ES, you also contact destinations, which are RPC services that have corresponding server-side configurations that provide server-proxied access.

43


The following diagram provides a simplified view of how RPC components interact with RPC services: Client tier User interface

HTTPService component - Send and receive data using HTTP GET or POST WebService component - Interact with web services RemoteObject component - Interact with Java objects Result

Request

RPC service implementations: Java object, web service, other

Resource tier

Server tier

The following list describes some key considerations when you are creating an application that uses LiveCycle Data Services ES to call an RPC service: 1.

What is the best type of service to use? For more information, see “RemoteObject components” on page 45, “WebService components” on page 45, and “HTTPService components” on page 46.

2.

What is the best way to pass data to a service? For more information, see “Calling a service” on page 59.

3.

How do you want to handle data results from a service? For more information, see “Handling service results” on page 75.

4.

How can you debug your code that uses RPC components? For more information, see “Server-side service logging” on page 562.

5.

What security measures can or should you implement? For more information, see “Securing destinations” on page 475.

44

Understanding RPC Components


RemoteObject components RemoteObject components let you access the methods of server-side Java objects, without manually configuring the objects as web services. You can use RemoteObject components in MXML or ActionScript. You can use RemoteObject components with a stand-alone LiveCycle Data Services ES web application or Macromedia® ColdFusion® MX 7.0.2 from Adobe. When using a LiveCycle Data Services ES web application, you configure the objects that you want to access as Remoting Service destinations in a LiveCycle Data Services ES configuration file or by using LiveCycle Data Services ES run-time configuration. For information on using RemoteObject components with ColdFusion, see the ColdFusion documentation. You can use a RemoteObject component instead of a WebService component when objects are not already published as web services, web services are not used in your environment, or you would rather use Java objects than web services. You can use a RemoteObject component to connect to a local Java object that is in the LiveCycle Data Services ES or ColdFusion web application source path. When you use a RemoteObject tag, data is passed between your application and the serverside object in the binary Action Message Format (AMF) format. For more information about using RemoteObject components, see Chapter 6, “Creating RPC Clients,” on page 51.

WebService components WebService components let you access web services, which are software modules with methods, commonly referred to as operations; web service interfaces are defined by using XML. Web services provide a standards-compliant way for software modules that are running on a variety of platforms to interact with each other. For more information about web services, see the web services section of the World Wide Web Consortium's website at www.w3.org/2002/ws/. Flex applications can interact with web services that define their interfaces in a Web Services Description Language (WSDL) document, which is available as a URL. WSDL is a standard format for describing the messages that a web service understands, the format of its responses to those messages, the protocols that the web service supports, and where to send messages. Flex supports WSDL 1.1, which is described at www.w3.org/TR/wsdl. Flex supports both RPC-encoded and document-literal web services.

About RPC components

45


Flex applications support web service requests and results that are formatted as SOAP messages and are transported over HTTP. SOAP provides the definition of the XML-based format that you can use for exchanging structured and typed information between a web service client, such as a Flex application, and a web service. You can use a WebService component to connect to a SOAP-compliant web service when web services are an established standard in your environment. WebService components are also useful for objects that are within an enterprise environment, but not necessarily available to the Flex web application's source path. For more information about using WebService components, see Chapter 6, “Creating RPC Clients,” on page 51.

HTTPService components HTTPService components let you send HTTP GET, POST, HEAD, OPTIONS, PUT, TRACE or DELETE requests, and include data from HTTP responses in a Flex application. Flex does not support mulitpart form POSTs. An HTTP service can be any HTTP URI that accepts HTTP requests and sends responses. Another common name for this type of service is a REST-style web service. REST stands for Representational State Transfer and is an architectural style for distributed hypermedia systems. For more information about REST, see www.ics.uci.edu/~fielding/pubs/dissertation/ rest_arch_style.htm. HTTPService components are a good option when you cannot expose the same functionality as a SOAP web service or a remote object service. For example, you can use HTTPService components to interact with JavaServer Pages (JSPs), servlets, and ASP pages that are not available as web services or Remoting Service destinations. You can use an HTTPService component for CGI-like interaction in which you use HTTP GET, POST, HEAD, OPTIONS, PUT, TRACE, or DELETE to send a request to a specified URI. When you call the HTTPService object's send() method, it makes an HTTP request to the specified URI, and an HTTP response is returned. Optionally, you can pass arguments to the specified URI.

46



Example: An RPC component The following example shows MXML code for a RemoteObject component that connects to a Remoting Service destination, sends a request to the data source in the click event of a Button control, and displays the result data in the text property of a TextArea control. The value in the curly braces ({ }) in the TextArea control is a binding expression that copies service results data into the text property of the TextArea control:

The following example shows the corresponding Remoting Service destination that is defined in the remoting-config.xml file on the server. The source value is a Java class that is in the web application classpath. flex.samples.myRO

For more information, see Chapter 6, “Creating RPC Clients,” on page 51.

Example: An RPC component

47


Handling results of RPC operations The Example: An RPC component topic shows how you can use data binding with the result of an asynchronous operation to display the result automatically when it is received from the server. This approach prevents you from having to write code to handle the result. Instead, when the remoteService.getData() operation updates its lastResult property, the TextArea component is notified through a PropertyChangeEvent. It then updates its display automatically. However, in some cases, you do need to handle asynchronous results. For these cases, note that calling remoteService.getData(inputText.text) returns an AsyncToken object that you can use to be notified of the returned result, as the following ActionScript code snippet shows: import mx.rpc.AsyncToken; import mx.rpc.AsyncResponder; …. var token:AsyncToken = remoteService.getData(inputText.text); // you can set additional properties on the token // to pass data to your handlers … token.info = token.addResponder(new AsyncResponder(myResultHandler, myFaultHandler, token)); ….. private function myResultHandler(event:Object, token:AsyncToken):void{ var resultEvent:ResultEvent = ResultEvent(event); //… Include result handler code here } private function myFaultHandler(event:Object, token:AsyncToken):void{ var faultEvent:FaultEvent = FaultEvent(event); // Include fault handler code here. } ...

When the remote service returns a valid result, the myResultHandler() method is called with the ResultEvent event passed in. If the remote service fails, the myFaultHandler() method is called. Note that some properties are assigned to the token after the call to the remote service is made. In a multi-threaded language, there would be a race condition where the result might come back before the token is assigned. This is not a problem in ActionScript because the remote call cannot be initiated until the currently executing code finishes. Alternatively, you can listen for ResultEvent and FaultEvent events at the service level. This approach is similar to using the token, but all remote calls made with the same service use the same result and fault handlers.

48



Comparing the RPC feature to other technologies The way that Flex works with data sources and data is different from other web application environments, such as JSP, ASP, and ColdFusion. Data access in Flex applications also differs significantly from data access in applications that are created in Flash Professional.

Client-side processing and server-side processing Unlike a set of HTML templates created using JSPs and servlets, ASP, or CFML, the files in a Flex application are compiled into a binary SWF file that is sent to the client. When a Flex application makes a request to an external service, the SWF file is not recompiled and no page refresh is required. The following example shows MXML code for calling a web service. When a user clicks the Button control, client-side code calls the web service, and result data is returned into the binary SWF file without a page refresh. The result data is then available to use as dynamic content within the application.

The following example shows JSP code for calling a web service using a JSP custom tag. When a user requests this JSP, the web service request is made on the server instead of on the client, and the result is used to generate content in the HTML page. The application server regenerates the entire HTML page before sending it back to the user's web browser.

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

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

Flash Professional data management Flash Professional and Flex 2 provide different data management architectures. These architectures were developed to meet the needs of the respective authoring environments and user communities. Flash Professional provides a set of data components designed for use in the Flash Professional authoring environment. Although some of the functionality of these components overlaps with features found in Flex, they are not based on the same architecture. Flash Professional also has its own data-binding feature that works in conjunction with the Flash Professional components, and is a completely different feature than Flex data binding.

50



CHAPTER 6

6

Creating RPC Clients Adobe Flex supports a service-oriented architecture in which a Flex application interacts with remote data sources by calling several types of services and receiving responses from the services. In a typical Flex application, client-side RPC components send asynchronous requests to remote services, which return result data to the client-side components. For introductory information about RPC components, see Chapter 5, “Understanding RPC Components,” on page 43.

Contents Declaring an RPC component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Configuring a destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Calling a service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Setting properties for RemoteObject methods or WebService operations . . . . . . .71 Handling service results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Using a service with binding, validation, and event listeners . . . . . . . . . . . . . . . . . . . 87 Handling asynchronous calls to services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Using features specific to RemoteObject components . . . . . . . . . . . . . . . . . . . . . . . . 91 Using features specific to WebService components . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Declaring an RPC component You can declare RPC components in MXML or ActionScript to connect to RPC services. If you are not using Adobe LiveCycle Data Services ES, you can use a WebService or HTTPService component to contact an RPC service directly. N OTE

To use RemoteObject components, LiveCycle Data Services ES or Macromedia ColdFusion MX 7.0.2 with the Remoting Update is required.

51


If you are using LiveCycle Data Services ES, you have the option of connecting to RPC services directly by specifying URLs in ActionScript or connecting to destinations defined in the services-config.xml file or a file that it includes by reference. A destination definition is a named service configuration that provides server-proxied access to an RPC service. A destination is the actual service or object that you want to call. A destination for a RemoteObject component is a Java object defined as a Remoting Service destination. A destination for an HTTPService component is a JSP page or another resource accessed over HTTP. A destination for a WebService component is a SOAP-compliant web service. You configure HTTP services and web services as Proxy Service destinations. The following example shows a Proxy Service destination definition for an HTTP service in the proxyconfig.xml file: http://www.mycompany.com/services/myservlet http://www.mycompany.com/services/*

One major difference between Remoting Service destinations and Proxy Service destinations is that you always host the remote Java object in your LiveCycle Data Services ES web application, while you constact a Proxy Service destination through a URL that could be remote or local to the LiveCycle Data Services ES web application. A LiveCycle Data Services ES developer is responsible for writing and compiling the remote object Java class and adding it to the web application classpath by placing in in the classes or lib directory. You can use any plain old Java object (POJO) that is available in the web application classpath as a Remoting Service destination. This technique requires that your class have a zero-argument constructor so that LiveCycle Data Services ES can constuct an instance. You can also use a factory to integrate LiveCycle Data Services ES with a component namespace of components that already exist, or configure LiveCycle Data Services ES to invoke components found in the ServletContext or HttpSession. The following example shows a Remoting Service destination definition the remotingconfig.xml file. The source element specifies the fully qualified name of a class in the web application's classpath. flex.samples.census.CensusService

52

Creating RPC Clients


The following examples shows the corresponding source code of the Java class that is referenced in the destination definition: package flex.samples.census; import import import import import import

java.util.ArrayList; java.util.List; java.sql.Connection; java.sql.PreparedStatement; java.sql.ResultSet; java.sql.SQLException;

import flex.samples.ConnectionHelper; public class CensusService { public List getElements(int begin, int count) { long startTime = System.currentTimeMillis(); Connection c = null; List list = new ArrayList(); String sql = "SELECT id, age, classofworker, education, maritalstatus, race, sex FROM census WHERE id > ? AND id

Developing Flex Applications

Developing Flex Applications

Suggest Documents

Developing Mobile Applications with Flex and Flash Builder 4.6 - Adobe

Developing Mobile Applications with Flex and Flash Builder 4.6

Developing Mobile Applications with Flex and Flash Builder 4.6 - Adobe

Developing Mobile Applications with Flex and Flash Builder

Developing rich Internet applications for SAP® with Adobe® Flex™

Pentesting Adobe Flex Applications

Creating Modular applications in flex

Technical Guide: Upgrading Flex 3 applications to Flex 4 SDK

Building real-time web applications with Flex

Building mobile applications with Flex - jfokus.se

Embedding Flex applications in a web browser

Building Rich Internet Applications with Flex Builder.pdf

Lenovo IdeaPad Flex 14/Flex 14D Flex 15/Flex 15D

Lenovo IdeaPad Flex 14/Flex 14D Flex 15/Flex 15D

Lenovo IdeaPad Flex 14/Flex 14D Flex 15/Flex 15D

Developing ColdFusion 9 Applications

Developing Java Applications

Developing Zen Applications

Developing Enterprise JavaBeans Applications

Developing Web Applications - SERSC

Developing Web Database Applications

Flex

developing ubiquitous computing applications - CiteSeerX

developing ubiquitous computing applications - CiteSeerX