LiveCycle Data Services (LCDS) – Quick Start

June 16, 2009By 33 Comments

With the recent work I’ve been doing to add LiveCycle Data Services samples to the Flex Data Access category for Tour de Flex, I felt the need to add some additional helper information to assist people in getting started using it quickly. I’m including some basic information on how to configure the client (using Flex 3) and server side, and provide links to more detailed information as needed. This post is not intended to explain all things Data Services, but I am hoping to provide some overview information for those just beginning to take a look at it, as well as some helpful info and links that might be needed to get on board fast!

So… you want to use Data Services, where do you begin? First I suggest you think about and try to answer the following questions:

  • What kind of data access do I need or what does the service need to do?
  • What platform/language do I need to use (Java, .NET, Cold Fusion etc)?
  • Will there be a database needed, and if so how complex will the table structure be?
  • Will there be any other layers involved, such as Hibernate for instance?

LiveCycle Data Services (LCDS) – Feature Overview

First, a quick overview of the different features provided by LCDS…

RPC Services
Making calls to a remote service or operation is super easy using LCDS. There are various ways to achieve this depending on protocol you want to use etc… they include an HTTP call (using the HTTPService class),  a SOAP call (using the WebService class) or using AMF via Remoting (using the RemoteObject class). I strongly encourage using Remoting where possible due to the significant gains in response time. James Ward has a fantastic and powerful example of different response times for different types of invocations here. The best way to use this app is to select the ‘Census – Guide Me’ option from the drop down list and go through each type of call to get the full effect of response times.

Data Management
If you need to persist and manage data between clients, LiveCycleData Service’s Data Management is definitely the way to go. Using the DataService object, you are immediately given amazing power over your data, including CRUD operations (Create, Read, Update, Delete) with conflict management handling options, auto-commit of data, persisting to a local cache when offline (in an AIR app), and so much more. And what’s even better is the little bit of code needed to make all of this happen! It is still totally amazing to me how powerful yet easy it can be compared to anything I’ve done in the past. The Tour de Flex samples for Data Management are the best resource to check out to get started in this area quickly.

Messaging
The most common use of messaging is in a one-to-many relationship, when there is information that should be broadcast real-time to many at once. This is often called publish-subscribe messaging, or topic-based messaging. The topic is the shared item that a ‘producer’ (the one sending the message) and the ‘consumer’ (the one receiving the message) both subscribe to. A general but explanatory example often used for publish-subscribe messaging is that of subscribing to a stock ticker topic that is broadcasting all of the stock prices real-time to its subscribers. Another type of messaging supported by LCDS is point-to-point messaging, which involves a one-to-one relationship. All of this is described in-depth in the LCDS Developer documentation for those looking for more information. Adobe offers the open-source BlazeDS that offers most of the same Messaging features as well. More info on BlazeDS is given later in this post.

What next?

So once you decide what you need to do and which LCDS features you need to use, I recommend going to the Flex Data Access category in Tour de Flex and locating a sample for the specific area of LCDS you’re planning on implementing. If your solution involves  server side code, for instance if you’re doing Remoting or Data Management, the following steps detail what you should do next to configure the server side:

Server-side Configuration Steps
1.    Create your project in your favorite IDE (I use Eclipse) and be sure to include the following libraries (found in the LCDS or BlazeDS install packages):

a.   acrobat-core.jar
b.   acrobat-core-charset.jar
c.   backport-util-concurrent.jar
d.   cfdataservicesadapter.jar – (Cold Fusion only)
e.   cfgatewayadapter.jar (Cold Fusion only)
f.    commons-codec-1.3.jar
g.   commons-httpclient-3.0.1.jar
h.   commons-logging.jar
i.    concurrent.jar
j.    flex-acrobat
k.   flex-messaging-common.jar
l.    flex-messaging-core.jar
m.  flex-messaging-data.jar
n.   flex-messaging-data-req.jar
o.   flex-messaging-opt.jar
p.   flex-messaging-proxy.jar
q.   flex-messaging-remoting.jar

2.    Create a destination in the appropriate XML configuration file (remoting-config.xml, data-management-config.xml etc.)  The next section has more information about configuration files and LCDS.

3.    Point the destination to the appropriate server side ‘assembler’, (if using Data Management) or class you are using to perform the server side RPC operations and set required parameters on that destination.

Note:  An assembler is a general term for the server side code that will be used to process your interactions with your data. There are a few different types of assemblers built into LCES, or you can extend their AbstractAssembler class to create your own custom class. Examples of each are part of the recent additions to Tour de Flex, and more information about the Java classes used can be found here

4.    Copy your compiled class files for your service or assembler into the WEB-INF/classes directory. Ensure any other configuration files needed for things like a Hibernate integration etc are added to their appropriate server location as well. Note: Tour de Flex has more information regarding configuring LCDS with Hibernate.

For a detailed explanation of the server side configuration needed for your web application that uses LCDS, see here.

Client-side Configuration Steps
1.    Create your Flex project. There are actually a couple ways you can go about doing this. The conventional way will include your required libraries in the build path and set up your compiler options as needed (adding the –services option) so you are ready to use the various LCDS components in your application. However, I personally find the non-conventional way along with using runtime configuration of channels easier and feel that I have more control over it that way.

a.    Conventional way: this link sums it up
b.    Non-conventional way: create a basic Flex project (no server specified) and add the necessary SWC’s to the included libraries for the build path (fds.swc, playerfds.swc and the locale folder found in your webapps WEB-INF/flex/libs folder). Note: these SWC’s are also shipped with LCDS

As I said above, using this option requires you to use runtime channel definitions and set them on your LCDS components, but also offers you full control over which channel is used when, and allows you to easily switch where one is pointing (for instance localhost versus another server destination). Also important to note, configuring this way does not require the services configuration to be compiled into your SWF. An example of configuring channels at runtime is shown below, and used in all of the Tour de Flex Data Access samples:

    
         
    
        

Config file C-R-A-Z-Y! Why are there so many configuration files and what are they used for?

When I first started using LCDS, it seemed a little confusing to me that there were so many different XML files for configuring things, I was just accustomed to having to edit one main config file for many of the things I had worked on, so to have to touch all the different ones for the different services seemed a bit overwhelming at first.

Now that I have worked with it for awhile, I realize there really is one main configuration file called services-config.xml, and it just includes the rest of the config files for the specific services (remoting-config.xml, data-management-config.xml, messaging-config.xml etc).  The services-config file defines channels, logging and security settings, and then has the includes for the rest of the configuration files.  You would typically not specify application level destinations here, but would put them in the appropriate *-config.xml file based on the guidelines below:

remoting-config.xml – set up your destinations used for remoting here (ie: RemoteObject from your Flex client)

data-management-config.xml – set up your destinations for Data Management applications here (ie: those referred to from the DataService object in your Flex client).

messaging-config.xml – set up your destinations for messaging applications here (ie: those referred to from  Producer/Consumer objects from your Flex client).

proxy-config.xml – defines Proxy Service destinations for working with web services and HTTP services (REST services).

Channel Confusion! Which, when and why?

Channels are used in LCDS to provide the transport of your data from end to end over a specified protocol (HTTP, AMF, RTMP etc).  They specify an endpoint for your data to be sent to as well as handle how it should get there. Channels are defined in the services-config.xml file, and there are many different types that can be defined for them. It can be very confusing to try to read the documentation given and figure out what you actually need. Damon Cooper has a fantastic and detailed summary of the different channels depending on what you might need located here.

BlazeDS

BlazeDS is the remoting and HTTP-based messaging technology Adobe is contributing to the community under LGPL v3. BlazeDS offers publication of the Action Message Format (AMF3) binary data protocol specification. Certified builds, warranty protection and enterprise support subscriptions are available. A comparison of the features included in LCDS versus BlazeDS can be found here. There’s also a full test drive available in BlazeDS you can use to check out the included features.

References

The LCDS Gurus

Christophe Coenraets – site includes TONS of cool samples using more advanced LCDS features and information. Christophe has a way of explaining the more complex features in a manner that seems much less intimidating and always supplies source code so you can see exactly what he did to make something happen.
Sujit Reddy G – again lots of great info on LCDS, BlazeDS and more, but some particularly helpful info on using Flash Builder 4 with Data Access.
Dr Flex – a very cleverly written site packed with some great and useful information on a variety of topics.
Cornel Creanga –  former J2EE Software Developer turned Adobe Evangelist with a lot of useful information and samples to check out.
Greg Wilson – great blogger and Adobe Evangelist with a bunch of LCDS, LiveCycle and Tour de Flex sample information.
LCDS Livedocs/Developer’s Guide – in-depth information related to Data Services, includes all the details for the subject matter covered in this post.

LiveCycle Data Services – included samples – included in LCDS is a great set of samples that show off the different features. Some of these were already the basis of the samples added recently to Tour de Flex, but it is in you best interest to start by installing LCDS, running the samples locally to see how they work, and then checking out the included source code. For instance, when running locally your path to the LCDS samples webapp might be: http://localhost:8080/lcds-samples/ depending on your configuration. Don’t miss the ‘Take the Test Drive’ option as well… that is actually the best place to start as some of the other samples on the main samples page become a bit more advanced.

Filed in: Flex/AIRLiveCycle Data Services Tags:

About the Author ()

Comments (33)

Trackback URL | Comments RSS Feed

  1. Kevin says:

    I’m looking to populate PDF fields from Flex…could you help?

    How do I get access to the flex.acrobat packages?

    Looked around but can’t find much help…THANKS!

    K.

    • devgirl says:

      Hi Kevin! You can use LiveCycle Data Services (LCDS) to do this. I just created a sample for Tour de Flex of how it can be done from a Flex client and LCDS that should show you what you need. The sample should be in Tour de Flex sometime today or Monday, but I will email you a zip file of my Flex project to the email address from your comment right now. There is also a library called AlivePDF that is a client-side PDF Generation library you could check out here. Hope this helps! Holly

  2. Alec says:

    Hi, Holy.

    We’re evaluating LCDS ES to be used in a high performance real-time trading app. Lots of high frequency data being streamed into many clients. On a client data and updates are displayed in a data grid. Users can update certain values and changes should be replicated to other clients. Ideal for LCDS I guess.

    Source of the data and updates is a pub/sub messaging system (with Java api) other than JMS but conceptually similar to topic based interaction. How would you suggest to approach integrating this data bus with LCDS ES without loosing major LCDS advantages (especially data management, object remoting, speed and scalabality) ? Is custom Assembler best way to do this? Are there samples of custom Aseemblers wrapping messaging systems? What pitfalls to expect, what pay attention to, etc? I understand that reply to this requires more like a full fledged article.

    Awesome blog, btw 🙂

    Thanks!

    • devgirl says:

      Hi Alec!

      I consulted with the expert on this one (Christophe Coenraets) and we agreed that if you do want the benefits of data management, your best approach here would be to use TWO things:

      1) a custom adapter – to allow publish/subscribe to your messaging system through Java. Take a look at the JMSAdapter for more info on how to do that… And then the message adapter will basically need to transform a raw message to a data management update. So when the custom message adapter receives a message, it uses the Data Management Java API to commit a change to the corresponding dataset. That way the flex client will receive the change as a data management update
      and not a raw message.

      2) a custom assembler (as you said) to wrap your messaging system but using data management. So in this assembler you would be ‘saving’ (publishing) to your messaging system rather than using JDBC to save to a database. A custom message assembler subscribes to your custom messaging system and will take care of the client-to-server direction of this process by getting the update from the client and transforming it into a message. I do not know of any direct samples of this being done, but you could take a look at the custom assemblers we wrote in the Flex Data Access samples in Tour de Flex for more info on writing custom assemblers. The links to the server side assembler code are included in the readme docs for each sample. You would essentially want to modify to to not use JDBC but to use your messaging system instead. Check out Christophe’s blog for more info on using Java and messaging as well, he has some samples on there.

      Your other option would be to just use the custom adapter, but in that case you would not get the data management.

      I hope this makes some sense and helps :). Let me know if you have more questions and keep us posted on your progress! It sounds like LCDS is the right solution for you.
      Holly

      • Alec says:

        Holly, wow, thanks for a great answer!

        I was considering custom messaging adapter for the incoming data feed. One thing I didn’t realize was that, as you pointed, adapter can commit updates to the data management dataset and thus allow client to deal with objects and not raw messages. I was also looking to avoid keeping state (cached data) at adapter level which really works better when caching is delegated up to the data management. Your suggestion solves this nicely. Is having data management in between incurs noticeable latency penalty (in terms of the latency for the message to reach a client) over straight raw message delivery to the client? Another question: In BalzeDS source of the ActionScriptAdapter I noticed that there’s an explicit API call to push changes to all subscribed clients, similar thing is with JMS Adapter. If our adapter commits changes to the data management set I assume this explicit distribution isn’t needed since data management services take care of replication. Correct?

        All above takes care of getting data and updates into the client. For the requests from the client for data updates I was thinking about just wrapping our messaging API inside a service POJO. Clients will call methods (via remoting) on the service objects to update/add/delete data, requests will be passed to our external system and results will be reflected back by the messaging adapter. How this approach stacks against custom Assembler?

        Once again Holly I really appreciate time and effort you are taking in helping us out.

  3. cmm says:

    If we starting building the appliction using BlazeDS and now the client wants to switch to LiveCycle Data Services ES, what is the impact? Will the code we have built using BlazeDS work if we deploy (or recompile with) LiveCycleDataService?

  4. devgirl says:

    Hi, yes, the code is essentially the same for BlazeDS to LiveCycle DS. Note however that BlazeDS does not support Data Management as LCDS does. The other main differences between them are regarding support for the RTMP protocol (LCDS only), scalability (LCDS has NIO server-based option) etc. More info about that can be found here: http://devgirl.wordpress.com/2009/07/14/livecycle-data-services-channels-and-endpoints-explained/

    Assuming you are using messaging though, the same API’s are used to support messaging between both, so you can use the same code to point to an LCDS instance as you used to point at your BlazeDS instance.

    Another good link showing differences in support between the two is here:
    http://sujitreddyg.wordpress.com/2008/01/31/blazeds-and-lcds-feature-difference/

    Hope this helps!
    Holly

  5. fijiaaron says:

    Great post devgirl!

    Now I sound like a blogspam.

    Um… I agree about the config files, but that’s old hat when it comes to Java. Thankfully, there’s no dependency injection framework with annotations needed to configure LCDS (Though I’m sure you could find one.)

  6. Irene says:

    I need some help on LCDS configuration:

    Our flex app using Flex WebService and LCDS Proxy to proxy web service calls. In developer environment it works fine. We are using ColdFusion8 that has LCDS baked in. Define several destinations in proxy_config.xml.

    In production environment we use ColdFusion clustering. How it will work with integrated LCDS version? Do we need to deploy copy of proxy_config.xml on every cluster? Is any additional configuration required for LCDS to work nicely in clustered environment?

    Thanks in advance for your help?

    • devgirl says:

      Hi Irene, I have not used Cold Fusion in a clustering environment but will try to find out more information for you from some experts on the subject and reply shortly. Cheers! Holly

      • Irene says:

        Thanks for helping, did you find any info on clustering?

      • umal says:

        I have the same question as Irene. I am using LCDS integrated with ColdFusion and using the RTMP channel for comminication. Now how can i use ColdFusion clusters or multiple instances of ColdFusion to run my Flex application.

  7. Naveen says:

    Hi Devgirl,

    I am getting the following error when i call a remote method of java class using lcd’s:

    RPC Fault faultString=”[MessagingError message=’Destination ‘loginService’ either does not exist or the destination has no channels defined(and the application does not define any default channels.)’]” faultCode=”InvokeFailed” faultDetail=”Couldn’t establish a connection to ‘loginServlet'”

    Can you sought out my problem.

    Thanks & Regards,
    Naveen.

    • devgirl says:

      Hi Naveen, can you show me what you have defined in your remoting-config.xml file located in your LCDS instance to handle your call? Do you have a loginService destination defined and a channel definition defined either within the destination definition or as a default channel? You should either have something like this defined at the top of your remoting-config.xml (which refers to channel id’s setup in the services-config.xml):

      <default-channels>
             <!--
                 ref: A reference to a channel-definition id. Channels are defined
                 in the top level configuration file.
              -->
              <channel ref="my-amf"/>
              <channel ref="my-http"/>
          </default-channels>
      

      – OR –

      you need to have it specified within your destination definition. Here’s a sample one:

      <destination id="product">
              <properties>
                  <source>flex.samples.product.ProductService</source>
              </properties>
              <channels>
                  <channel ref="my-amf" />
                  <channel ref="my-http" />
              </channels>
          </destination>
      

      The above are just examples, you will need to check the channel id’s you have setup and make sure they match.

      Hope this helps!
      Holly

  8. John Deer says:

    follow this URL for clarifying ideas on LCDS by a complete exemple:

    http://www.adobe.com/devnet/flex/learn/content/flp_flexinaweek_remoting_exercise.html

    Hope it will help

  9. John Deer says:

    Hello devGirl,

    Can you please expose us a “video” to help us understanding clearly the full procedure to implement an LCDS project.

    We need you here.
    Regards

  10. Laurie Hall says:

    Dev Girl,

    This quick start is awesome. I wish it was around when I started “hacking” LCDS a few of years ago. It was painful. I couldn’t find a good general write up anywhere. Very much appreciate your efforts to explain in newbie terms LCDS!

    Cheers!
    Laurie

  11. Po says:

    This blog is truly awesome; but this black background color doesn’t help at all.

    I want to read but I can’t!

    Please make it a little more readable.

    Keep up the good work. Thanks.

  12. Jimmy says:

    Hi, there..

    It seem ur active with ur bloggers.. Hope i could find help here.
    I’ve been using air/coldfusion8 with my latest project, and its pretty well doing. But i really want to use lcds with its services, and i think its awesome. Can you find me link or any help that would guide me using lcds in air projects. From lcds setup, configuring channel/destination; to calling these assets from air application.

    Thanks for the help.

    • devgirl says:

      Hi Jimmy! Take a look at Tour de Flex – Data Access category. There are a bunch of samples of using LCDS features such as remoting, messaging etc that include runtime channel configuration in the sample and the configuration file with the destination is shown so you can see an example of how to use it. There are also other links and information about LCDS in general there. You can use those samples from AIR the same way you would use them from a Flex app. Here’s the link to the web version of Tour de Flex to that Data Access category. I hope this helps!! Holly

  13. Gaston says:

    Hi there, great blog.
    I was wondering if you could help me out with something… I’m new at flex and lcds. My code is giving me a RPC fault error when running it. It says the item already exists, but the thing is I want to update the data in the item. It saves new items with no problem, but i just can’t update any.
    I would much appreciate if you knew what should i check or do.

    Thnx

    • devgirl says:

      Hi Gaston! Could you give me a little bit more info about what you’re doing on the LCDS side for the update? Are you calling a remoting destination that calls a custom Java service? Do you use any other layers like hibernate? What does your LCDS configuration look like for the destination that you’re calling from Flex? Are you passing in an id of the item you want to update to your server-side service and using SQL to update that row in your code in a separate method from your add method? More information would allow me to advise better, thanks! Holly

      • Gaston says:

        Hi,
        My bad. Well, I’m using swiz framework to connect to a Java back-end. I’m using Hibernate too, so I think I don’t need to send the id, but the very object I’m using. I change one of the item’s attributes, and then call a DataService createItem which connects to a Java class, then calls a Hibernate save method. I was tld that hibernate ‘knows’ if you’re trying a save or an update, since it checks the object reference or something like that.
        Anything else you need to know? (A actually think it IS updating the data, but keeps sending me the RPC fault)

        • devgirl says:

          Hi Gaston, if you are using the DataService class with a managed ArrayCollection of data you can use the fill() and commit() methods to retrieve and commit your changes. The commit() method will save off any new changes including updates and new items added to the array collection you’re managing without specifically calling addItem or updateItem etc. If you’re not using the managed AC, you should try calling the updateItem() instead of the saveItem() to persist your changes. There is an example of using DataServices with a hibernate layer in the samples that come with LCDS. You should be able to find it at a URL such as: http://localhost:8400/lcds-samples (where 8400 is the port you have it running on) – then scroll to the bottom to find the Hibernate Integration sample. The code is included in the flex-src.zip file within …webapps/lcds-samples/WEB-INF/, in a folder with the name hibernate. Hope this is helpful :)! Holly

  14. Dinesh Kumar Lohia says:

    Hi,
    I getting below error, when i run application through *.html which call swf, while running with mxml its working fine.
    Can any one help me why this is happening.

    In Fault[FaultEvent fault=[RPC Fault faultString=”[MessagingError message=’Destination ‘loginService’ either does not exist or the destination has no channels defined (and the application does not define any default channels.)’]” faultCode=”InvokeFailed” faultDetail=”Couldn’t establish a connection to ‘loginService'”] messageId=”31A0DC35-13A7-9A33-9643-95CD16C38BA5″ type=”fault” bubbles=false cancelable=true eventPhase=2]

  15. Dinesh Kumar Lohia says:

    remoting-config.xml

    spring
    contactService

    spring
    loginService

  16. Dinesh Kumar Lohia says:

    spring
    contactService

    spring
    loginService

  17. Dinesh Kumar Lohia says:

    /*

    spring
    contactService

    spring
    loginService

    */

  18. Daniela says:

    Hi there, I don’t know if this is the right place for me to ask the following but your blog is the one that have more insight when it comes to livecycle data services, I am using LCDS but, within the livecycle workbench tech, and I created a service along with the entity but I can’t deploy de model it shows me the following error :
    “Error creating and starting destinations while deploying model..” I’ll apreciate if you can help me out with this issue or point out the right path to follow if this is not the right place to ask, thank you before hand, and do forgive me if my request make not sense english is not my native language.

Leave a Reply