Those of us investing time in developing AIR apps have been working with one hand tied behind our back, unable to do simple things like even launch a document in MS Word, let alone utilize the thousands of shell commands available inside the OS.  (Well, there are various alternatives and hacks to do similar things, but still…)  Simple functions like burning a CD or encoding an audio file were simply not possible because the underlying libraries that perform these functions are not accessible within the AIR sandbox – even if those libraries themselves are cross platform.  None of the other major cross-platform environments have this limitation.  AIR was designed to connect to a server via HTTP in order to do these types of things, which is great for a web-based solution but not so for a desktop solution.  So AIR sometimes gets a bad rap as a a “widget” development platform that is good for eye candy, but not able to have deep interaction with the OS.

With AIR 2 Adobe decided to lift even more of the constraints and allow developer to execute native commands.  What this means is that we might start seeing very handsome AIR apps that serve as SVN front-ends, MP3 encoders, network monitoring tools, disk utilities, etc.   AIR will be able to interact with other software on the machine such as legacy enterprise apps.  I know this was not Adobe’s original vision for AIR, but  I have always thought otherwise and I’m very glad Adobe decided to loosen the shackles.  There are several other interesting improvements in version 2, but I think the native call feature has the potential to open the floodgates for enterprise developers.

With the new functionality comes the inevitable risk that some AIR apps will only run on one platform, or they may require you to install an OS-specific component in addition to the AIR application.  It will also be possible to build an AIR app that requires a certain Windows-only or OSX-only command.  However, thoughtful developers will at least be able to make that choice for themselves.

AIR 2 is out in beta now and end users will start seeing new applications when the public release launches in the first half of 2010.

If this is something that has caused you grief, I encourage you to vote for the issue to be fixed in the Flex SDK.

The crux of the problem is a combination of three things.  First that all Dates are timezone aware, yet they are “locked” to the local system timezone and the offset property is read-only.  The second is that all of the Date formatting functions and Date-related UI controls have no concept of timezone.  The third is that the Date class is marked Final, so there is no way for developers to extend the class and override the default behavior.  It almost seems like it was an intentional effort to prevent any apps from displaying anything other than local time, which is weird.  The unfortunate side effect of this design is that it forces developers to use very ugly hacks.

In my mind there would be two “correct” way to deal with this.  The first would be to allow the timezone offset property of a Date to be writable.  This would allow developers to store the correct UTC time but specify the offset of their choosing for input and display.  To me this makes the most sense and I don’t understand at all why it isn’t allowed unless there is some low-level feature of the Flash engine that makes this difficult.

A less optimal solution, if changing the timezone is not possible, would be to re-write all of the Date related UI controls and functions (formatters, etc) so that they can accept input and display output in a different timezone from the local system.  This would be a ton of work and you’d probably run into problems with third-party components that weren’t written the same way.  This would at least allow you to keep your date values stored correctly, though.

What developers are currently forced to do instead is to actually create Dates with incorrect UTC values in order to get them to display correctly.  If I have a meeting in NY at 5PM but I am physically in PST, I have to set the time to 5PM PST in order to show it on a calendar 5PM.  But 5PM PST is actually 8PM EST so this is not technically correct – the UTC value is off by 3 hours.  Flex of course wants this item to show up on my calendar as 2PM PST because it does not think a user would ever want to see time written in it’s relevant timezone.  When I pass this to the server, of course, I have to neutralize the senders timezone offset on the way in, and then account for the receiver’s timezone on the way out.

For now I’ve managed to work-around all of these issues, however it is a constant worry for my team since our users are managing events that take place around the world, some of them traveling to a new timezone every day.  I hope that Adobe will address this seemingly minor issue in a future release.

• NetConnection.Call.Failed: HTTP: Status 500
• Channel Disconnected

You may have tried directing your browser to weborb.php only to get this message: “WebORB v3.5.0 Fatal error: Call to a member function getServiceURI()”

The getServiceURI message is actually a red herring error message.  This simply occurs because weborb.php is expecting the raw headers to contain Flash remoting AMF message data.  Your browser is just making a normal HTTP GET and doesn’t know anything about AMF.   So weborb.php winds up with a null object on which it tries to call getServiceURI().  I wouldn’t be surprised to see a future release of WebORB that catches this error, even though it isn’t the purpose of this particular file to run inside a browser.

So, you are probably frustrated because you were trying to figure out what is wrong with your install and why you are getting the connection and/or channel errors.  These errors are almost always the result of a PHP compile-time error.  PHP5 itself is rather inconsistent in the way it handles different types of errors.  You may have noticed that it’s impossible to catch a syntax error or a bad path in a require_once() statement, for example.  If an include file is missing, PHP craps out before you have a chance to do any error handling.  You can only catch and handle run-time errors within your PHP code.  You may be tempted to think that WebORB should be able to catch these errors and return a more useful message to Flex, however the PHP engine stops executing before it even gives your code or WebORB a chance to handle anything.  It’s kinda the equivelant of having a syntax error in Java or C code that causes your app to not compile.  It doesn’t matter what type of error trapping code you write – if you code doesnt’ even compile, it doesn’t even get the chance to run.

When any part of either your service or WebORB encounters a compile-time error, it instantly dies and, depending on your server config, will write out the error details to STDOUT (which shows in a browser) but what it does not do is return a proper AMF message to the client.  If you were to look at the output of the PHP page, most likely you would instantly see cause of the error.  However Flex/Flash seemingly ignores the output of the page and it only processes the headers returned by the server (ie 500 error).  So PHP is outputing the details of the error but Flex blocks you from reading it.

UPDATE: I now use App Puncher to view error messages now.  A network proxy or packet inspector would probably work as well.  My original info below is still here in case you want to trace down errors by hand.

To figure these errors out, I try to start debugging with a simple function that doesn’t do anything.  Slowly, step-by-step I start re-enabling code until I locate the source of the channel disconnect by process of elimination.  Other times I write a debug page in PHP and call the function in question directly.  (This isn’t always easy if Flex is passing in complex structures, however, it can be worth the effort sometimes).

I’ve noticed these things to be sure-fire causes:

• require_once statement with file missing (or PHP include path not set right).  Note that if you are dynamically calculating the abolute path of the current working directory that it will be different when you are running via the “Management Console” than if you call your service directly from Flex.  This is a dead giveaway if it runs in one, but not the other.
• passing in an argument to a method that does not match the declared PHP type.  You can detect this by simply removing your type declaration in your methods and see if the data comes through.  This could indicate a mapping problem or an unsupported type.
• syntax error that causes PHP compile-time error.  This can be any type of silly syntax error.  These are usually easy to see if you create a server-side page that calls your service method.
• If the WebORB examples work, but not your own services, it’s pretty much a giveaway that PHP is crashing somewhere inside your own service code and not the WebORB installation.
• If you can’t even get the WebORB examples to work, then there is a good chance that editing PHP.ini will be required.  If that’s the case, hitting weborb.php with your browser can sometimes show you what’s wrong – just realize that any errors mentioning either getServiceURI() and FlashorbBinaryReader are due to the missing AMF headers that your browser didn’t send and are not the problem.

If you have a better way of debugging, please post a reply.  This can be an extremely frustrating error to chase down and I would welcome any suggestions.

The TextInput can be bound as well so that when the dataSource changes, the value of the TextInput will automatically update. However, unlike the DataGrid, changing the text of the TextInput will not automatically update the dataSource. Take the following code for example (assuming “source” is a String variable):

When the TextInput is changed, the value of source remains the same. It’s only bound one-way. If you want the value of source to be updated when TextInput changes, it’s actually easy, but there are at least five (5) different ways to do it of which I know. For the most straight-forward two-way binding, you could update the TextInput code like so:

Technically source is not bound to the TextInput, but it does produce the desired result. source is updated manually whenever the valueCommit event fires. The valueCommit event fires when the TextInput text has been changed onBlur (ie when when TextInput loses focus). If you prefer source to be updated on every key stroke, you can change valueCommit to change instead and the update will occur on every keyUp. If I’m updating a database or making a service call, I prefer valueCommit so the back-end code only fires once after the user is finished updating the field. If the TextInput is an ajax-style auto complete or lookup, the change event might be more desirable so the application can react after each key stroke.

As I mentioned there are five methods to do this. You can bind controls using Flex’s binding features in either MX code or ActionScript. Depending on your application one may be better than the rest as far as keeping your code clean and consistent. For the most part they all achieve the same result. Attached is source code that demonstrates all five techniques:

Download TextInputBinding.zip

If you know of any other ways to bind data to UI Controls, please post a comment.

Working with SQLite and Flex/AIR Date values can be tricky and various caveats are not particularly well documented. The confusion (for me) is that ActionScript is loaded with UTC functions, and SQLite will happily insert them into DATETIME columns. Everything appears fine, however SQLite does not actually recognize this format as a Date and treats it as plain text. You have no way to see this happened until you try to apply some date formatting functions and notice SQLite returning NULL. SQLite is so lax about data integrity that you can insert anything into any column type and will never receive any warnings. AIR, though, will attempt to cast values behind the scenes based on column types and so you will run into ‘Invalid Date’ errors and weird glitches when attempting to update data.

The magic solution is the Julian Date Format which both SQLite and AIR recognize as a date value. This is somewhat surprising as ActionScript has no built-in support for outputting Julian dates. If you’re like me, you may have already hacked up workarounds using int fields with timestamps, however your matching ActionScript class properties have to be hacked to match, and the hacking can trickle down throughout your code. This also prevents you from using the SQLStatement.itemClass functionality, which is nice when using Cairngorm, DAOs, value objects, etc.

To avoid the pain follow these rules when working with dates:

1. If you want a strongly typed Date field in AIR, the relevant SQLite column must be defined as DATETIME.  The interesting thing about this is that DATETIME is not technically a recognized SQLite column type and according to the SQLite docs it will be considered numeric.  But AIR is obviously looking at the column definition somewhere in the framework because it will refuse to automatically cast any value where the column type is not DATETIME.

2. Whenever inserting or updating DATETIME fields, you must store it in Julian format (or NULL).  SQLite will happily accept many common date formats. However AIR will behave inconsistently. Here is how to insert Julian dates in a variety of ways:

Inserting a Julian date manually via SQL:

To do this, simply have SQLite format your date value to Julian format using ‘%J’

UPDATE my_table SET my_column = STRFTIME('%J','2008-01-02 03:04:05')

Inserting a Julian date via AIR (with parameters):

Parameters are the best way to build SQL statements as you can use strongly typed Date variables and AIR will deal with the formatting for you.

statement.text = "UPDATE my_table SET my_column = :my_value";
statement.parameters[":my_value"] = new Date(2008,0,2,3,4,5); // Jan 02, 2008 03:04:05

Inserting a Julian date via AIR (without parameters):

If you are not using parameters, you have to pre-format the date into something that SQLite can parse. This is surprisingly obnoxious and requires you to write a couple of helper functions. (Note – if you know of an easier way to do this, please post a comment.)

public function lpad(original:Object, length:int, pad:String):String
{
var padded:String = original == null ? "" : original.toString();
while (padded.length < length) padded = pad + padded;
return padded;
}

public function toSqlDate(dateVal:Date):String
{
return dateVal == null ? null : dateVal.fullYear
+ "-" + lpad(dateVal.month + 1,2,'0')  // month is zero-based
+ "-" + lpad(dateVal.date,2,'0')
+ " " + lpad(dateVal.hours,2,'0')
+ ":" + lpad(dateVal.minutes,2,'0')
+ ":" + lpad(dateVal.seconds,2,'0')
;
}

var myDate:Date = new Date(2008,0,2,3,4,5); // Jan 02, 2008 03:04:05
statement.text = "UPDATE my_table SET my_column = strftime('%J','" + toSqlDate(myDate) + "')";

Fudging data to work around AIRs validation

If you absolutely refuse to change your schema (for example you insist on using timestamps, or you have to maintain compatibility with other clients) you can get AIR to play along during READ operations by altering your select statement like so:

SELECT STRFTIME('%J',my_column) as my_column from my_table

This does assume that the data is in a format that SQLite recognizes as a date. If SQLite can’t parse the date value, then it will just return NULL. For hilarity sake, you can also use this ridiculous date format which surprisingly works with AIR. A word of warning about this workaround is that, even though you will be able to read data, you may not be able to update data via SQLCommand parameters if your column types are DATETIME because AIR will complain about an invalid date (see errors below). You will have either have to write your own SQL statements without parameters or else change your column types to int or varchar.

Formatting a Julian date manually in SQL so you can read it:

Julian values are great and all that, but it’s pretty much impossible to eyeball them when you’re working at the command line. SQLite recognizes Julian formatting as a valid date, so you can use the STRFTIME function to format and output it any way you like. Below is a simple example that is easier to read:

SELECT STRFTIME('%Y-%m-%d %H:%M:%S',my_column) as my_column_formatted FROM my_table

Common errors that occur while working with dates:

Invalid Date

You may see this in a DataGrid instead of the expected date value. This is because you have a DATETIME column in SQLite, however the value is not in Julian format. Even though SQLite may recognize it as a date value, AIR does not. The solution is to clean your data so that all dates are Julian format, or alternatively change the column type to VARCHAR.

‘Error #3115: SQL Error.’, details:’could not convert string value to date’

This error occurs when you try to update a record that has one or more DATETIME columns that do not have the date stored in Julian format. The weird part is that even if you are not touching that specific column in your insert/update statement – AIR will still validate the Date and throw this error. The solution is to clean your data so that all dates are Julian format, or alternatively change the column type to VARCHAR.

If you have any tips or corrections please post a comment and I’ll incorporate it into the article.

SELECT
   CASE WHEN (  strftime('%m',my_column)   = '01') THEN ('Jan') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '02') THEN ('Feb') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '03') THEN ('Mar') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '04') THEN ('Apr') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '05') THEN ('May') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '06') THEN ('Jun') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '07') THEN ('Jul') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '08') THEN ('Aug') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '09') THEN ('Sep') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '10') THEN ('Oct') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '11') THEN ('Nov') ELSE '' END
|| CASE WHEN (  strftime('%m',my_column)   = '12') THEN ('Dec') ELSE '' END
|| STRFTIME(' %d %H:%M:%S GMT-0600 %Y', my_column)
FROM my_table