AMF.js is the javascript client for R-AMF server.  It uses a custom version of AMF, version 99.  The custom version was created in an effort to reduce the number of bytes sent over the wire.  On a per client basis the reduction is not great but considering our customers at Reignite are expecting to have in some cases many thousands of clients making calls to the server and our customers pay for bandwidth usage every byte counts.

So here is the basic usage:

<script type="text/javascript" src="AMFR.js"></script>
var con = new AMFR();
con.endpoint = "http://www.example.com/amfr";
var msg = con.createMessage("securityService", "authenticate",["siteAdmin","password"]);
con.call(msg, function(data){alert("on result")},function(data){alert("on status")});

You import AMFR.js and that is all.  Then when you want to use it you create a new AMFR(), set the endpoint, use it to create a message and then send the message.

You can reuse the same AMFR over and over.  Just create new messages and send them.

Create message takes the following:
destination, operation, [params]
The destination is the name of the service specified in your server side configuration.  It is the same as the destination name used in Flex RemoteObjects.  The operation is the method to call on that service, just like the operation in Flex RemoteObjects.  The params are an array of javascript objects.  So if you want a date to appear as a date in Java you need to pass a javascript Date object not a string representation.  If you want an object to deserialize as a correctly typed object in Java you need to add a special field to your Javascript object.  EG:
{“AMFR_class”:”com.example.security.User”,
“id”:4,
“username”:”frank”, etc… }
The server would attempt to instantiate an object of type com.example.security.User and set its fields with id, username and whatever else you sent through.

The inverse of this is true too.  When a server method returns a Java object to the Javascript client it is a plain old Javascript object, or map or dictionary or whatever term you like, with the special AMF_class property attached.  So you could load a User from the back end, update some fields then store it back.

Dig into the AFMR.js code and see what it does for yourself.  It is not minimised or obfuscated in any way and I’ve tried to use plain english names for things.

R-AMF is the name I’ve given the no frills implementation of Adobe’s AMF server I wrote in an effort to improve efficiency and fix a few bugs that bothered me.  It stemmed from the requirement to move to HTML 5 / Javascript while retaining backward compatibility with our old Flex based clients.  I’ll go into how to configure the server side an example of using the AMFR.js Javascript client for AMF99 or AMFR if you like.

Overview

AMF is a binary protocol for communicating over the web.  That means we need a client and a server side to encode and decode the messages.  The client can be either Flex, in which case AMF3 is usually used or it can be my Javascript client which uses AMF99.

The server side is written in Java.  Essentially it is a servlet that a client POSTs to.  The servlet reads the body data, which is encoded in AMF of version 0, 3 or 99.  The body, once decoded will contain a service call that is routed according to configuration to the appropriate endpoint.  The configuration of the server begin in the web.xml.  This specifies the servlet used and the type of configuration used for the routing and remoting systems.  R-AMF server does not support streaming or real time messaging, only synchronous service calls.  This is because I intend to use web sockets for real time messaging as they become available.

Web.xml

The first part is a filter.  The SEncodeFilter is required to convert a Java binary stream into a character stream that can be read by Javascript.  The filter operates based on an HTML header.  So if you are using AMFR.js as your client you would set the header to true but if you are using a Flex AMF3 client you would either not set the header or you would set it to false.  Flex can handle binary streams but Javascript using the XMLHttpObject can only handle character streams.  I used to use a Base64 encode filter but found it was less efficient that required.  SEncode is an encoding scheme I came up with that is more compact.

<filter>
    <filter-name>encodeFilter</filter-name>
        <filter-class>com.reignite.messaging.server.SEncodeFilter</filter-class>
    </filter>
<filter-mapping>
    <filter-name>encodeFilter</filter-name>
    <url-pattern>/amfr</url-pattern>
</filter-mapping>

The above would be added to your web.xml.  I’m assuming you are somewhat familiar with Java server configuration eg: Tomcat, Jetty, etc… so I won’t go into great detail about this.  But you can see there is a filter that intercepts everything going to /amf.  The filter looks for the header:
s-enc
If you set s-enc to “true” as in the string without the quotes.  Then the filter works its magic on the body of the request to convert it to and from a UTF-8 character stream.

The next bit is the servlet configuration.

<servlet>
	<servlet-name>MessageBrokerServlet</servlet-name>
	<display-name>MessageBrokerServlet</display-name>
	<servlet-class>com.reignite.messaging.server.MessagingServlet</servlet-class>
	<init-param>
		<param-name>initializer</param-name>
		<param-value>com.reignite.messaging.server.SpringWebInitializer</param-value>
	</init-param>
        <init-param>
		<param-name>RAMFServerBeanName</param-name>
		<param-value>ramfServer</param-value>
	</init-param>
	<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
	<servlet-name>MessageBrokerServlet</servlet-name>
	<url-pattern>/amfr</url-pattern>
</servlet-mapping>

So I called the servlet MessageBrokerServlet out of habit but the servlet class is MessagingServlet.  This is the base class that will listen on /amfr and process AMF messages.  You’ll note the servlet listens to the same url as the filter.  I personally extended the MessagingServlet to become the SecureMessagingServlet which allowed me to store some request data in a ThreadLocal for use in my application, but you don’t need to extend the servlet if you don’t want to.

The other important thing to note here is the init-param I pass in to the servlet.  This is the initializer and is what the servlet will use to set up the routing.  I’ve got it configured with a SpringWebInitializer but you could extend com.reignite.messaging.server.WebInitializer to get configuration details from somewhere else if you like or you could implement the Initializer interface and not use the web servlet context at all.  I only created the SpringWebInitializer because I use Spring. The other init-param is for the SpringWebInitializer so it can find the RAMFServer in your Spring applicationContext.xml. I don’t use annotations for dependency injection as they are an incorrect use of annotations and should not be used for that purpose.  I also do not use autowiring as that is an incorrect use of dependency injection and should not be used due to maintenance issues and project hand over issues.

Once your MessagingServlet has been configured to find your RAMFServer instance you’ve finished configuring the servlet.  Now you have to configure the server.  In the source code I put up on google code there is a basic context file.  You should look at that for clues as to what to do.

Spring configuration

<bean id="ramfServer"  class="com.reignite.messaging.server.RAMFServer">
	<property name="endpointLocator" ref="endpointLocator" />
	<property name="codecLocator" ref="codecLocator" />
	<property name="errorVersion" value="99" />
</bean>
 <bean id="endpointLocator"class="com.reignite.messaging.server.WebEndpointLocator">
	<property name="endpointMap">
		<util:map>
			<entry key="/amfr" value-ref="endpoint" />
		</util:map>
	</property>
</bean>
 <bean id="codecLocator" class="com.reignite.codec.CodecLocatorImpl">
	<property name="serializeWorkers">
		<util:map>
			<entry key="99" value="com.reignite.codec.amf.AMFRSerializeWorker" />
		</util:map>
	</property>
	<property name="deserializeWorkers">
		<util:map>
			<entry key="99" value="com.reignite.codec.amf.AMFRDeserializeWorker" />
		</util:map>
	</property>
	<property name="aliasRegistry">
		<bean class="au.com.reignite.amfr.SelfRegisteringMessagingAliasRegistry">
		    <property name="sessionFactory" ref="sessionFactory" />
		</bean>
	</property>
	<property name="proxyRegistry">
		<bean class="com.reignite.messaging.MessagingProxyRegistry">
			<property name="typeEditor" ref="delegatingTypeEditor" />
		</bean>
	</property>
</bean>
<bean id="delegatingTypeEditor"class="com.reignite.messaging.proxy.DelegatingTypeEditor" />
<bean id="endpoint"class="com.reignite.messaging.server.AMFEndpoint">
	<constructor-arg ref="ramfServer" />
	<property name="destinationMap">
		<util:map>
			<entry key="securityService" value-ref="securityDestination" />
		</util:map>
	</property>
</bean>
<bean id="securityDestination"class="com.reignite.messaging.server.SpringInitializedDestination">
	<property name="name" value="securityService" />
	<property name="target" ref="securityService" />
	<property name="typeEditor" ref="delegatingTypeEditor" />
</bean>

You can see there is a RAMFserver at the top.  It has an endpoint locator, codec locator and an error version.  The endpoint locator is listed later on as is the codec locator.  The error version just says what version of AMF any errors are encoded to.  If you are using Flex clients to talk to the RAMFserver then set error version to 3 other wise to 99.

The endpoint locator maps a url to an endpoint.  An endpoint is a collection of services.  In this way you could use this server to collect together several different sets of services by mapping different endpoints.  In practice though you’ll probably only have one endpoint to locate.

The codec locator maps AMF versions to serialisers and deserialisers.  The above config only maps version 99, but if you look in the source code you’ll find AMF3SerializeWorker and deserialize worker too.  So you can support both Flex and js clients if you want.

The delegating type editor is the thing that converts types from the client to types in the server.  EG: Javascript doesn’t have ArrayList but Java does.  So Javascript sends an array and the TypeEditor sees you are trying to put an array where an ArrayList is wanted so it converts it.

The Endpoint is a map from destination name to Spring configured service.  As an example I have a securityDestination.

I encourage you to look through the code of all of these because there are all sorts of different configuration details you can use.  Also you should note that numbers that come through as undefined or NaN are converted to java null.

I hope this has helped.  You will still need to do some trial and error and look through the source code and read my comments in it.

You’ll see error messages like:

Fatal error: cannot allocate memory for the buffer pool

mysqld dead but subsys locked

And so on.  Her is a quick way to create a swap file (makes your system perform better anyway)

1. dd if=/dev/zero of=/swapfile bs=1M count=1024
2. mkswap /swapfile
3. swapon /swapfile
4. Open /etc/fstab and add this line /swapfile swap swap defaults 0 0

Thanks to: http://www.prowebdev.us/2012/05/amazon-ec2-linux-micro-swap-space.html

For that info.

AMF

As a quick refresher AMF is an open source communication protocol developed by Adobe and implemented in Java in BlazeDS.  It is a highly compact binary protocol that accommodates object remoting and remote procedure calls.  The difference between a binary protocol and a non-binary is that a binary protocol just stores the numeric value of a data item instead of spelling it out using characters.  Thus the number 32,342 is represented by 4 bytes as an integer whereas in XML or JSON it is represented by 5 bytes (one for each character).  This becomes particularly useful with very long numbers like date / time expressions.  The other difference is that AMF uses references for repeated data meaning if you send a list of objects all the same type, the type information is sent only once and a byte reference is used for each additional occurrence.  In all, AMF is up to 10 times more efficient than XML and probably around 5 times more efficient than JSON.

AMF in GWT

Previously I created an AMF client in GWT and compiled that to Javascript which our UI guys used.  This resulted in heavy code that was easy to maintain by me, as a Java developer, but hard to maintain and understand for Javascript developers.

Greater Efficiency

Reignite has moved into the mobile application space in a big way.  We’ve taken our enterprise development mindset and applied it to the mobile space to create robust, scalable and maintainable apps.  But one of the big challenges with mobile apps is bandwidth and memory efficiency.  That is, end users may have relatively small data allowances for their devices and they need all their apps to use it.  So we would like to keep as small a footprint as possible.  We are also aware that wireless speeds are a bit up and down so we need our service calls to be fast.  To that end I threw out BlazeDS and turfed the GWT implementation of AMF to replace it with my own version.  RAMF or AMF version 99 does away with all the legacy Flash interaction and cuts out several unneeded features.  As a result each service call is from 2 bytes to about 100 bytes smaller.  It doesn’t sound like much, but it adds up on the server side when you have to pay for bandwidth for possibly tens or hundreds of thousands of users.

AJAX and Character Encoding

As anyone who has done AJAX calls before knows, the HTML 4 XMLHttp Object can only pass character data to and receive character data back from a server.  So how do you deal with a binary protocol that sends bytes instead?  (HTML 5 has web sockets that allow byte data transmission)  The most common way is Base64 encoding.  But this means taking a step backward in the bandwidth stakes.  This is because Base64 uses 4 bytes to encode 3.  Thus Base64 is 33% fatter than pure binary.  But is Base64 the only way to go?  Nope.  I searched long and hard until I found Y-Enc.  Inspired by Y-Enc I created my own encoding that escapes only negative byte values (positive byte values can be equated to UTF-8 characters).  Since most bytes in an AMF stream are positive I could get away with it.  The results are about 20% smaller message sizes than Base64.  This is really helpful in large requests.  In doing the encode / decode it was important to ensure all data was being sent and received in UTF-8 otherwise it all went south very quickly.

The Upshot

The upshot of all of this is Reignite now has a pure Javascript implementation of AMF without the weight of any legacy Flash code.  The server side is implemented in Java and uses Spring to configure it meaning fewer configuration files and greater flexibility.  The server implementation can execute remote procedure calls not only from this new AMF but is backward compatible (to support our old clients) and can be configured to support REST, SOAP and in the future web sockets.

Number One Tip

Javascript uses 64 bit numbers but does bitwise operations on only 32 bit numbers.  This means I had to grab an implementation of Long from Google code to allow me to parse 64 bit numbers that came over the wire (such as date / time values and some UTF characters).

1. they are abandoning the Flash Plugin on Mobile Devices

2. they are contributing Flex to the Apache Foundation

Basically Adobe is moving away from Flash and towards HTML5.

As Reignite is one of the premier builders of Flex Applications in Australia you would be correct in thinking that this will have some impact on our business and our clients. However the writing has been on the wall for quite a while now and fortunately we saw this coming!

When Steve Jobs effectively banned the Flash Plugin on iOS it sent alarm bells ringing at Reignite. This was nearly 2 years ago now and at that time we were about to launch into Smart Phone App development. We had originally thought that we would simply leverage our then 5+ years of experience with Flex writing online applications to now use Flex to write mobile applications. Apple made sure this was not going to happen. After a quick assessment of a plethora of mobile “write-once-deploy-many” frameworks we realised that nothing was as mature as Flex. It became pretty clear that in the absence of Flex on the mobile that the only real alternative to write quality applications would be to write mobile apps in their native languages. Accordingly we added Objective C and Android skills to the team and we have since built many successful mobile applications.

With more and more people browsing the web via phones and tablets it also soon became apparent that even online applications built in Flex were now under threat. Accordingly we added GWT skills to the team.

So by keeping an eye on our industry and interpreting the trends and moods of developers, technology organisations and the wider Internet community Reignite has predicted the changes coming, put plans in place well ahead of time and now we are well positioned to help all our clients evolve into a HTML5 future.

Reignite will still be one of Australia’s premier developers of online applications however the tools we use to do this have changed. So now we don’t just build online applications that live in the browser but we build multi-screen applications that can run on just about any device including smart phones, tablets, desktops, browsers, smart TVs and so on. Also our partnership with Adobe will not change either, Flex may “catch a second wave” with its contribution to Apache, Adobe’s acquisition of PhoneGap was a very positive move, Adobe makes regular contributions to jQuery and Adobe’s development and graphics tools are still industry leading. All of this means Adobe is still a very relevant company in this space.

I am an existing Reignite Client with a Flex application what do I do?

There is no need to be alarmed, Adobe’s decisions will not have any immediate impact on any of our clients. All your applications will work exactly as they did yesterday and will continue to run for years to come. What we will need to do is look at the future of your applications and assess the correct time (if any) to migrate them over to HTML5. Our friends at Whotune.com wont mind me telling you that we started migrating their Flex application one feature at a time from Flex to GWT several months ago. The site as it exists today is a hybrid HTML5 and Flex application.

Will you continue to write Flex Code and provide Flex Skills to our team?

Yes! All of our developers are already multi-skilled in several languages, mostly Java and Flex. Having a Java and Flex background is the perfect foundation to become a HTML5 developer and as such all of our existing developers will be adding HTML5 to their skill sets. This will enable them to continue to write Flex Applications and provide Flex skills and provide Flex mentoring where needed.

It is unlikely from now on that Reignite will build entirely new green-field projects in Flex, however it is worth pointing out that there are still many areas where Flex is still far superior to HTML5 which is relatively immature.

Does this have any impact on the server side of my application?

No! Reignite has developed all of its applications using a best practice n-tiered architecture. This means that the interface tier implemented in Flex can simply be replaced by a new technology like HTML5 without impacting on the server at all. As part of our migration to various HTML5 based interface development technologies including GWT and PhoneGap we have developed the mechanisms to communicate from the new technology to our existing server side applications. On nearly all of our projects this communication is performed via AMF an open source protocol from Adobe. Reignite has written AMF clients for GWT and JavaScript to allow our new interfaces to connect and communicate with our existing back end services. Good architecture definitely pays you back handsomely in the long term!

If you have any further questions then please do not hesitate to contact me directly or add a comment to this blog.

Russell Francis
Managing Director

What is GWT?

GWT is Google Web Toolkit.  It is a base level development kit that cross compiles Java into a Javascript web application.  It allows developers familiar with the Eclipse suite of Java productivity tools to quickly develop and easily support ajax applications.

What I did

I created a new user interface for an existing application that had substantial investment in services provided by BlazeDS, Adobes Java implementation of an AMF server.  So rather than recreate all my services using GWT remote procedure calls, I created an AMF client that would compile to Javascript.  It turns out it is fairly complex work to do, but fun.

Major hurdles

The major hurdles in converting a Java AMF client to Javascript are:

1. No dynamic class loading.  This means that while I can instantiate classes on the fly and I can use the instanceof operator, I can’t instantiate objects from class variables, only class literals.  To get over this one, I created a code generator that reads in all your remote objects and creates object proxies for them.  These object proxies are then registered in a big map that maps the remote class name to the local proxy.  This way, when I want to instantiate an object, I get the proxy and use it as a factory to do the work without reflection.
2. No java.io package.  Ouch.  This hurt because it meant I had to create my own implementations of InputStream and OutputStream (amongst a few other related classes).  That all seemed to go fairly well, but there’s more to that below.
3. Ajax calls can only pass strings over HTTP.  AMF is a binary protocol, which makes it more efficient than text based ones.  It uses object references and bitwise encoding to make your packets small and your objects easy to recreate.  It also means you need to base 64 encode your AMF payload.  I then had to put a filter on my server to detect base 64 and decode it.  This adds some overhead to each request, but not much.

Today’s big issue

Having over come the above issues I thought it was all smooth sailing, until I found my Date objects weren’t serialising and deserialising correctly.  For some unknowable reason, Blaze encodes dates as doubles, even though it is encoding the millisecond time which is a long.  That means the time is cast to a double and then encoded using IEEE 754 encoding.  Now to save you some time if you ever have the same need.

Decoding a Double from a Long

A double is encoded in three parts, the sign, exponent and mantissa (cool word, look it up).  Essentially you need to break the 64bit integer (long) into chunks and each chunk is then multiplied together.  The left most bit, the one in bit position 63 (0 index) is 0 for positive numbers and 1 for negative numbers

int sign =  ((bits >> 63) == 0) ? 1 : -1;

Then the exponent is bits 52 – 62.

int exponent = (int) ((bits >> 52) & 0x7ffL);

But the exponent is what as known as “biased” and is stored with an offset so the actual exponent is exponent – 1075

Finally the mantissa

long mantissa = (exponent == 0) ? (bits & 0xfffffffffffffL) << 1 : (bits & 0xfffffffffffffL) | 0x10000000000000L;

The actual double value is gained thusly:

double result = sign * mantissa * Math.pow(2, exponent - 1075);

Encoding a double to a long

This is the tricky one and my solution is probably inefficient, but it works and produces the same output as Double.longBitsToDouble() (which you can’t use in GWT because it calls native methods)

double v = the double you want to encode;
long bits = (long) v;
long total = 0;
if (v == 0.0) {
	total = 0;
} else {
	Double test = Double.valueOf(v);
	 if (test.isNaN()) {
		total = 0x7ff8000000000000L;
	} else if (v == Double.POSITIVE_INFINITY) {
		total = 0x7ff0000000000000L;
	} else if (v == Double.NEGATIVE_INFINITY) {
		total = 0xfff0000000000000L;
	} else {
		 if (bits < 0) {
			total = 0x8000000000000000l;
			bits = Math.abs(bits);
                        v = Math.abs(v);
		}
		int lastExponent = 0;
		 while (bits >> lastExponent > 0) {
			lastExponent++;
		}
		long exp = (lastExponent + 1022) * (long) Math.pow(2, 52) + 1;
		double man = v / (Math.pow(2, lastExponent - 1)) - 1;
		int count = 52;
		StringBuilder out = new StringBuilder();
		while (man > 0 && count > 0) {
			man = man * 2;
			if (man > 1) {
				man--;
				out.append("1");
			} else {
				out.append("0");
			}
			count--;
		}
		long manLong = out.length() == 0 ? 0 : Long.valueOf(out.toString(), 2);
		total += exp + manLong;
	}
}
writeLong(total);

As you can see I ran out of mathematical inspiration and reverted to binary as a string.  For those who are knowledgeable enough and patient enough I’m sure you can replace the binary string, but the above does work.

There is so much more to do with writing an AMF client in GWT and more I can say about GWT, but that will have to wait until  next time.

Definitions

First up, let’s get our terms defined so we know what’s what.

Flex:

For those who believe all Flash is created equal, you’ll need to change your way of thinking.  There are three different things when talking Flash: Flash Runtime, Flash Creative Suite and Flex.  The Flash Runtime is the thing that runs in your browser and allows Flash files (.swf) to run.  It can be compared to the Java Virtual Machine.  Flash Creative Suite is a program you can use to create Flash files.  It is a bit of Photoshop and a bit of programming that lets you write code and create animations, interactions and images.  Then there is Flex.  Flex is an object oriented, enterprise application development framework that uses Actionscript.  It is a way to create rich featured applications that run on the Flash Runtime.  If you want a spinning logo or page banner, you’d use Flash.  If you wanted a multi-user n-tier enterprise wide, data driven application, you’d use Flex.

HTML 5:

HTML 5 is a standard that specifies a set of markup tags for laying out documents that can be viewed in a web browser.  In general, when someone talks about creating a site in HTML 5 (or any version of HTML) they are usually also talking about the use of cascading style sheets and Javascript as well.

Should you use HTML 5 Rather than Flex?

I suppose you want a yes or no answer?  My answer is, like always, use the tool that makes the most sense at the time.  You wouldn’t use a hammer to drive a screw and you wouldn’t try to polish your car with sandpaper, would you?  So why would you say HTML 5 is better than Flex, or vice versa?  I wouldn’t.  Recently, a client asked what we thought of converting their application from Flex to HTML 5.  I said it would be an expensive and fruitless endeavour.  The reason was not because it couldn’t be done, but rather, for the complexity of application the client had, it would not work out.

Enterprise Values:

When developing an application, as opposed to a web site, there are certain extra factors you need to keep in mind:

• Maintainability: Once put into production, the application needs to be able to be updated and modified easily and cheaply.
• Scalability: On application needs to be able to cope with increases in size and use.
• Reliability: The application needs to be reliable.
• Extensibility: The application needs to be easily expanded beyond its original scope.

Flex is object oriented, compiled and can be developed using Flash Builder (the name is confusing, I know).  The feature set supported by the Flash runtime and the code base available to Flex is maintained by Adobe, a single company with a single vision.  This means that if I write a Flex application and it works well on my computer, it will work well on someone else’s computer too.  It also means that I can hand my code over to one of my colleagues and they can immediately continue work on it.  HTML 5 is a standard that specifies certain behaviours but not implementations.  Each browser vendor creates their own interpretation of how it should all work.  Some implement optional features, some invent their own features and some simply don’t comply with the standards.  The features supported by one version of a browser may not be supported by the next version and so on.  As a result, trying to write a complex application in HTML/Javascript/css turns into a nightmare game of tail-chasing.  Does this mean HTML 5 should not be used?  Heck no.  HTML 5 is a fantastic, modular and flexible way to create web sites.  It provides a quick and easy way to put content into the web and because it is light-weight, you can create small sites much faster than you could with Flex.  But until someone creates a standard and stable implementation, used by all vendors, it just can’t pass muster for large and complex projects.  People will disagree with me, but I think that would be a matter of how they define large or complex.

Summary

HTML vs Flex is horses for courses.  If you want to build an application, particularly an enterprise level one, you would be best served by Flex.  Its stable and predictable performance and ease of maintenance and extensibility will save you many hours and many dollars.  HTML is much better for company web sites or single purpose applications where you will not be doing a lot of expanding or maintenance work.  Mind you, I won’t be surprised when Adobe releases a compiler that will turn Flex code into HTML 5 content so the future might well belong to HTML.

Imagine the scenario where you have two application servers behind a hardware load balancer.  Imagine that the load balancer uses “round-robin” style balancing.  That is, rather than using sticky sessions to associate a client machine with a single server for the duration of their session, the load balancer simply alternates which machine each request goes to.

The Problem:

The problem is that BlazeDS stores client subscriptions at the servlet level, that is in the server context.  So when the subscribe message from the client hits the server, Blaze creates a subscription that is stored in the memory (web context) of that servlet container.  Then the client sends a poll request for data and the load balancer flicks it off to the other server.  You can see that the second server would have no knowledge of the client and would return a “no subscription found” error and so the client would attempt to re-subscribe.  That new subscription message would be directed to the original server, which would say “I’ve already got your subscription”.  The funny business would repeat until the client finally quits.

Possible Solutions:

1. Blaze comes with JGroups clustering.  You could use this to flick messages about the place.  I tried it, and it worked a bit.  What tended to happen though is that servers would drop out of the JGroups cluster and not re-merge, or messages would be delayed and get out of sync or the gremlins would eat the packets.  I’m not really sure why these things happened, but it was completely unacceptable for a business critical, software-as-a-service application.
2. I tried using the Apache Tomcat session replication feature.  It was pretty easy to set up and as easy to break.    It worked, sort of, but I had the same issues of unreliable message propagation.  The way Tomcat detected a dirty session was by looking at attribute changes in the session context, not several layers in to an object in the context.  Blaze keeps a subscription object with a list / map of messages and connected clients.  Tomcat couldn’t detect the changes that happened deep inside that subscription object, so I had to manually muck about.  Suffice to say it was a mess.

So What Works?

Taking a leaf from my old middleware days playing in the Victorian (state of Australia, not during the reign of the Queen) Power Market, I decided to use the database to guarantee message delivery.  The system I was working on used MySQL with two way replication.  That is, each app server had an instance that was both the master of, and slave to, each other.  If you haven’t used it before, MySQL server replication as of v5.1 is extremely reliable over two computers and very quick.  In over 2 years of operation, this set up has failed only twice.  Both of those failures were due to operating system crashes caused by unexpected shutdown situations.

Solution Part One:

Create two new tables in the DB: subscription and message.

DROP TABLE IF EXISTS `subscription`;CREATE TABLE  `subscription` (  `ID` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,  `CLIENT_ID` VARCHAR(100) NOT NULL,  `MESSAGE_CLIENT_ID` VARCHAR(100) NOT NULL,  `SELECTOR` VARCHAR(255) DEFAULT NULL,  `EXPIRY_DATE` datetime NOT NULL,  `LAST_MESSAGE_ID` INT(10) UNSIGNED NOT NULL,  `CREATED_DATE` datetime NOT NULL,  `MODIFIED_DATE` datetime NOT NULL,  PRIMARY KEY (`ID`),  UNIQUE KEY `Index_CLIENT_ID_UNIQUE` (`CLIENT_ID`)) ENGINE=InnoDB AUTO_INCREMENT=17 DEFAULT CHARSET=latin1;

and

DROP TABLE IF EXISTS `blaze_message`;CREATE TABLE  `blaze_message` (  `ID` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,  `MESSAGE_BYTES` BLOB NOT NULL,  `MESSAGE_BODY` text,  `CREATED_DATE` datetime NOT NULL,  `MODIFIED_DATE` datetime NOT NULL,  PRIMARY KEY (`ID`)) ENGINE=InnoDB AUTO_INCREMENT=152 DEFAULT CHARSET=latin1;

When a client subscribes to a server, an entry is placed in the subscription table.  Then, when that same client polls, either server can get the subscription from the DB and service it.  The DB takes care of replicating the subscription to each server, and it does it very well.  But what is stored?

CLIENT_ID: this is the unique id created by the instance of Flash or Air.

MESSAGE_CLIENT_ID: this is the unique id created by the instance of the consumer running on Flash or Air.  You can let Flash/Air create this for you, but we like to append our own user id to the end of it so we can make sense of log messages and such.

SELECTOR: Adobe have implemented the idea of “selectors” to channel messages to different consumers.  For example we have normal users and admins.  Normal users receive only those messages meant for them based on role and client company (software as a service) but admins get all messages.

LAST_MESSAGE_ID: This is how I guarantee delivery of messages.  Messages are queued in the message table and each subscriber receives all messages from the last id to the most recent, in that order.  That way, if a poll goes missing we can keep the message around until the client gets it.

When a message is to be sent, the publisher inserts a record of it in the message table.   The main bit to see is the MESSAGE_BYTES column which is simply the Blaze message object serialized using an ObjectOutputStream.  I also store the text representation of the message body (XML) so I can trace it in logs and so on.  Every so often I clean out the message table by removing all messages that have been received by all subscribers.  I check that by looking at the LAST_MESSAGE_ID in the subscription table.

Solution Part Two:

So part one covered the database side of things, but you want to know how I made Blaze play by the new rules… I extended a couple of classes .  One that takes care of subscriptions and one that takes care of publishing.

In my messaging-config.xml file, instead of using the standard adapter, I created my own:

package au.com.reignite.amf;
 
 
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.ObjectOutputStream;
 
 
import org.springframework.context.ApplicationContext;
import org.springframework.web.context.support.WebApplicationContextUtils;
 
 
import au.com.reignite.logging.LogWriter;
import au.com.reignite.orchestration.MessageOrchestrator;
import flex.messaging.FlexContext;
import flex.messaging.MessageDestination;
import flex.messaging.config.ConfigMap;
import flex.messaging.messages.AsyncMessage;
import flex.messaging.messages.CommandMessage;
import flex.messaging.messages.Message;
import flex.messaging.services.messaging.SubscriptionManager;
import flex.messaging.services.messaging.adapters.MessagingAdapter;
 
 
public class DatabaseMessagingAdapter extends MessagingAdapter {
 
 
 private String messageOrchestratorName = "messageOrchestrator";
 
 
 private MessageOrchestrator messageOrchestrator;
 
 
 @Override
 public Object invoke(Message message) {
 // just store this message in the database queues
 // when the client polls for messages it will get
 // them direct from the db. If there aren't any
 // in the db it will wait and the server will poll
 // the db on behalf of the client until timeout or
 // a message is returned.
 
 
 ByteArrayOutputStream bos = new ByteArrayOutputStream();
 ObjectOutputStream out;
 try {
    out = new ObjectOutputStream(bos);
    out.writeObject(message);
    getMessageOrchestrator().storeMessage(bos.toByteArray(),
    message.getBody().toString());
 } catch (IOException e) {
    LogWriter.error(getClass(), "Failed to serialize message: " + e, e);
 }
 
 
 return null;
 }
 
 
 /**
 * @see flex.messaging.services.ServiceAdapter#handlesSubscriptions()
 */
 @Override
 public boolean handlesSubscriptions() {
    return true;
 }
 
 
 /**
 * Manages subscriptions and unsubscriptions. In particular the creation of
 * subscriptions in the database.
 * 
 * @see flex.messaging.services.ServiceAdapter#manage(flex.messaging.messages.CommandMessage)
 */
 @Override
 public Object manage(CommandMessage commandMessage) {
   if (commandMessage.getOperation() == CommandMessage.SUBSCRIBE_OPERATION) {
       LogWriter.info(getClass(), "SUBSCRIBE: "
       + commandMessage.getClientId() + " in MessagingAdapter");
       MessageDestination destination = (MessageDestination) getDestination();
       SubscriptionManager subscriptionManager = destination
       .getSubscriptionManager();
       String selectorExpr = (String) commandMessage
       .getHeader(CommandMessage.SELECTOR_HEADER);
       subscriptionManager.removeSubscriber(commandMessage.getClientId(),
       selectorExpr, (String) commandMessage
       .getHeader(AsyncMessage.SUBTOPIC_HEADER_NAME),
       (String) commandMessage.getHeader(Message.ENDPOINT_HEADER));
       getMessageOrchestrator().storeSubscription(
       FlexContext.getFlexClient().getId(),
       commandMessage.getClientId().toString(), selectorExpr);
    } else if (commandMessage.getOperation() == CommandMessage.UNSUBSCRIBE_OPERATION) {
       if (FlexContext.getFlexClient() != null) {
           LogWriter
           .info(getClass(), "UNSUBSCRIBE: "
           + commandMessage.getClientId()
           + " in MessagingAdapter");
           getMessageOrchestrator().deleteSubscription(
           FlexContext.getFlexClient().getId());
        }
    }
    return null;
 }
 
 
 /**
 * @see flex.messaging.services.messaging.adapters.MessagingAdapter#initialize(java.lang.String,
 *      flex.messaging.config.ConfigMap)
 */
 @Override
 public void initialize(String id, ConfigMap properties) {
    super.initialize(id, properties);
    messageOrchestratorName = properties.getPropertyAsString(
    "message-orchestrator-name", "messageOrchestrator");
 }
 
 
 /**
 * @return the messageOrchestratorName
 */
 public String getMessageOrchestratorName() {
    return messageOrchestratorName;
 }
 
 
 /**
 * @param messageOrchestratorName
 *            the messageOrchestratorName to set
 */
 public void setMessageOrchestratorName(String messageOrchestratorName) {
    this.messageOrchestratorName = messageOrchestratorName;
 }
 
 
 /**
 * @return the messageOrchestrator
 */
 public MessageOrchestrator getMessageOrchestrator() {
    if (messageOrchestrator == null) {
        ApplicationContext appContext = WebApplicationContextUtils
        .getRequiredWebApplicationContext(FlexContext
        .getServletContext());
        messageOrchestrator = (MessageOrchestrator) appContext
       .getBean(messageOrchestratorName);
    }
    return messageOrchestrator;
 }
}

The important bits:

INVOKE: The invoke method serialises the Blaze message object and stores it in the database as a new message.  The MessageOrchestrator object I’m using is just my service for database persistence, you would use your own method there.

HANDLESSUBSCRIPTIONS: You need to make sure you return true, for obvious reasons.

MANAGE: This method actually manages the subscriptions and unsubscriptions.  You can see that when I get a subscribe message I log a bit of info, grab a stack of info from the message and store it using the MessageOrchestrator.  The fancy bit of trickery I do in here is to use the Blaze SubscriptionManager to remove a subscriber.  That sounds like the opposite of what I want to do, but the problem is that Blaze store the subscription even though I’m managing it myself.  So I take it out of Blaze to keep things clean.  In the case of an unsubscribe message I just log it and delete the subscription from the DB.

The second class I had to extend was Endpoint.  Thusly:

package au.com.reignite.amf;
 
 
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.ObjectInputStream;
import java.util.ArrayList;
import java.util.List;
 
 
import org.springframework.context.ApplicationContext;
import org.springframework.web.context.support.WebApplicationContextUtils;
 
 
import au.com.reignite.domain.message.BlazeMessage;
import au.com.reignite.domain.message.Subscription;
import au.com.reignite.logging.LogWriter;
import au.com.reignite.orchestration.MessageOrchestrator;
import flex.messaging.FlexContext;
import flex.messaging.MessageException;
import flex.messaging.client.FlexClient;
import flex.messaging.client.FlushResult;
import flex.messaging.config.ConfigMap;
import flex.messaging.endpoints.ConfigurableAMFEndpoint;
import flex.messaging.messages.CommandMessage;
import flex.messaging.messages.Message;
import flex.messaging.services.MessageService;
import flex.messaging.services.messaging.selector.JMSSelector;
 
 
/**
 * An AMF endpoint that is not only configurable (may configure additional amf
 * filters) but also uses the database as a backing for poll commands.
 * 
 * @author Surrey
 * 
*/
public class DatabaseConfigurableAMFEndpoint extends ConfigurableAMFEndpoint {
 
 
	private String messageOrchestratorName = "messageOrchestrator";
 
 
	private Long dataBasePollMillis = 500l;		
 
 
	private MessageOrchestrator messageOrchestrator;
 
 
	/**
	* Polls the database instead of using the flex client. It is necessary to
	* divert the normal poll action here because in an environment with
	* multiple blaze servers it is unknown which server a poll will be against
	*  but the normal polling requires the poll to be against the same server as
	* the subscription. Subscriptions are held in the database and are managed
	* and timed out by a separate reaper thread.
	* 
	* @see flex.messaging.endpoints.AbstractEndpoint#handleFlexClientPollCommand
	*      (flex.messaging.client.FlexClient,
	*      flex.messaging.messages.CommandMessage)
	*/
	@SuppressWarnings("unchecked")
	@Override
	protected FlushResult handleFlexClientPoll(FlexClient flexClient,
	CommandMessage pollCommand) {
		LogWriter.info(getClass(), "HANDLE_FLEX_CLIENT_POLL: "
		+ flexClient.getId());
		FlushResult result = null;
		Subscription subscription = getMessageOrchestrator().loadSubscription(
		flexClient.getId());
		if (subscription == null) {
			LogWriter.info(getClass(), "CLIENT: " + flexClient.getId()
			+ " has no subscription.");
			MessageException e = new MessageException();
			e.setMessage(10028, new Object[] { getId() });
			e.setCode(MessageService.NOT_SUBSCRIBED_CODE);
			throw e;
		}
		// begin wait and poll of the database
		long wait = 0;
		JMSSelector jmsSelector = new JMSSelector(subscription.getSelector());
		Integer lastMessageId = subscription.getLastMessageId();
		do {
			// get messages and check for match of selector
			List<BlazeMessage> msgs = getMessageOrchestrator().loadMessages(
			lastMessageId);
			for (BlazeMessage blazeMessage : msgs) {
				lastMessageId = blazeMessage.getId();
				ByteArrayInputStream bin = new ByteArrayInputStream(
				blazeMessage.getMessageBytes());
				ObjectInputStream in = null;
				try {
					in = new ObjectInputStream(bin);
					Message message = (Message) in.readObject();
					if (jmsSelector.match(message)) {
						if (result == null) {
							result = new FlushResult();
							result.setMessages(new ArrayList());
						}
						message.setClientId(subscription.getMessageClientId());
						result.getMessages().add(message);
					}
				} catch (Exception e) {
					LogWriter.error(getClass(), "Failed to deserialize: " + e, e);
				} finally {
					if (in != null) {
						try {
							in.close();
						} catch (IOException e) {
							// do nothing
						}
					}
				}
			}
			if (result != null) {
				break;
			}
			// there were no matching messages so wait and check again
			try {
				wait += dataBasePollMillis;
				synchronized (this) {
					this.wait(dataBasePollMillis);
				}
			} catch (InterruptedException e) {
				// do nothing
			}
		}while (wait < waitInterval);
		LogWriter.info(getClass(), "END POLL for: " + flexClient.getId());
		getMessageOrchestrator().storeSubscription(subscription.getClientId(),
		subscription.getMessageClientId(), subscription.getSelector(),
		lastMessageId);
		return result;
	}
 
 
	/**
	* @return the messageOrchestrator
	*/
	public MessageOrchestrator getMessageOrchestrator() {
		if (messageOrchestrator == null) {
			ApplicationContext appContext = WebApplicationContextUtils
			.getRequiredWebApplicationContext(FlexContext
			.getServletContext());
			messageOrchestrator = (MessageOrchestrator) appContext
			.getBean(messageOrchestratorName);
		}
		return messageOrchestrator;
	}
 
 
	/**
	* @return the messageOrchestratorName
	*/
	public String getMessageOrchestratorName() {
		return messageOrchestratorName;
	}
 
 
	/**
	 * @param messageOrchestratorName
	 *            the messageOrchestratorName to set
	 */
	public void setMessageOrchestratorName(String messageOrchestratorName) {
		this.messageOrchestratorName = messageOrchestratorName;
	}
 
 
	/**
	* @return the dataBasePollMillis
	*/
	public Long getDataBasePollMillis() {
		return dataBasePollMillis;
	}
 
 
	/**
	* @param dataBasePollMillis
	*            the dataBasePollMillis to set
	*/
	public void setDataBasePollMillis(Long dataBasePollMillis) {
		this.dataBasePollMillis = dataBasePollMillis;
	}
 
 
	/**
	* @see flex.messaging.endpoints.ConfigurableAMFEndpoint#initialize(java.lang
	*      .String, flex.messaging.config.ConfigMap)
	*/
	@Override
	public void initialize(String id, ConfigMap properties) {
		super.initialize(id, properties);
		messageOrchestratorName = properties.getPropertyAsString(
		"message-orchestrator-name", "messageOrchestrator");
	}
}

The Important Bits:

HANDLEFLEXCLIENTPOLL: In essence all I’m doing here is grabbing enough info from the poll request to pull the subscription from the database, check the selector and if it matches, I return the message.  I update the subscription with the message id as the LAST_MESSAGE_ID so I know where I’m up to.  Of course there is a stack of logging and error catching going on as well.

There you go.  You update your config xml to use this endpoint and that adapter and away you go.  This messaging system has worked very well for a couple of years now.  I am about to do some reworking of it in cooperation with flex client changes to handle “delivery in doubt” messages.  These are the ones where the client sends a poll, but for some unknown reason it doesn’t reach the server properly.  At present this causes a retry, but Justin and I want to make it a bit more water tight so push messaging is 100% reliable.

Till next time,

Surrey.

I Know TLF 2 is in development and around the corner but unfortunately we couldn’t wait.  We had the requirement to move to the more stable TLF from the old Flash TextFields but also needed to render bullets.

The most common solution I’ve seen to combat this issue is the use of the Bullet Unicode character appended to a paragraph or span element.  This poses a number of problems.

1. Bullets are editable (which can be worked around by shifting the selection any time a user clicks into or keys into the bullet region)
2. Bulleted paragraphs do not wrap gracefully.  List Items that span multiple lines will need different indents if the font size changes due to the fact that the Bullet Character’s width will change so lists will not line up as expected.

There are more issues we encountered but unfortunately I don’t have all day to go through each in detail

As another solution I wrote a function that loops through the textlines in the flow composer on each composition_completion and draw’s bullets on a child layer of the RichEditableText based on a styleName of the paragraph.

You can view the source by clicking here

Enjoy!

J.