While working on the Tour de Flex samples for Flex 4, I spent some time digging into the new Flex 4 Skinning Architecture and found that I could do some really cool stuff with it. Though I’m definitely NOT a designer, I was impressed by the level of control it offered me and wanted to share some basics/tips for skinning your Flex/AIR applications.

So you want to skin your app… where do you start?

1) Copy the source code for the default ApplicationSkin.mxml or WindowedApplicationSkin.mxml file from the Flex 4 SDK source into a new MXML component file within your project. The path should be something like: /<your-flex4-sdk-folder>/frameworks/projects/spark/src/spark/skins/spark/ (or on Windows it would be c:\..\<your-flex4-sdk-folder>\frameworks\projects\spark\src\spark\skins\spark\). You can also use the default skins specified in the Wireframe Flex 4 theme included in the SDK. They are sometimes simpler to work with (for more info on Flex 4 themes, see this link). The path to the wireframe skins will be something like: /<your-flex4-sdk-folder>/frameworks/projects/wireframe/src/spark/skins/wireframe/ (or on Windows it would be c:\..\<your-flex4-sdk-folder>\frameworks\projects\wireframe\src\spark\skins\wireframe\)

I figure what better way to make sure you have control over every detail than by starting with the Flex 4 SDK default skin class currently being used by the container or component. Many times you will not need that level of control and can omit parts of the code that are not changing, however I personally found it nice to see the options I had for modifying skin parts and the fact that they included comments in their skins to explain what each part is.

This is a quick and easy way to understand specifically which skin parts are defined as well. You can also check the Adobe Flex 4 Livedocs for that particular host component’s class documentation to see the required skin parts, skin states etc. Generally though I begin by just grabbing the skin source for the host component I want to skin and modifying or omitting different parts to see how it affected the component (so in the case of skinning an app I would look for either spark.components.ApplicationSkin.mxml or spark.components.WindowedApplication.mxml respectively).

Note: ‘host component’ simply refers to the Spark component/container I want to skin.

2) Change the parts you want to control. So for an Application you may want to modify the ApplicationControlBar look in addition to the background. This can all be done by modifying the source code for the ApplicationSkin.mxml class. Just rename it and modify it to your liking. These examples do not go into skinning the ApplicationControlBar, but you can apply the information from this post in doing so.

Quick Tip: if you just want to use a graphic for your application background, you could use a skin as simple as this:

<?xml version="1.0" encoding="utf-8"?>
<s:SparkSkin xmlns:fx="http://ns.adobe.com/mxml/2009"
   xmlns:mx="library://ns.adobe.com/flex/halo"
   xmlns:s="library://ns.adobe.com/flex/spark">;

    <fx:Metadata>
        [HostComponent("spark.components.Application")]
    </fx:Metadata>

    <s:states>
        <s:State name="normal" />
        <s:State name="disabled" />
    </s:states>

    <s:BitmapImage width="400" height="500" source="@Embed('assets/SampleBackground.png')"/>
    <s:Group id="contentGroup" left="0" right="0" top="0" bottom="0">
</s:SparkSkin>

Note: You must keep the ‘contentGroup’ part in your custom skin so the content of your application shows, otherwise you will only see your image. In the case of skinning an Application, the actual Application.mxml Livedocs will show you which skin parts are required. Scroll down until you see the section labeled Skin Parts in the class documentation. You can also view the inherited skin parts and skin states there.

If you want your image to actually fill in the entire space of the app, then you could use something like this:

<?xml version="1.0" encoding="utf-8"?>
<s:SparkSkin xmlns:fx="http://ns.adobe.com/mxml/2009"
 xmlns:mx="library://ns.adobe.com/flex/halo"
 xmlns:s="library://ns.adobe.com/flex/spark">

 <fx:Metadata>
     [HostComponent("spark.components.Application")]
 </fx:Metadata>

 <s:states>
     <s:State name="normal" />
     <s:State name="disabled" />
 </s:states>

 <s:Rect id="backgroundRect" left="0" right="0" top="0" bottom="0">
     <s:fill>
         <s:BitmapFill source="@Embed('assets/SampleBackground.png')"/>
     </s:fill>
 </s:Rect>

 <s:Group id="contentGroup" left="0" right="0" top="0" bottom="0" />
</s:SparkSkin>

3) Apply the custom skin to your MXML application. You can do this in two ways, either inline MXML or CSS. For inline MXML, you simply set the skinClass property on the root Application tag to the fully-qualified name of your custom class. For instance:

    <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark"
       xmlns:mx="library://ns.adobe.com/flex/halo
       skinClass="skins.CustomApplicationSkin">

In CSS it would be something like:

s|Application
{
    skinClass: ClassReference("com.devgirl.blogexample.skins.CustomApplicationSkin");
}

I generally use the skinClass property for application skins. The CSS way to do it is nice when you want to apply a certain skin to all instances of a component that you may have created a custom class for, such as Button for example.

Below are a couple of examples of skinning an application with a simple custom application skin (keeping in mind the fact that I am so NOT a designer ) but, they should help give an idea of what you are able to do. The screenshot is shown first followed by the source code for the custom skin and Flex app:

The custom background skin for the above screenshot looks like:

<?xml version="1.0" encoding="utf-8"?>
<!-- ../skins/BackgroundImageAppSkin.mxml>
<s:SparkSkin xmlns:fx="http://ns.adobe.com/mxml/2009"
		xmlns:mx="library://ns.adobe.com/flex/halo"
		xmlns:s="library://ns.adobe.com/flex/spark">

	<fx:Metadata>
		[HostComponent("spark.components.Application")]
	</fx:Metadata> 

	<s:states>
		<s:State name="normal" />
		<s:State name="disabled" />
	</s:states>

	<!-- This image fill also specifies padding around it -->
	<s:Rect id="backgroundRect" left="100" right="100" top="20" bottom="20">
		<s:fill>
			<s:BitmapFill source="@Embed('assets/wood-bg.png')"/>
		</s:fill>
	</s:Rect>	

	<s:Group id="contentGroup" left="0" right="0" top="0" bottom="0" />
</s:SparkSkin>

The Flex application code for this screenshot is the following:

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
			   xmlns:s="library://ns.adobe.com/flex/spark"
			   xmlns:mx="library://ns.adobe.com/flex/halo"
			   skinClass="skins.BackgroundImageAppSkin"
			   backgroundColor="0x000000">

	<fx:Declarations/>

	<s:VGroup horizontalCenter="0" verticalCenter="0">
		<s:Label text="Wood Sales Int'l" fontSize="42" />
		<s:Border borderColor="0x000000" borderWeight="3" cornerRadius="7" horizontalCenter="0" verticalCenter="0">
			<s:VGroup>
				<mx:Form fontSize="16">
					<mx:FormItem label="Userid:">
						<s:TextInput id="userid"/>
					</mx:FormItem>
					<mx:FormItem label="Password:">
						<s:TextInput id="pw"/>
					</mx:FormItem>
					<mx:FormItem>
						<s:Button label="Login"/>
					</mx:FormItem>
				</mx:Form>
			</s:VGroup>
		</s:Border>
	</s:VGroup>
</s:Application>

Now I can change just one line in my sample code, the skinClass property to a different skin, and produce this:

And below is the custom gradient background skin for the above screenshot:

<?xml version="1.0" encoding="utf-8"?>
<s:SparkSkin xmlns:fx="http://ns.adobe.com/mxml/2009"
		xmlns:mx="library://ns.adobe.com/flex/halo"
		xmlns:s="library://ns.adobe.com/flex/spark">

	<fx:Metadata>
		[HostComponent("spark.components.Application")]
	</fx:Metadata> 

	<s:states>
		<s:State name="normal" />
		<s:State name="disabled" />
	</s:states>

	<!-- border -->
	<s:Rect left="10" right="10" top="10" bottom="10" radiusX="9" radiusY="9">
		<s:stroke>
			<mx:SolidColorStroke color="0xCCCCCC" alpha=".5" weight="4"/>
		</s:stroke>
	</s:Rect>

	<s:Rect id="backgroundRect" left="10" right="10" top="10" bottom="10" radiusX="9" radiusY="9">
		<s:fill>
			<s:LinearGradient rotation="90">
				<s:entries>
					<s:GradientEntry color="0x0000FF" ratio="0.00" alpha="0.8"/>
					<s:GradientEntry color="0x336699" ratio="1.0" alpha="0.5"/>
					<s:GradientEntry color="0xCCCCCC" ratio="0.5" alpha="0.8"/>
				</s:entries>
			</s:LinearGradient>
		</s:fill>
	</s:Rect>

	<s:Group id="contentGroup" left="0" right="0" top="0" bottom="0" />
</s:SparkSkin>

Again, the sample Flex application MXML looks exactly the same except we are specifying my custom gradient background skin on the skinClass property:

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
			   xmlns:s="library://ns.adobe.com/flex/spark"
			   xmlns:mx="library://ns.adobe.com/flex/halo"
			   skinClass="skins.GradientBackgroundAppSkin">

	<fx:Declarations/>

	<s:VGroup horizontalCenter="0" verticalCenter="0">
		<s:Label text="Wood Sales Int'l" fontSize="42" />
		<s:Border borderColor="0x000000" borderWeight="3" cornerRadius="7" horizontalCenter="0" verticalCenter="0">
			<s:VGroup>
				<mx:Form fontSize="16">
					<mx:FormItem label="Userid:">
						<s:TextInput id="userid"/>
					</mx:FormItem>
					<mx:FormItem label="Password:">
						<s:TextInput id="pw"/>
					</mx:FormItem>
					<mx:FormItem>
						<s:Button label="Login"/>
					</mx:FormItem>
				</mx:Form>
			</s:VGroup>
		</s:Border>
	</s:VGroup>
</s:Application>

So you can see just how quickly you can make your application theme look entirely different with just a one line change and not modifying any behavioral logic. It’s very powerful and there are so many more things beyond this that you can do with the FXG drawing API’s.

A couple other tips for non-designer folks out there… You can use the Adobe CS4 products such as Photoshop, Illustrator and Fireworks etc to create your skins and then export them as FXG and use them within your skins. You do not have to understand all of the FXG classes and properties necessarily but can just visually draw what you want with those products and either do a ‘Save As’ .fxg extension type (such as in Photoshop), or use the Export to FXG command (from the Commands menu) in Fireworks. For instance, it may generate your FXG for a drawn border (using the Path FXG object) based on what you drew that you can use without having to figure all the specific points out. You can then extract the parts you want from the FXG and place them in your custom skin class. Many times you will also get an image as a result and will use that within your skin class as well, like I did in the wood sample above. The image is exported and referenced as part of the FXG from the CS4 tools. If you play around with it a bit and export the FXG to see what it created, you will quickly see what you can do.

Important to note: One FXG-related issue I ran into when exporting from Photoshop or Fireworks, is that there are times when what you produced will result in either a TextGraphic or BitmapGraphic in the FXG source and you must manually change them to RichText (for TextGraphic) and BitmapImage (for BitmapGraphic) or you will get compiler issues with the namespace. Detailed information about this can be found here.

Also, an obvious tip to most, but just in case it helps someone… When I create my new image, I always use the ‘Transparent’ background mode so that it fits in with whatever color scheme I might choose within the app. If you know exactly what color you are using already, you can set the background to that and it will matte it to that color. This is probably already known to many, but for those that might not know, it will save you time figuring out why there is a white border around your image in your app!

Also note, everything above can be applied to skinning your AIR applications as well. You simply start with the WindowedApplicationSkin.mxml default skin class from the Flex 4 SDK.

There’s so much to the skinning architecture to understand, that you should definitely check out the Flex 4 team blogs and Livedocs Help to complete your knowledge.

If you weren’t able to come to MAX or attend our ‘Making Real-Time Data Come Alive with Flex Data Visualization’ session, Greg and I have our slides, code zip and other resources here. The lab handout has all of the source code for the lessons as well and will walk you through the lab. Please post a comment if you have any questions!

I had a wonderful time at MAX and met some really great people, I encourage all developers to make it a priority to attend this conference each year. The experience is invaluable!

If you weren’t aware, all of the session videos for MAX are posted here. Some sessions I found particularly interesting and definitely worth your time to watch the videos are:

Ely Greenfield – What’s New in Flex 4

Glenn Ruehle – Deep Dive into Flex 4 Lists and Layouts

Christophe Coenraets – Model Driven Development with Flex 4 and LCDS 3

Scott Evans – Flash Builder 4 Advanced Tips and Tricks

Chet Haase – Effects in Flex 4

Marcel Boucher – What’s Next in Livecycle ES

I’m already looking forward to Adobe MAX 2010

We on the Attest team have been hard at work creating a new Attest PRO version that is now offered on the Adobe AIR Marketplace in the new Try/Buy Service announced today at Adobe MAX! Dave and I have been working late hours and weekends implementing a number of new features for this version and are particularly excited about being able to participate in the Try/Buy Program.

Attest PRO features:

• Two Modes – there are now two modes in Attest, ‘Test’ and ‘Learn’. The Learn mode offers tons of resrouces broken down into the specific categories and topics the Flex/AIR Certification Exam focuses on to help you quickly start studying those areas you will be tested on without having to research them yourself.

• Randomization – this version supports randomization so you never get the same exam twice and cannot memorize the order of questions or answers. This is a huge change from our regular Attest version and we are continuously adding questions to our Attest database so you will keep finding more and more new questions.
• New Menu Options
  • Untimed option – you can now select an option to take your tests untimed if you want to use them for practice until you’re ready to try it with the pressure of time.
  • Show Answer option – new feature to help with studying and provide instant feedback. You can select this option if you’d like to answer and immediately see if you’re correct. The Show Answer dialog also shows feedback and documentation links for further study. An example is shown in the 2nd screenshot below:

• New Questions/Answer Results Renderer visually shows what you missed quickly so you can drill in for more info in a grid of answers. Clicking in further will take you to another view that will allow you to quickly review every question again with the answer you chose and the correct answer(s) highlighted in green for you to review. Those screens are shown below:

About Adobe Marketplace Try/Buy

The Try/Buy Service Adobe is offering is allowing Attest PRO to be offered on a trial basis before being purchased. The trial is currently set for 3 days, and will restrict some features in the application until fully purchased.  And of course the free regular Attest version will always still be available for those that do not feel the need to cough up the dough

To try out Attest PRO, go here

Be sure to check out Dave’s post about Attest PRO as well for more details.

Today we are rolling out the first batch of new Flex 4 samples based on the recent **Flex 4 SDK (update: as of 10/1/2009, all have been updated to work with the latest version of the SDK beta 2 released at MAX). Tour de Flex had a Flex 4 Preview category previously, but the samples were based on a very early build of Flex 4 and much as changed since then so many were no longer valid.

We recently spent some time with members of the Flex 4 team in San Francisco to get an idea of what had changed, what’s coming, etc and I’ve been working on creating new samples to help show off some of the new features. Many more are in the works and will be rolled out weekly while Flex 4 is under continued development, so stay tuned for tons more!

The Flex 4 team is working hard at addressing concerns previously raised and I think people will find a lot of really cool stuff to come here. Be sure to check out the readme’s in the various categories with the samples as well as the one in the top Flex 4 Preview folder. I’ve included some very helpful links that can make the transition so much less painful if you take the time to check them out. I think it is key in overcoming the learning curve quickly. I would also highly recommend spending some time going through the source code in the Flex 4 SDK to understand the architecture better. It was a huge help to me in coming up to speed with it overall. To get the very latest SDK and docs, check here for nightly builds.

If you have specific requests for a certain sample let me know, or if you’d like to contribute a sample feel free to contact myself or Greg Wilson with the sample you’d like to add. Also, if you have any issues with any sample or questions while trying Flex 4, feel free to contact me here on my blog, twitter or email and I will see if I can help you out

Flex 4 – Useful Links

I will continue to update this list. Please feel free to comment with your favorites!

Also, please note, the Tour de Flex samples are best viewed in the AIR version of Tour de Flex. When using the web version, we recommend hitting the expand button in the top right corner to see the full sample better. Sizing issues are currently being worked on.

If you don’t know it already, the Adobe MAX conference is always a great learning and networking experience and this year it is sounding better than ever. They’re offering some new things I believe will really help developers get the most out of their experience with the addition of more lab-type sessions, Birds of a Feather discussions at lunch-time etc and more sessions overall. There will also be a ton more content this year focusing on LiveCycle ES and Enterprise RIA which is particularly cool to me as someone who works on both the client and server side and want to know my options for different business solutions. And of course there are always the sessions focusing on Adobe’s creative tools, not to mention really big secret announcements and a sneak peek at upcoming coolness seen only there first.

As a developer attending a conference, I have always been one to seek out as many lab-type sessions as possible believing in the extended benefit of working on something hands-on while learning. The Adobe people must have realized the value in this as well and decided to offer a new alternative to lab-type sessions called BYOL – (Bring Your Own Laptop), where you can use your own laptop to work along with the class. You will still be given a handout of the code lessons etc but instead of using a workstation provided, you simply use your own laptop. The biggest pro here is that you are comfortable on your own laptop already and will have the final version without having to copy it off quickly before getting to your next session. You will however have to be sure that you have the necessary requirements for the class on your laptop prior to attending, and these requirements are posted along with the session details on the MAX portal.

This year I’m fortunate enough to have the opportunity to co-present a session on two different days with Greg Wilson entitled, “Making Real-Time Data Come Alive with Flex Data Visualization.” I’m very excited about this session because I think it’s a topic that is great fun and offers a unique learning experience by giving people a taste of not only using data visualization with real-time data, but experience using Messaging with Data Services on BlazeDS. From this session you will learn how to do push-subscribe messaging acting in both a publisher and subscriber role as well as how to take real-time data and visualize it in a Flex Charting component. We will also talk about the Tour de Flex Dashboard, so you are sure to walk away with some really cool stuff here.

The session times are Monday, Oct 5th at 2:30pm and Wednesday, Oct 7th at 1:30pm. So if you have not already registered for Adobe MAX 2009 then what are you waiting for?! Hope to see you soon in L.A.

As a follow-up to my LCDS Quick Start Guide, I wanted to offer more in-depth information about using channels and endpoints with your LiveCycle Data Services application. What is a channel and what is an endpoint ultimately? A ‘channel’ is the term used for the client-side code to manage the connection, and the ‘endpoint’ is the term used for the server-side code or configuration that manages the connection. So for a Flex client to communicate with LiveCycle Data Services, a channel must be defined for the client side to communicate with the endpoint on the server-side. The data is sent across the channel in a network-specific format to the endpoint. The endpoint code (Java) reads the data that comes across the channel and determines which service to route that data to. In this case, a service is just another set of code that will be used to process the data sent over the channel and refers to either a remoting service, a data management service, messaging service or an HTTP Proxy service.  The channel and endpoint definition are configured and associated in the services-config.xml file via tags, such as the following:

<channel-definition id="samples-amf" type="mx.messaging.channels.AMFChannel">
        <endpoint url="http://servername:8400/myapp/messagebroker/amf" port="8700"
            type="flex.messaging.endpoints.AMFEndpoint"/>
</channel-definition>

where the ‘id’ attribute refers to the client side channel and ‘type’ refers to the client-side code class type. The associated endpoint element is included as a child of the channel definition to show what server-side endpoint should be used when that client-side channel is used. The ‘url’ attribute on the endpoint must be unique across endpoints, and points to either the MessageBrokerServlet or an NIO based server depending on what implementation you are using. The above example shows the use of the MessageBrokerServlet.

Christophe Coenraets presents on LCDS and BlazeDS often, and has great summary information in those presentations regarding channel usage. I took details from his slides and summarized them in the text below because I think it’s very valuable information for people to know.

Simple Polling

• Near real-time
• May use when you only expect to have 100-150 connections max.
  

<channel-definition id="my-amf">
    <endpoint url="http://{server.name}:{server.port}/{context.root}/messagebroker/amfpolling"/>
    <polling-enabled>true</polling-enabled>
    <polling-interval-millis>8000</polling-interval-millis>
</channel-definition>

Long polling with piggybacking

• Similar to traditional poll, but if no data available, server “parks” poll request until data becomes available or configured server wait interval elapses.
• Client can be configured to issue next poll immediately following a poll response making this channel configuration feel very “real-time”.

Pros

• HTTP request/response pattern over standard ports. No firewall/proxy/network issue.

Cons

• Overhead of a poll roundtrip for every message when many messages are being pushed
• Servlet API uses blocking IO.  You must define an upper bound for the number of long poll requests parked on the server

Example:
<channel-definition id="my-amf">
    <endpoint url="http://{server.name}:{server.port}/{context.root}/messagebroker/amfpolling“/>
    <polling-enabled>true</polling-enabled>
    <polling-interval-millis>8000</polling-interval-millis>
    <piggybacking-enabled>true</piggybacking-enabled>
    <wait-interval-millis>60000</wait-interval-millis>
    <client-wait-interval-millis>1</client-wait-interval-millis>
    <max-waiting-poll-requests>200</max-waiting-poll-requests>
</channel-definition>

The following illustration is taken from the Adobe LiveCycle Data Services Developer’s Guide and is helpful in showing the difference between for standard polling versus long polling. The description of it, taken from the dev guide is as follows: “In the standard polling scenario, the client constantly polls the server for new messages even when no messages are yet available. In contrast, in the long polling scenario the poll response thread waits for messages to be available and then returns the messages to the client.”

Streaming AMF/HTTP Streaming

• Because HTTP connections are not duplex, this channel sends a request to “open” a HTTP connection between the server and client, over which the server will write an infinite response of pushed messages.
• Uses separate connection from browser’s connection pool for each send it issues to server.
• Each message is pushed as an HTTP response chunk (HTTP 1.1 Transfer-Encoding: chunked).

Pros

• No polling overhead associated with pushing messages to the client.
• Uses standard HTTP ports. No firewall issue and all requests/responses are HTTP so packet inspecting proxies won’t drop the packets.

Cons

• Holding “open” request on the server and writing an infinite response is not “nice” HTTP behavior. HTTP proxies that buffer responses before forwarding them can effectively swallow the stream.  Assign the channel’s ‘connect-timeout-seconds’ property a value of 2 or 3 to detect this and trigger fallback to the next channel in your ChannelSet.
• No support for HTTP 1.0 clients.
• Servlet API uses blocking IO. You must define a upper bound for the number of streaming connections you allow.

Example:
<channel-definition id="my-streaming-amf">
    <endpoint url="http://localhost:8400/messagebroker/streamingamf"/>
</channel-definition>

RTMP

• Single duplex socket connection to the server.
• If direct connect fails, the Player will attempt a CONNECT tunnel through an HTTP proxy if one is defined by the browser.

Pros

• Single, stateful duplex socket that gives clean, immediate notification when a client is closed. The HTTP-based channels/endpoints generally don’t receive notification of a client going away until the HTTP session on the server times out.
• The player internal fallback to HTTP CONNECT trick to traverse an HTTP proxy if one is configured in the browser gives the same pro as above (technique not available from ActionScript or Javascript).

Cons

• Generally uses a non-standard port so it is often blocked by client firewalls.
• Network components that do stateful packet inspection may also drop RTMP packets, killing the connection.

Example:
<channel-definition id="my-rtmp">
    <endpoint url="rtmp://{server.name}:2037"/>
    <properties>
        <idle-timeout-minutes>20</idle-timeout-minutes>
    </properties>
</channel-definition>

NIO Channels

• NIO stands for Java New Input/Output and is basically a Java socket server completely separate from the servlet-based server-side option.
• The same channels as previously described are available through an embedded NIO Server.
• This option offers much better scalability and no configured upper bound on the number of parked poll requests.
• Because the servlet pipeline is not being used, this endpoint requires more network configuration to route requests to it on a standard HTTP port if you need to concurrently service HTTP servlet requests.
• NIO endpoints use the Java NIO API to service a large number of client connections in a non-blocking, asynchronous fashion using a worker thread pool, therefore the limitation of the servlet option using one thread is removed and a single thread of an NIO server can service multiple I/O’s.

NIO AMF example

<channel-definition id="my-nio-amf">
    <endpoint url="http://{server.name}:2080/nioamf"/>
    <server ref="my-nio-server"/>
    <properties>
        <polling-enabled>false</polling-enabled>
    </properties>
</channel-definition>

NOTE: BlazeDS only supports the following channel types:

• Polling
• Long polling
• Long polling with piggybacking
• HTTP Streaming

Configuring Channels

Channels can be specified on the client-side via the configuration of the -services compiler option in your project setup, or programmed at runtime. If done at runtime, they are coded into the client MXML or ActionScript directly, therefore no –services compiler option is specified on the project. This also means that the specific endpoint URL does not have to be compiled into the client SWF. In this case it is much more flexible in that you could simply create an XML file with your endpoint URLs in it depending on the environment, and connect with an HTTPService in your client to read them in at initialization. More detailed information regarding defining channels can be found here: http://livedocs.adobe.com/livecycle/8.2/programLC/programmer/lcds/help.html?content=lcoverview_4.html

Below are screen shots to show you how to set up your LCDS project with the compiler options etc:

However, as noted in the previous paragraph, you can completely skip all the above project setup and define your channels for runtime use. An example of this is shown below:

<mx:ChannelSet id="channelSet">
    <mx:RTMPChannel id="rtmpChannel" url="rtmp://tourdeflex.adobe.com:2037"/>
</mx:ChannelSet>

You can also code it in ActionScript if desired, such as the following:

var cs = new ChannelSet();
cs.addChannel(new RTMPChannel("my-rtmp", "rtmp://localhost:2035"));
cs.addChannel(new AMFChannel("my-polling-amf","http://servername:8400/app/messagebroker/amfpolling"));

You then use that defined ChannelSet on your DataService object as follows:

<mx:DataService id="ds" destination="product2" channelSet="{channelSet}"/>

This can be done for any of the LiveCycle Data Services objects you are working with, including RemoteObject, Producer/Consumer objects for Messaging etc…

An example of this with remoting is below:

<mx:ChannelSet id="channelSet">
   <mx:AMFChannel id="amfChannel" url="http://tourdeflex.adobe.com:8080/lcds-samples/messagebroker/amf" />
</mx:ChannelSet>
<mx:RemoteObject id="myService" destination="userService" channelSet="{channelSet}" result="onResult(event)" fault="onFault(event)"/>

Many other examples of this can be found in the Flex Data Access section of Tour de Flex.

General Guidelines

So when to use which channel? Below are some general guidelines. For more detailed information, see the LiveCycle Data Services Developer’s Guide:

• Use AMF channels for Remoting
• The order of preference in choosing channels in general, particularly based on latency (other then when using Remoting):
  • RTMP
  • Streaming AMF (1st choice for BlazeDS since RTMP is not supported there)
  • Long Polling
  • Polling

  Important Note: you can code multiple channels at runtime and LCDS will use them in order of declaration. If there is a problem, such as a firewall issue with RTMP, then the next channel in the code will be tried. It is a good practice to add a regular polling channel as the last channel in order since it will always work as a fallback. An example of how this would look in the code is shown below:

      <mx:ChannelSet id="channelSet">
         <!-- RTMP channel -->
         <mx:RTMPChannel id="rtmp" url="rtmp://tourdeflex.adobe.com:2037"/>
         <!-- Long Polling Channel -->
         <mx:AMFChannel url="http://tourdeflex.adobe.com:8080/lcds-samples/messagebroker/amflongpolling"/>
         <!-- Regular polling channel -->
         <mx:AMFChannel url="http://tourdeflex.adobe.com:8080/lcds-samples/messagebroker/amfpolling"/>
     </mx:ChannelSet>

• If you need scalability and are using LCDS (versus BlazeDS), opt for the NIO based channels. Note that in this case though you will not have access to any HttpSession data etc since it is not servlet-based.
• Use AMF channels over HTTP-based channels since the data is passed in binary format versus text/XML and will be much faster.
• Choose Long-polling or streaming over simple polling.
• Damon Cooper has an excellent summary of the various channels with more detail on when to use which here, definitely recommend reading through this post.
• InfoQ article describing the differences between choosing LiveCycle Data Services versus BlazeDS. More detailed channel and endpoint information here too, very interesting and detailed read.

And lastly… if you’re like me and really need to understand what is happening under the covers with all of this rather than assuming the magical black box, I recommend reading at least this one page of the Adobe LiveDocs for LCDS. It was eye-opening for me!

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:

    <mx:ChannelSet id="channelSet">

         <mx:RTMPChannel id="rtmpChannel" url="rtmp://tourdeflex.adobe.com:2037"/>

    </mx:ChannelSet>

        <mx:DataService id="ds" destination="hibernate-contact" autoCommit="false" channelSet="{channelSet}" fault="onFault(event)"/>

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.

Have you ever needed to launch another AIR application from within an AIR application? I have found myself wondering how this would be done exactly, and noticed that Rich Tretola just did a great blog post this morning on two ways to do it, including source code. He presented the solutions at 360 | Flex recently and was kind enough to share it on his blog. He shows one solution using an undocumented AIR class called ProductManager, and another of how to load from the Browser API air.swf in the event that you are not sure the other AIR app is installed on the user’s machine. Check it out if you find yourself in need of this functionality in the future!

If you haven’t heard the news yet, Tour de LiveCycle was released this week! It is based on the same architecture as used in Tour de Flex and is jam-packed with useful information on how to use this very complex but powerful product from Adobe. LiveCycle ES is near and dear to me as I have worked with it and the wonderful people that continue to develop and support it for many years now.  I was fortunate enough to work with the development team that wrote the original workflow engine that was eventually purchased by Adobe back in 2004, and have seen it evolve so much over the years. I have to say I’m super excited about this application because I feel it was so necessary and will be such a huge help to so many.  I know that many people have no clue what LiveCycle ES is all about, what you would do with it etc, but now is your chance to find out! It is absolutely worth your time to install the AIR app and find out more about it. This app is not only useful for those who are discovering LiveCycle, but will also serve as an awesome reference to those who are using it in their day to day jobs. I highly recommend checking this out, yet another great application from Adobe…

Recently I’ve been given the opportunity to work on adding LiveCycle Data Services (LCDS) samples to Tour de Flex in an effort to help ‘de-mystify’ it for developers. In my opinion it seems that many find it a bit intimidating, at least anything beyond using HTTPService, WebService or RemoteObject anyway… I think much of this is due to the lack of information on how to use it exactly (other than the super helpful coenraets.org), the confusion about configuration, (since there are so many different XML files involved) and developers not knowing exactly how to set it up with their projects to get started with it quickly and not painfully ! I am a great example of this myself because I remember full-well the experience I had when I needed to use it on my first project and know the frustrations that could have been avoided given the right knowledge!

The overall goal of these samples is to help get developers started with showing off the many different features available in a simplified manner, along with explanatory text, source code (including server side), XML configuration file entries etc. I was involved in numerous discussions regarding these samples and how to best present them with Adobe Evangelists Greg Wilson, Christophe Coenraets and James Ward, and they had some really great ideas that I believe will be a huge benefit to the community of developers of all types. Some samples have already been added thus far (under top-level category Flex Data Access), and notes about them are listed in the QuickStart page that’s shown when you open Tour de Flex initially (on both the AIR and web versions). However, there are more to come, as well as some samples that highlight using Flex and LiveCycle Data Services with a back-end other than Java (PHP, ColdFusion, .NET, Ruby etc). As part of this goal, we’re hoping to solicit samples from other server side software companies showing how to use their APIs, so look for those in the near future. I’m also about to release a sample that shows how to work with Hibernate on the back-end with your Flex client using data services.

In addition to the samples, I’ve also started writing up some summary notes to supplement them and explain some things about LCDS overall. I’m hoping these notes will help people get started quickly since they are coming from a fellow developer’s point of view who’s sorta been there, done that and will hopefully simplify things for people beyond trying to gather it from reading the very large LCDS developer’s guide ! That post will be coming in the next week as well so please check back again soon!