LiveCycle Data Services ES Test Drive

In this test drive, you run a series of short sample applications that demonstrate the key features of LiveCycle Data Services ES. We walk you through the source code of each application to highlight the key points of its implementation. The source code for the Test Drive applications is available in WEB-INF/flex-src/flex-src.zip. For example, on a typical Windows installation using the Tomcat integrated server, flex-src.zip is located in
[LCDS ES install]/tomcat/webapps/lcds-samples/WEB-INF/flex-src.

Sample 1: Accessing data using HTTPService

Run the sample:

  1. Click here to run the application
  2. Click "Get Data": The DataGrid is populated with XML data returned by catalog.jsp
  3. Also notice some of the built-in DataGrid features:

Code walkthrough:

Open main.mxml in the testdrive-httpservice/src directory to look at the source code of the application.

Using HTTPService, you can send HTTP requests to a server, and consume the response. Although the HTTPService can be used to consume different types of responses, it is typically used to consume XML. You can use the HTTPService with any kind of server-side technology: JSP, Servlet, ASP, Ruby on Rails, PHP, etc. You specify the target service in the url property of HTTPService.

Flex provides sophisticated data binding capabilities. You can bind the value of a property to the value of another property, or to an expression in general. In this example, the dataProvider property of the DataGrid is bound (using the curly braces notation) to the lastResult property of the HTTPService.

HTTPService calls are asynchronous. The result event is triggered on the HTTPService when the data becomes available to the client application. The fault event is triggered if an error occurs at the server-side, or if the network becomes unavailable. (See sample 5, for an example of coding result and fault event handlers).

By default, the XML document retrieved from the server is deserialized into an object graph. This allows you to navigate through the result using the dot notation. You can also get the result as an XML document by specifying resultFormat="e4x" on the HTTPService. In that case, you can parse the document using E4X (ECMAScript for XML).

The LiveCycle Data Services ES server is not required to use the HTTPService: By default, the application tries to connect directly to the domain specified in the HTTPService url attribute. This will work if one of the two conditions below is satisfied:

  1. The domain specified in the HTTPService url attribute is the domain from where your application was downloaded.
  2. A crossdomain.xml file granting access to your application's originating domain is available on the domain specified in the HTTPService url attribute. More information on crossdomain.xml is available here.

If you want your application to access services available on another domain without deploying a crossdomain.xml file on that domain (for example, because you may not own the target domain), you can set the useProxy attribute of the HTTPService to "true" like in this example. In this case, the request is sent to the LiveCycle Data Services ES proxy which makes the request to the target domain on the client application's behalf. This configuration also provides more control over the access to the service. For example, you may configure the proxy to require authentication before accessing a service, log access to the service, etc.

When using the proxy, you can specify a logical name in the HTTPService destination attribute instead of specifying a hardcoded value in the url attribute. You then map this logical name to an actual URL in WEB-INF/flex/proxy-config.xml. Open WEB-INF/flex/proxy-config.xml to see how the catalog destination is configured.

More info:


Sample 2: Accessing data using Web Services

Run the sample:

  1. Click here to run the application.

    NOTE: Since this application accesses a live web service, you must have a connection to the internet to run it.

  2. Click "Get Data": The DataGrid is populated with data returned by the ProductWS web service hosted on livecycledata.org.

Code walkthrough:

Open main.mxml in the testdrive-webservice/src directory to look at the source code of the application.

Access the wsdl file for the web service used in this example:

Using the WebService tag, you can invoke SOAP-based web services deployed in your application server or on the internet. Objects returned by a web service are automatically deserialized into ActionScript objects. Similarly ActionScript objects passed as arguments to a web service operation are serialized according the wsdl description.

Notice that we also added DataGrid column definitions (using DataGridColumn) in this example.

The LiveCycle Data Services ES server is not required to use the WebService: By default, the application tries to connect directly to the domain specified in the WebService wsdl attribute. This will work if one of the two conditions below is satisfied:

  1. The domain specified in the WebService wsdl attribute is the domain from where your application was downloaded.
  2. A crossdomain.xml file granting access to your application's originating domain is available on the domain specified in the WebService wsdl attribute. More information on crossdomain.xml is available here.

If you want your application to access services available on another domain without deploying a crossdomain.xml file on that domain (for example, because you may not own the target domain), you can set the useProxy attribute of the WebService to "true" like in this example. In this case, the request is sent to the LiveCycle Data Services ES proxy which makes the request to the target domain on the client application's behalf. This configuration also provides more control over the access to the service. For example, you may configure the proxy to require authentication before accessing a service, log access to the service, etc.

When using the proxy, you can specify a logical name in the WebService destination attribute instead of specifying a hardcoded value in the wsdl attribute. You then map this logical name to an actual URL in WEB-INF/flex/proxy-config.xml. Open WEB-INF/flex/proxy-config.xml to see how the ws-catalog destination is configured.

More Info:


Sample 3: Accessing data using Remoting

Run the sample:

  1. Click here to run the application.
  2. Click "Get Data": The DataGrid is populated with data returned by the getProducts() method of the ProductService Java class.

Code walkthrough:

Open main.mxml in the testdrive-remoteobject/src directory to look at the source code of the application.

Open the following files in a text editor to look at the source code for the server side of the application:

Using RemoteObject, you can directly invoke methods of Java objects deployed in your application server, and consume the return value. The return value can be a value of a primitive data type, an object, a collection of objects, an object graph, etc.

The value of the destination property of RemoteObject is a logical name that is mapped to a fully qualified java class in remoting-config.xml.

Java objects returned by server-side methods are deserialized into either dynamic or typed ActionScript objects. In this example, we don't have an explicit ActionScript version of the Product Java class. Product objects are therefore deserialized into dynamic objects. In sample 5, we work with an explicit Product class in ActionScript.

More info:


Sample 4: Flex Programming Model 101

Run the sample:

  1. Click here to run the application.
  2. Click a phone in the list: the details for the selected phone appear in the right panel.

Code walkthrough:

Open the following files in the testdrive-101/src directory to look at the source code of the application:

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.

When you create an mxml file, you are actually creating a class. The root node of the mxml document indicates the class you extend. For example, creating a file named MasterDetail.mxml with an <Application> root node is equivalent to creating an ActionScript class with the following signature:

public class MasterDetail extends Application {

}

Similarly, creating a file named ProductView.mxml with a <Panel> root node is similar to creating a class with the following signature:

public class ProductView extends Panel {

}

Once you have defined a class, you can use it programatically or declaratively (as a tag in MXML) without the need for an additional descriptor file. Public properties are automatically available as tag attributes. For example, in MasterDetail.mxml, we define the <ProductView> tag and bind its product attribute to the selected item in the product list.

Also notice the support for CSS style sheets.


Sample 5: Updating Data

Run the sample:

  1. Click here to run the application.
  2. Select a phone.
  3. Modify some data in the right panel. For example, the price.
  4. Click Update: changes are sent to the back-end and persisted in the database by the ProductService class.

Code walkthrough:

Open the following files in the testdrive-update/src directory to look at the source code of the application:

Open the following files in a text editor to look at the source code for the server-side of the application:

In Product.as we use the [RemoteClass(alias="flex.samples.product.Product")] annotation to map the ActionScript version of the Product class (Product.as) to the Java version (Product.java). As a result, Product objects returned by the getProducts() method of ProductService are deserialized into instances of the ActionScript Product class. Similarly, the instance of the ActionScript Product class passed as an argument to the update method of the RemoteObject is deserialized into an instance of the java version of the Product class at the server-side.


Sample 6: Publish-subscribe messaging (data push use case)

Run the sample

In this 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.

  1. To start the feed component at the server-side, access testdrive-datapush/startfeed.jsp.
  2. Click here to run the application.
  3. Click the Subscribe to 'feed' destination button. Pushed values appear in the text field. You can click the Unsubscribe from 'feed' destination button to unsubscribe from the destination.
  4. To stop the feed when you are done experimenting with the application, access testdrive-datapush/stopfeed.jsp.

Code walk through

Open FeedClient.mxml in the testdrive-datapush/src directory to look at the source code of the application.

Open the following files in a text editor to look at the source code for the server side of the application:

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. To subscribe to a destination, you use the subscribe() method of the Consumer class. When a message is published to a destination that you subscribed to, the message event is triggered on the Consumer.

In Feed.java, the LiveCycle Data Services ES Java API (MessageBroker, AsyncMessage) is used to publish messages to the destination. Another way to exchange messages between Flex and Java applications is to map destinations to JMS topics, essentially allowing a Flex client to publish and subscribe to JMS topics. In addition to JMS, the Message Service adapter architecture lets you integrate with any kind of messaging system.

LCDS destinations are configured in messaging-config.xml. You can configure a destination to deliver the messages using a real-time protocol or using polling.


Sample 7: Publish-subscribe messaging (collaboration use case)

Run the sample

  1. Click here to run the application
  2. Open the same URL in another browser session to open a second instance of the chat application
  3. Type a message in one of the chat clients and click "Send": the message appears in the two chat clients

Code walk through

Open Chat.mxml in the testdrive-chat/src directory to look at the source code of the application.

Open the following file in a text editor to look at the source code for the server side of the application:

WEB-INF/flex/messaging-config.xml

This sample builds on the concepts and APIs introduced in sample 6. To publish a message from a client, you use the send() method of the Producer class.

The messaging and real time infrastructure available in Flex lets you build collaboration and data push applications in a scalable and reliable manner while preserving the lightweight web deployment model.


Sample 8: Data Management Service

Testing persistence

  1. Click here to run the application.
  2. Click Get Data to populate the DataGrid with data.
  3. Click a DataGrid cell, modify the data in that cell, and press Enter.
  4. Click Refresh in your browser and then click Get Data. Notice that the new value appears in the cell, which indicates that the data has been successfully persisted.

Testing data synchronization across clients

  1. Open the same application in a second browser window.
  2. Resize the two browser windows so that you can see both at the same time on your screen.
  3. Modify data in one browser, and press Enter. Notice that the update is automatically pushed to the other client.

Code walk through

Open the following files in the testdrive-dataservice/src directory to look at the source code of the application:

Open the following files in a text editor to look at the source code for the server side of the application:

In addition to the RPC services described in samples 1, 2, and 3, the LiveCycle Data Services ES Data Management Service feature provides an innovative and highly productive approach to synchronizing data across tiers and between clients. The Data Management Service feature consists of a client-side API and server-side service.

On the client side, managed objects keep track of changes made to the data, and notify the backend of these changes. In SampleDataService.mxml, you:

You don't have to keep track of changes made to the data, nor do you have to invoke remote services to notify the backend of the changes (create, update, delete) made on the client side.

On the server side, the Data Management Service receives the list of changes and passes it to your server-side persistence components. The Data Management Service also pushes the changes to other clients. In this example, the product destination configured in the data-management-config.xml file uses the java-dao adapter, which indicates that custom Java classes handle the persistence code (another option is to use the Hibernate adapter). There is no specific contract imposed on the Java class that provides the persistence implementation. You map methods such as fill and sync to actual methods in an assembler class (in this case, ProductAssembler). In the assembler class, you typically delegate the actual persistence implementation to existing persistence classes (in this case, ProductService).

© 2004-2008 Adobe Systems Incorporated. All rights reserved.