A File object represents a path to a file or directory.

Uh? Why? When you bring this up some people start banging about old paradigms such as “system nodes” and other ancient stuff. Well, I think whoever designed the AIR API lost a great opportunity to make a difference and start applying some usability to API design. This is most likely due to the old inferiority complex about ActionScript being a “serious” language that Java and C developers cannot look down to.

Well, how do you think Java and C developers explain it to Grandma?

Yeah, you have 2 types of files, one is for storing information, the other is a special type of file which can contain other files (of the first type) and other special files like itself.

Or

Yeah, you have files for your docs, and folders where you can group other files and folders. Y’know, like real life files and folders.

Best part is, since they are forcing the concept so much, they end up with ugly APIs and code. Let’s see:

Smelly code:

Smelly API:
File.isDirectory says it pretty much all:

Indicates whether the reference is to a directory. The value is true if the File object points to a directory; false otherwise.

“The reference“. Maybe they should’ve called the class Reference instead of File, then?

Also, if files and folders are the same, why there is File.deleteDirectory(deleteDirectoryContents) vs File.deleteFile()? Sure there should be a common method called File.delete(), right? Well, turns out that most systems don’t allow you to remove a non-empty folder without confirmation and thus the deleteDirectoryContents parameter.

So, convinced now? If you are not, then enjoy the official API. If you are, check out XAPI for AIR : )

Benefits (IMHO):

* No instances, all methods are static.
* Different File and Folder APIs with consistent method names.
* Much simpler API. Compare:

Reading the contents of a text file in plain AIR:

Using XAPI:

You decide : )

XAPI for AIR hasn’t been released yet, so if you can’t wait just go and checkout the code from Github. Once it’s done it will be released as a SWC, I guess.

Extra ball: XAPI for AIR would be almost 100% identical to XAPI for haXe which was the original implementation (differences due to platform limitations), so if you are up to developing build tools using haXe the jump would be much simpler cause you would be using the same (X)API.

We are developing at ustwo a very interesting internal little project that needs to run 24/7. By default developers should always be very careful with memory leaks and hogging resources, but with an AIR/Flash app running non-stop every detail counts.

To top it up, the app must handle images, SWFs (AS2, AS3) and videos without going through developers. That means marketing can contact one of the designers, ask s/he to produce someething and put it to display without developer approval. Oh, and all assets are in the network, not in the machine. Scary.

Preliminary tests show we are doing OK, we’ve been running the app non-stop for 4 days without a crash or needing it to reboot. The player takes and releases memory when it needs to, transitions and animations look as smooth as the first day, etc.

Check out below some of our thoughts.

FAIL, FAIL, FAIL

Shit will happen, so be ready to fail. Assets won’t load, video will have the wrong codec, image will be 80mb, network will be down….

That’s Google’s approach to servers. Instead of having a big fat multimillion dollar server, they have a farm of 100 mini-servers and they *know* one or two *will* crash everyday. They’ve build their systems to cope with failure and fail gracefully.

Also embed some default content for when everything else fails.

RELEASE, RELEASE, RELEASE

You must release resources. Explicitly remove every single listener you add, use FP 10 unloadAndStop and if you are in AIR don’t hold references to File objects (more about this in another post).

If you are a good dev, the Flash player will behave most of the times…

MONITOR, MONITOR, MONITOR

…but sometimes it won’t. Or something you didn’t even think was possible will happen in-your-face. You can’t prevent all errors, but you can react when they happen.

At the beginning we were trusting our own app to be its own watchdog, but then we got a nasty crash and obviously the watchdog failed as well. So we’ve created a little haXe/Neko app called “the helper” that is automatically called every minute and that checks the state of our app.

At the moment, the helper is being automatically launched using launchd (fancy cron job for OS X), but that has very interesting side effects (again, more on another post).

The helper checks if our app is running using something like:

And parsing the result for a relevant match. If the app is not running, it starts it again using:

Since we are using AIR 2 beta, we could implement a more refined communication system using the new Native Process API, but for the time being checking if the app is running “the hard way” is enough.

UPDATE, UPDATE, UPDATE

Find a good mechanism to auto-update your app. Most 24/7 apps are unattended apps and they might well be in a different room / building / city / country. But even if you are just a few steps away, you still want to be able to remotely deploy a new version.

We decided to implement our own update system based on GIT commits instead of relying on AIR’s update framework.

LOG, LOG, LOG

Log as much as you can. You’ll be happy you did when you need to find out why your app crashed. Believe me, in this case more is more, even if you face huge log files. If you are a little bit consistent you can always build automatic parsing tools for your logs or just run a simple grep to find error traces.

BTW, we settled for a log file per day to avoid massive log files.

WARN, WARN, WARN

As I said before, most of these apps run unattended, so you want to be notified as soon as possible when there’s an error. You can:

* Use a private Twitter account that people subscribe to.
* Send an email. You can do that from Flash using for example SMTP Mailer and a local SMTP server.

Whatever you do, don’t rely on one method only, specially Twitter, in case is down when the app needs it.

REMOTE, REMOTE, REMOTE

You either enable VNC, SSH or both. If you can’t, then be prepared for walking / driving / taking the bus a lot.

–

I’ll leave the details of running your apps using launchd and the peculiar way in which AIR holds “hard” references to files for another posts.

[Warning, haxeIgniter is not a port of CodeIgniter, the PHP framework. Sure, ideas are pretty similar, but it's not a direct port]

As a rule of thumb, I like it. Although docs and code need further improvement, it seems easy enough to get your head around. Let alone it brings a compiler and friendly haXe syntax to the server. If you want to try it yourself, read the docs, starting at the intro and follow links from there.

I’ll list some things that got me and might save you some time.

By default only works in the root of your server

In theory you should be able to make it work in any folder by tweaking Config.hx, but I got it working in the root and didn’t try again.

Needs write permission on www/runtime folder

When I started testing on OSX under XAMPP I wasn’t getting anything on the screen or Apache logs, for some reason. Finally tried in Ubuntu and got to the problem, you need write access folders in www/runtime.

Custom router

The router is the piece of code that decides the “translation” between URL and controllers. There’re 2 by default, Basic and RESTful. Basic translates URLs to classes like this:

site.com/class/method/param1/param2

The RESTful follows the REST approach where:

site.com/controller/id > show(id, ?args)
site.com/controller/new > make(?args)
…

Ok, but what if you need more control than that? Well, for the time being you just have to roll your own. Create a MyRouter class implementing Router, add it to your Config.hx (about line 259 in 0.9.2) and you have full control over mapping URLs to controllers. See DefaultRouter.hx in haxigniter.server.routing for sample (as any other library, haxIgniter is installed in haxelib’s path, find it running haxelib path or haxelib setup).

No obvious way of creating common + content views

haxeIgniter offers 3 different template systems. haxe.Template (default), Templo and good ol’ Smarty. I’m not so sure that more is more in this case, especially since there’s a low common denominator interface to deal with all of them, but anyway.

If you want to create a common + content view (common being html header, title, css and js links and content being each page’s specific markup) you need to render templates inside templates:

No helper for linking assets into views

By default there’s no helper to include assets in your view (js, css, images, etc). Something like:

In theory, inside a view, that code would create a img tag with the right path to the foo image, working out what the application path is inside the server, etc. At the moment there’s nothing like that, but you can set the base path in your html and then use absolute paths. Something like:

–

So, there’re a few gotchas and probably haxeIgniter is not ready for mass consumption yet, but I think it’s a good start. I’m using it for building the next version of my website, so you will be able to look at “real” code soon. I’m using quotes here because the next version of my site is going to be very, very simple, so probably not the most complete haxeIgniter sample, but sample code nonetheless : )

To put it simply, XAPI (Ximple API, the “x” is mandatory on haXe projects, you know?!) is a higher level API for haXe backends. Tu put it even simpler, that means doing more with less lines of code.

So, what can it do?

• Read / write / manage files and folders.
• Get information about your system (OS, where’s the temp or the user folder, etc.).
• Interact with other tools in your system (Git, SVN, MTASC, SWfMill, etc.).
• Search for files and folders.
• And other smaller bits and pieces.

You can do all this already with “plain” haXe, XAPI only simplifies how you do it. Sometimes it also prevents developers for making mistakes. Two quick samples:

Writing content to a text file using XAPI:

Using plain haXe:

[BTW, the opposite is not true, there's neko.io.File.getContent() which I didn't know about and used to use for this example. And also, turns out the PHP package has php.io.File. putContent()]

Checking if a file exists using XAPI:

Using plain haXe:

So, there’s no “isFile()” call in the API, plus using haXe alone you would get an exception because you are passing null (in real world you would never pass null on purpose, but it happens that you pass a variable that is), whereas in XAPI I check for null and, if it is, it just returns false. I think that’s how it should work and I reported it as a bug, but it won’t get fixed :/

Those are the little and not so little additions that XAPI provides to the Std API. To get full details, just install and check out the docs. Simplest option is installing via haxelib (haxelib install xapi), but you can read installation instructions on the wiki.

HippoHX’s API is the mother of XAPI. That’s when I first decided that I was going to expose a slightly different API that **I** thought it was simpler. See those stars around “I”? They are important. You see, this business of building APIs is very, very subjective. I honestly think it’s much like designing. You need to know your target audience, one size doesn’t fit all, and there’s a great deal of taste involved.

XAPI is an API for developers like me, with the same needs I have, etc., etc. I’m fine with that, I have no plan to dominate the world (yet), and I’ve built XAPI to help me on my own projects. I open it to the world so hopefully a) other devs will benefit and b) people will help me fix bugs.

What the future is?

Turns out XAPI is almost feature complete because I want to keep it simple. I want it to be easy to use and I don’t want to target every single project out there, because that’s what the Std API is for. When we were discussing on the list about what XAPI could do,Jonh de Goes came up with an interesting idea about building some kind of “general file system wrapper” API where each “node” could be a file on your system, in the cloud or somewhere else (read it here). Well, that sounds like an awesome project, but out of the scope of XAPI.

On what can only be described as sweet irony, he also was the person who convinced me NOT to do it when I read his series of posts about writing Good APIs (1, 2, 3, 4. Extra Ball, also read his post about Dispersed Development).

Sweet Spot Saturation Rule

“By letting go of the power users, they achieve high usability (this is not always an inevitable tradeoff, but at the very least, simpler applications are easier to make usable than more complex applications”

And that’s exactly what I’m planning to do. By not implementing the general file system wrapper he proposes I’m going to let go power-users like him on behalf of mid-users like myself. I hope it pays off resulting in a very simple to use API. Time will tell.

One thing that I’m thinking about is custom exceptions, though. At the moment if the Neko VM finds a problem it raises an exception which I’m not sure we know the type of. So catching them in XAPI and raising new ones to which we know the type I think would help a lot. Ideas welcome, btw.

Is XAPI for you?

Well, depends on the type of projects you face and the kind of developer you are.

If you build for backends (php, cpp, neko), it might interest you.
If you are rather new to haXe, it might interest you.
If you develop build tools, it might interest you.
If you are wiling to sacrifice some flexibility to gain simplicity, it might interest you.

And to wrap up, thanks to Ian Thomas, he was the first one suggesting such a project more than a year ago. I might need some time, but I do deliver : )

How is this better than the others?

I think it’s better than Bash because haXe is an OO language and it’s fully crossplatform (no bash in Win unless you use Cygwin). I also think it’s better than Ant because you get rid of bloody-fatty Java as a dependency.

How is this done

In a nutshell: you program in haXe, compile to Neko and then pack to a native app using Xcross. Piece of cake!

Let’s say you need to read some config file, compile your AS using MTASC and copy the output file to several places. Let’s assume a simple config file like this:

And that we pass it to our tool like this:

Now the pseudo-code:

And now compiling:

That should be it; we’ve read and parsed a config file passed as a parameter and then called MTASC handling the result. Then compiled to native Win, Mac and Linux apps.

As I said, that’s pseudo code, on a real life app you would definitely need more error handling or might have a more complex config file (maybe xml, try parsing xml in Bash!), etc., but since haXe is a really similar to Flash or JS, it feels very natural to me. Granted, you can do the same in Bash, but to my eyes is much more complicated.

Some more notes:

• From a Neko app you can call any other tool on your system. That includes SVN, Ant, GIT, grep… Whatever is there, you can call it.
• Apps created with Xcross embed the Neko VM so they have zero dependencies (unless you use any of the tools described above, of course).

We are investigating this route instead of Ant for our build scripts. You might think it’s kind of reinventing the Ant wheel, but we have the feeling that this is going to be much faster and flexible to our needs.

We’ll see : )

PS: I’ve used the xa.* package in the code, that’s a little project I’m working on to provide a simpler haXe API for backends. This is a spin-off of HippoHX and it’s not ready yet, but if you are interested you can follow the development in GitHub.

Unless you’ve been living under a HUGE rock you should know by now what GAIA is. Either that or you are not a Flash dev so here it goes anyway: GAIA is a Flash framework that is meant to greatly speed up your development workflow. It automatically gives you scaffolding, SWFAddress, SWFObject, transitions between pages, etc. And as with any other frameworks, it makes bringing new people to the team much more easier because it’s known and documented. The problem for Linux peeps was that it requires the Flash IDE. Well, not any more!

Lee McColl (one of the guys behind the haXe book) has ported it to haXe. This is just version 0.1 and there’re still some wrinkles here and there, so some more testing is required. Read the announce on the mailing list for more info.

This is another great addition to haXe after PHP and soon-to-be-released C++ backends. Whatever your dev background is, I think haXe is well worth looking at, you can start by the brand new haXe introduction.

…performance can be considerably faster than ActionScript 3.0…

Luckily for us, what’s interesting to me is a challenge for the so-called man that never sleeps, Nicolas Cannasse. How come you could create faster SWFs with Alchemy? At the end of the day it’s just a SWF, right? Well, it’s not. Alchemy SWFs use parts of the AVM2 that “regular” SWFs don’t use.

It didn’t take long to Nicolas to come up with the haXe solution: the Virtual Memory API. So from haXe you can use this new API that outputs the same bytecode as Alchemy does, therefore you get super-fast SWFs. Veeeeeery cool. Or very cool if you are an haXe developer.

And this is my point. How weird it is that there’re 2 ways of producing fast SWFs but none of them is officially supported by Adobe? One is in the labs, the other one is haXe. Now put yourself in the shoes of a Papervision or Away3D developer. It sucks. Those projects (and many others) need to squeeze the player till the very last drop of performance. And when you are talking about 30-40% performance boost…. it’s a big deal.

On the bright side, Adobe keeps improving the AVM2 and that’s always good for everybody, haXe developer or not!

To sum up, write your CSS files using haXe. There are quite nice tricks like nested block, variables, etc. I’ll definitely give it a go when needed, but I’d like to know what my CSS friends think about it.

And as usual, hats off to Nicolas. I love the spirit: “I don’t like how this works I think I can make it better” that we all should follow. Also, he shouldn’t create any more tools, he should write a book about productivity to teach us that how to build them ourselves.