LiveCycle Data Services Introduction

1. LiveCycle Data Services Introduction 4/8/08 Nick Kwiatkowski

2. Want to follow along? • This presentation, and other related materials are available at my blog’s website: • http://quetwo.wordpress.com

3. About Me • Work for Michigan State University as a Telecom Manager (aka, phone guy) • Manager of the Michigan Flex User’s Group • Co-Manager of the Mid-Michigan ColdFusion User’s Group

4. What is LiveCycle Data Services? • LiveCycle Data Services, apart of the LiveCycle ES package is a middle-ware application designed to better connect your client applications to your application server. • Manage large amounts of data • Establish messaging between clients and servers • Help retrieve/store data via Remoting and Proxy configurations.

5. The Middleware Java LiveCycle DS Flex or AJAX application ColdFusion Data .NET AIRApplication PHP Presentation Layer Business Layer Data-Access Layer

6. The Middleware • But you can already connect directly to your application server without LDS! • That is true, however, many features are not available in just the AMF/Remoting situation • LDS cannot talk directly to databases.

7. Other Gotcha’s • LDS is a J2EE application • Requires a server • Requires Java • Often not supported by shared-hosting environments • Licensed software (we will get more into that in a minute) • Fairly difficult to setup (not install) • Paybacks are great, however.

8. LDS Licensing • Small application can make use of LiveCycle Data Services ES Express Edition for FREE. • Limited to 1-CPU • No Clustering of data • Larger Applications need to purchase LDS-ES. • Expect about $10,000 to $15,000 per CPU

9. Free? • Yes, LDS is free for development and deployment for small applications • Including commercial applications. • Adobe is trying to get the ‘large guys’ to pay for everybody’s toy-box. • Available at http://www.adobe.com/products/livecycle/dataservices/ • LCS-Express is included / baked in to ColdFusion 8

10. What LDS brings to the table… • Data Management • Have your application server send large amounts of data to LDS, and let it worry about passing it to the client. This includes pagination of data, and data synchronization. Flex Client LDS App Server

11. What LDS brings to the table… • Data Messaging • Allows Flex clients to communicate with each other without tying up resources on the App server (the App server can participate in these conversations) Flex Client App Server LDS AJAX Client Flex Client

12. What LDS brings to the table… • Data Proxying: • You can proxy your web-service or Remoting calls through your LDS to help get around restrictions in firewalls or policies. Web Service LDS Flex Client App Server

13. Data Management • Data Management is the component of the LiveCycle Data Services suite of services that allows for LDS to help you communicate and control the data to your end user • Allows for Data Synchronization, Data Caching, Data Pagination, and Conflict Resolution.

14. Data Management How it works: • Data is packaged up into ‘Value Objects’, or packages of data. • This usually consists of a “row” of data from a database • Each VO is tracked separately as to who is viewing, editing, etc.

15. Data Management • Users then Subscribe to a set of data. • LDS will then keep track of the state of that data, and send it from the Application Server to the Flex Application. • LDS will ‘listen’ to any changes made to the data in the Flex Client.

16. Data Management • If the Collection that holds the data is changed in the client, LDS will take that change, change the Value Object in memory, send the change to the App server, and update all clients in real-time.

17. Data Management • When an update is sent to the other clients, it will check its local copy, to make sure that record has not changed. If it has, it will issue a “Conflict” event, and allow the Client to choose what to do.

18. Data Management • On the Client, 95% of your work is handled by any of the Collection classes, such as the ArrayCollection • Handles updating LDS with Changes, and notifying other visual components of changes.

19. Data Management • When a DataGrid, or InputBox broadcast the Change event, the ArrayCollection hears it, and updates its own data, and passes the change to other components that subscribe to its change event.

20. Building an Application • We will be building a quick “CMS” application utilizing a DataGrid, and some TextInput boxes. • Backend will be ColdFusion and Access • LiveCycle 2.5 (ColdFusion) will be used • Flex Builder 3 along with Flex 3 SDK

21. Building an App • First, we will want to create a new database file in Access. We will be using the “Contacts” template to create the file. • Normally, we would create a custom database file for this purpose. • If using Access 2007, make sure to save the file as an Access 2003 or Access 2000 file.

22. Building an App • Next, we will want to add the new Database as a ‘Datasource’ in ColdFusion • Named “contact_cms”, using the Access Unicode Driver • Load up Flex Builder, and create a new Flex Project • Web Application, ColdFusion App Server, LiveCycle Data Services

23. Building an App • Create a new folder on the server for the ‘Value Objects’, \bin\cfcs\ • Create a new AS Class folder : \src\ascript • Open the RDS view, and find the Contacts table • Right-Click on Table, ColdFusion Wizards, Create CFC

24. Building an App • CFC Folder: • /contact_cms/bin/cfcs • CFC Package Name: • contact_cms-debug.cfcs • CFC Type: • LiveCycle DS Assembler • Create AS-VO • AS Folder: \src\ascript

25. Building an App • Next, we need to modify the LDS configuration files to tell LDS about the components we just created. • File is in the wwwroot\WEB-INF\Flex\ directory, named data-management-config.xml • Add a new entry (Destination) to represent the component we just created.

26. Building an App • Destination.properties.component • Component dot path on the CF server • Destination.properties.scope • Application or request • Destination.properties.metadata.identity • Set this to the key field in your table • Destination.properties.metadata.query-row-type • This is the path to the ActionScript Value Object we created.

27. Building an App • Restart LiveCycle Data Services, and make sure there are no errors • If using the bundled LDS with ColdFusion, restart the CF Application Service • Now, we just need to create the client, and we are done!

28. Building an App • Open your MXML document, and add a <mx:DataService> tag • Give it an ID, and the Destination that we used in the last step • Add a new ArrayCollection variable (to hold your data) • Add a new function to execute the DataService.fill(arrayCollection);

29. Building an App • Next, add a DataGrid and at the very least, a button to trigger the fill() command. • Bind this DataGrid to your ArrayCollection, and set the editable property to true. • Also, open up the Contacts.as file, and notice the [Managed] metadata. This code tells the AS to broadcast its changes to outside components.

30. (this is where things break) Running the application

31. Running the Application • If you update the data in one application, the data becomes updated in any other instances of the Flex Client, in real time! • What if you wanted to queue the changes, or allow the user to back out of the changes before they occur?

32. Turning off AutoCommit • In order to allow the clients to queue changes, and control when they commit the changes, we need to turn off the AutoCommit feature of the DataService • Add the autoCommit=“false” declaration to the DataService component. • We will now need to add two buttons to allow the user to commit their changes.

33. Turning off AutoCommit • Add two additional buttons: • Name one Apply, with a click event of : dataService.commit(); • Name the second Cancel, with a click event of : dataService.revertChanges();

34. Auto-Commit demo

35. Adding and Removing Items • Adding and removing items to the database is as trivial as adding a new item to the ArrayCollection. • Remember when adding an item, you may need to turn off the AutoCommit feature, as your database may not allow null values. • ArrayCollection.addItem(new className()); • DataService.deleteItem(dgContacts.selectedItem);

36. Conflicts • Another nice thing about Data Management is the ability to have Conflict Resolution built right into your application. • LDS can trigger an event when another user updates a record you are currently updating • Add the “conflict” event handler to the DataService to create your own conflict handler.

37. Conflict • When handling a conflict, you have the option to update with your version, take the server’s version, or to let the user choose what version to keep. • Lets show how to detect a conflict in data sets, notify the end user, overwrite the client’s data with the server’s version.

38. Conflict resolution

39. Fill Queries • Using the ‘out of the box’ data management is great if you want to return full sets of data • But what happens if you want to return only a portion of your full table; for example a search result? • You can customize your fill parameters by modifying your assembler’s Fill() function and passing the fill as the second parameter of the call.

40. Fill Queries • For example: • DataService.fill(ArrayCollection,SearchString:string); • Translates to: • <cffunction name=“fill”> • <cfargument name=“searchString”…./> • </cffunction>

41. Paging • What happens if you have too much data returned from a query to send down to the clients? • For example, do you really want to send 50,000 records down the pipe? • LDS has a built in Paging mechanism!

42. Paging • To configure it, edit your data-management-config.xml file. • Destination.properties.network • <paging enabled=“true” pageSize=“xxx”/> • That is all you have to do!

43. Paging & Queries

44. Questions? nick@theflexgroup.org