Apparently the article got lost in the shuffle, and about a week ago they found it and asked me to review their changes. I just found out that the article was published today.

Although it’s grouped under the “quick starts” category, it has a lot of detail. Also, it’s included in the Flash developer center but Flex developers shouldn’t be put off by that. It’s really about a core ActionScript class that’s available anywhere you’re writing ActionScript. (I’ve always found the ADC’s forced boundaries between Flash, Flex, and AIR to be too constraining for reality.)

I personally think the article provides a good, in-depth introduction to various aspects of working with the Vector class. In particular, it has guidance on areas that some people find problematic, such as the type parameter syntax and the fact that you have to provide your own custom sorting code (and of course the article includes examples to copy). I personally think it’s better than the developer guide documentation on the Vector class. (And I wrote them both so I’m not just showing a bias for my own work =)

A few years ago I was working as a developer for a computer training department at a large midwestern university*. I also wrote and taught training courses for them. As jobs tend to do, the work was often in cycles — sometimes I’d spend a few months doing mostly coding, then perhaps I’d be working on a new workshop so I’d spend most of my time writing for a few months.

At one point I was in the transition phase, moving off of a “coding” cycle and into a “writing” cycle. One day while I was writing (in Adobe Framemaker — the word processor we used) I realized that each time I reached the end of a sentence my first instinct was to type a semicolon rather than a period. Too many lines of code written, I guess!

Anyway, I was reminded of that today when something kind of similar took place. Nowadays of course most of my writing, whether code or documentation, is done on a computer. In fact it’s fairly common that when I reach a stopping place while writing in a web browser (such as editing a wiki page) I instinctively type Ctrl+S to “save” (even though that just opens up a dialog to save the HTML of the page, rather than actually saving my work in the wiki or whatever. Today, however, this instinctual behavior was taken to a new level.

I was in a meeting and I had a thought about something I’ve been brainstorming since yesterday. It’s a new project I’m starting on (a documentation architecture project, not a coding one) so I’ve started by just jotting down thoughts in a notebook as they occur to me. I pulled out my notebook and wrote down my ideas. Then I felt a sort of funny twitching in my left hand — my left pinky and middle finger were instinctively trying to perform some sort of repetitive action, and couldn’t quite figure out whether it was appropriate or not. I realized that since I had just finished writing down a thought, my hand was trying to make the gesture for Ctrl+S in an attempt to “save” my “document”. Because of this my brain was momentarily confused — like it somehow knew this action didn’t quite fit in this context (pen and paper) but couldn’t figure out exactly why that was the case. Since of course, mentally I knew I needed to hurry and save my work so that it wasn’t lost.

Anyway, that’s my funny story for the day. Probably for the rest of my life, at least in terms of publishing at this url. So I hope you enjoyed it =)

* Note

My use of the term “large midwestern university” is also an attempt at humor — its an academic inside joke. I went to graduate school at Indiana University (the same “large midwestern university” where I later worked) and we students often read academic papers published by our professors or their former students. In the spirit of anonymity, when they described the participants in their research studies they never described their study participants as “students at Indiana University” or something like that. Instead they always described them as “students at a large midwestern university” although the authors’ biographies would always indicate their affiliation with Indiana University, so there really wasn’t any anonymity about it at all.

As you may have heard among all the news that’s coming out from MAX right now, Adobe AIR 1.5 has just been released. Most of the features of AIR 1.5 are features that were introduced with Flash Player 10. However, one new feature in AIR 1.5 that helps address the easy-to-read database issue is AIR 1.5’s new support for AES encrypted databases.

I’ve had the interesting and at times complex job of writing the documentation for this new feature. The bulk of the new documentation is in a new section “Using encryption with SQL databases” in the SQL database chapter of the manual “Developing Adobe AIR Applications”.

It’s pretty straightforward to use an encrypted database. You have to create the database as an encrypted db. To create or open it, you call the SQLConnection class’s open() or openAsync() methods, just as you normally do, and there’s a new parameter where you provide a 16-byte ByteArray encryption key for the database. That’s all there is to it.

The SQLConnection class also has a new reencrypt() method, that you use to change the encryption key of an already encrypted database.

If you want to see some code examples, check out the documentation listed above, or see these quick start articles on the Adobe developer center:

• Working with the encrypted local SQLite database (Flex)
• Working with the encrypted local SQLite database (Flash)
• Working with the encrypted local SQLite database (HTML/JavaScript)

There are a couple of parts of the new documentation that I think are particularly interesting (although I’m obviously biased since I wrote it all):

• Considerations for using encryption with a database talks about some of the various reasons you may want to use an encrypted database, and some of the differences in how you might architect your application to account for the desired level of security and privacy.

• Example: Generating and using an encryption key goes into great depth into one technique for creating an encryption key for your database. You have to provide a ByteArray encryption key to encrypt your database. How you come up with that encryption key can have a big impact on the actual security of your app data.

  This was definitely the most involved example I’ve written for the documentation. the techniques it uses were specified to me by security engineers at Adobe. The documentation goes into lots of detail describing how these techniques are used and why. Both the code and the text went through a series of reviews by engineers and security experts.

  I ended up writing the example as a simple UI, plus a class that anyone can just pull into their own app (rather than having to pull apart the example and turn it into something you can use. I’m also excited to share that Mike Chambers and Christian Cantrell decided that this “encryption key generator” class is useful enough that it’s now included in the open-source ActionScript 3.0 core library (as3corelib) project.

Now that AIR 1.5 is out the door, I’ve updated my AIR database admin tool to support encrypted databases (when you try to open an encrypted database it prompts you for an encryption key, which you enter as a Base-64 string). I already mentioned that I wrote the encryption key generator class that’s now in as3corelib. I’ve also got at least one more new encrypted database-related open-source project that I’m about to release…but I’ll wait until the MAX “firehose” dies down a bit before I write more about that one. =)

Like so many people, my work goes in cycles (from “busy” to “crazy” to “desperate crunch”). If you’re someone who follows this site (if in fact there is anybody who does), you may have figured out that any time I go for a long time without posting, it means I’m near the end of a project (and consequently, that new documentation is coming soon).

Well, that time has arrived. With the public announcement of Adobe Creative Suite 4, we’re doing something different in terms of the schedule for releasing documentation. This time the documentation has been released ahead of time, before the product actually ships. (Primarily for the sake of search engine indexing — but hey, let’s not complain.)

Of course, a draft version of the Flash Player 10 language reference has been around for a while now, but if you haven’t had a chance to take a look (or if you want to know how things turned out in their final form), you can now view the final Flash CS4 (including ActionScript for Flash Player 10) documentation. Also, this includes several significant additions to the content in Programming ActionScript 3.0, so if you prefer to learn by reading about a topic rather than by piecing things together from the reference, then you’ll find this content useful.

Here are a few top-level links to get you started:

• Programming ActionScript 3.0
• ActionScript 3.0 Language and Components reference
• Using Flash (including what’s new in Flash CS4)

Just for fun, here is the new content that I wrote:

• Vector class (strongly-typed arrays):

  • Vector class in Programming ActionScript 3.0 (new content is interspersed with the previous content on the Array class)
  • Vector class reference

• Pixel Bender (“custom filters” — although it’s a lot more than filters)

  • Working with Pixel Bender shaders (in Programming ActionScript 3.0) - plus other sections that are linked to from there, about using a shader as a drawing fill, a filter, a blend mode, etc.
  • Shader class reference
  • ShaderJob class reference
  • ShaderParameter and ShaderInput class references
  • ShaderFilter class
  • plus new content in the DisplayObject class, the BlendMode class, the Graphics class, etc.

And here are some of the other new topics that I think are the most interesting:

• Working in three dimensions (3D) in Programming ActionScript 3.0
• Inverse Kinematics (IK) in Programming ActionScript 3.0
• Using the new drawing api (aka “drawing api 2”) in Programming ActionScript 3.0

So, what’s next for me? (Thanks for asking!) Since finishing the final versions of the Flash CS4 documentation, I’ve been working on some “quick start” articles around the new features. Those articles will appear in the Flash developer center soon — probably when Flash CS4 actually ships. (I’ve done one on the Vector class and one on the new FileReference functionality for accessing local files without a server round trip. Other colleagues have done cool things with dynamically generating audio and Pixel Bender — so I think it’ll definitely be worth a look.) Along with that, I’m working on new features for the next version of Adobe AIR. I also have a few side projects that I’ve been trying to make progress on as I can sneak in a minute here and there.

On a personal note, the screenshot that Lee posted for the Vector class documentation was written by me. So that was fun to see =)

If you’ve been following my posts on AIR and the SQL database functionality, you may have noticed a trend: every time there’s a new beta, I tend to go silent for a few weeks beforehand as I try to get things finished up with the documentation. Well, here we went again — another period of silence, another AIR beta.

The marketing team kept things pretty low-key with announcing this new beta, especially compared to previous rounds. I’m not sure of all the reasons for that, but there are a few that are important and helpful for you to know if you’re developing AIR applications:

• AIR is now API-frozen — as of this beta, there shouldn’t be any changes to the AIR apis. In fact, the goal was to have as few API changes as possible between AIR beta 2 and AIR beta 3, as things get closer to being locked down. Naturally, if we find a big security issue that requires us to change an API, we’re going to consider it — but aside from that, things are now the way they will be for AIR 1.0 (phew — it’s been tiring for me to update apps every beta, and I’m sure it has been for you, too).
• Along with the new AIR beta, Adobe also released a beta of a new product code-named “BlazeDS”. This very cool offering is a free, open-source, slimmed down LiveCycle Data Services — basically it includes the RPC Components (“Flash Remoting”) functionality as well as the Messaging functionality. In addition, we’re releasing an official specification for the AMF format. While the format was (for the most part) reverse-engineered long ago, I think it’s great to have something official for all the other open-source offerings like AMFPHP, Fluorine, etc. to work from.
• Along with beta 3, Adobe created the “Adobe AIR Marketplace” where developers can post apps for people to download and try out — basically an extension of the
• Flex 3 beta 3 is officially the last Flex 3 beta before Flex 3/AIR 1.0 (second paragraph, also in the FAQ PDF). ‘nuff said =)

Of course, following the trend of my going silent before each beta, you can expect that to be magnified as we continue leading up to AIR 1.0. There have been a few things each beta that I wanted to do but had to put off until later — but of course, this time there isn’t any “until later” — so it’s now or never!

Talking specifically about the local SQL database functionality, there were only a few changes this beta, but they’re pretty significant and maybe even a bit sneaky so you’ll want to pay attention to them:

• Specifying synchronous and asynchronous execution: Synchronous database execution was added to SQLConnection in beta 2. At that point, to specify that a SQLConnection’s operations were synchronous rather than asynchronous, you had to specify a true parameter in the SQLConnection() constructor. Now, however, the SQLConnection() constructor doesn’t accept any parameters. Instead, you specify the execution mode when you open the connection to the main database. To specify that you want to use synchronous execution, you call the SQLConnection.open() method; to specify async execution, you call the new SQLConnection.openAsync() method.

  The most important thing to note surrounding this change is this: if you’re migrating an app from beta 2 to beta 3, you may be changing the behavior of your app without even realizing it! If you want a connection to be synchronous, you’ll know you have to change things because the code won’t compile (SQLConnection() no longer accepts a parameter). However, if you want you connection to be asynchronous, then if you don’t change anything the code will still work but it will actually use synchronous rather than asynchronous execution. If you have a long-running query and it’s freezing the UI now, that’s probably the reason — the exact code you used previously to specify asynchronous execution (no SQLConnection() parameter, and open() to connect the db) now is the way to specify synchronous execution. If your code doesn’t cause any errors, you might not even notice immediately because the SQLConnection and SQLStatement events are still triggered even in synchronous execution — so your “success” event listeners will still get called (but error listeners won’t — the operations will throw exceptions instead).

• There were a couple of changes to the SQLError class and related classes: The SQLError.code property was removed (because it already inherited errorID from Error) and the details property was added, providing a more detailed error message in certain cases. Along with this, the SQLErrorCode class was removed entirely (tragically — I spent a fair amount of time hammering out those error descriptions with Jason, the engineer for the feature).

I think that’s it, but please let me know if I’ve forgotten another change!

In the mean time, In addition to the SQL database stuff I’ve been doing more with another part of AIR that I’ve previously been working on as I’ve had time — the AIR-related Flex components. This release includes a new one, the FlexNativeMenu component, which is pretty slick. Watch for more on this in the (hopefully near) future!

• Deep-linking to frames in Flash websites (Sept. 10, 2007) - for this article I took just one of the techniques I described in the original article and added more background information and better explanations. (I’m sometimes amazed by how much detail I leave out when I’m writing posts on this site!)
• Detecting when data is edited in the DataGrid component (Nov. 12, 2007) - this article was revised much less from the original than the other one. Basically I took the text and found places where I thought it needed more/better/clearer explanation, and added a sentence or revised the text. I definitely think the new version is better, but there isn’t any new information to be had if you read the original.

Note: This post won’t make as much sense unless you read Tim’s post first. So I’ll pause for a moment while you go read it — don’t worry, it’s not nearly as long as this one =)

As suggested by John Dowdell in the comments on Tim’s post, the biggest reason why SQLite isn’t mentioned by name in the documentation is a somewhat complex matter involving the timing of when the feature was developed, deadlines for when the documentation had to be done in order to include it in the beta release, and the timing of when Google Gears was announced.

Background: Development schedules, marketing announcements, and the realities of human limits

If you don’t mind, I’ll start off with a bit of background/context on the timing of the local SQL database feature being developed and the agreement with Google.

Note: Admittedly I’m making educated guesses on the timing described here, based on things I observed but without actually being involved in the conversations between Adobe and Google.

Before any sort of agreement about synchronized APIs and common code had been reached, perhaps before it had even started, Adobe, and presumably Google, had both separately developed most of their respective implementations of database functionality based on SQLite. Naturally, at the point that they agreed to make their APIs agree with each other, both companies could have chosen to postpone releasing their implementations until the final, synchronized API was finished. Not surprisingly, both companies felt it was more important to get something out to developers sooner (even if it wasn’t the “synchronized API”) rather than later when things were final. From a public visibility perspective, Google made their announcement first, so they have the benefit of being perceived as the “original” and I expect many developers expected the AIR API to be identical when it was released (about a week and a half later, it’s important to note).

I wasn’t involved in any of the planning or discussion surrounding the AIR-Google Gears “synchronized API” decision, and in fact I didn’t know anything about it until I read the public announcements. (If you can, imagine my reaction when I read that the APIs were going to be aligned — since I had just finished the API reference documentation the previous week! =) The fact that I wasn’t involved in the conversations doesn’t bother me and makes sense to me — there wasn’t really any compelling reason why I should have been involved in those conversations — but obviously that had a direct impact on my ability to anticipate the consequences of that announcement while I was writing the documentation. By the time the announcement was made, it was too late to go back and change the documentation, and definitely too late for us to actually change the API.

With that background, let me address some of the specific points that Tim raises. He asks the question, “why doesn’t Adobe’s AIR dev guide mention SQLite?”, and gives three points about why he isn’t pleased that SQLite isn’t mentioned:

1. “It stinks”

Of course, what I’ve said up to this point suggests that, were it not for the Google Gears announcements, Adobe might not have ever announced that we are using SQLite. I can’t speak for alternative futures, of course, but I think it’s possible that Adobe would never have mentioned SQLite in the documentation. Does that “stink” as Tim suggests? Is it discourteous? I can definitely understand the sentiment behind those expressions. I’m a firm believer in “credit where it’s due.” When I wrote the documentation, I certainly didn’t mean it as a discourtesy or to minimize my opinion of the value of SQLite that SQLite was not mentioned. I think SQLite is a great tool, and I’m very glad it exists, and that the authors have been so generous with the license.

On the other had, as Tim notes, Adobe has no legal obligation to acknowledge that they included source code from SQLite. Nor does Adobe have any obligation to acknowledge that a significant part of the documentation on the SQL dialect was adapted from the SQLite documentation, because the authors were even kind enough to secure public domain releases for the documentation — although I will readily admit that I did in fact adapt portions of the SQLite documentation — which was very helpful because it saved me a lot of duplicate effort!

So, were we intentionally trying to hide the fact that it was SQLite? No, although we chose not to advertise the fact either, for a few reasons:

• Our intention was to provide sufficient documentation so that a developer wouldn’t have any need to look at the SQLite documentation. (In fact, due to the short time frame for getting things done, one idea that was considered and rejected was just to point developers to the SQLite documentation for the first beta release.) With that decision made, we realized that there wasn’t any absolute need to make reference to SQLite.
• In many respects, the choice of SQLite was originally considered to be an “implementation detail” — something that developers didn’t really need to know or care about. Obviously in the wake of the Google Gears announcements, there is now more reason why it does matter (to some developers) that Adobe chose to use SQLite.

• In fact, when you get down to it, the choice of SQLite could still be considered an “implementation detail.” After all, consider what happens in the future when AIR version 5 or 10 is released. What if SQLite is no longer the best choice for an embedded database? Should AIR developers be limited by the fact that AIR is absolutely tied to SQLite? As long as the API continues to work, and the older file-format databases are supported, and older applications continue to run, how much does it matter whether the embedded database is SQLite or something else?

  Obviously that’s not a highly likely scenario. From a practical standpoint, even if another database engine were used, it would be pretty involved to ensure backwards compatibility, both with the API and especially with the supported SQL dialect.

In summary, when the time came to decide whether to explicitly mention SQLite in the documentation, it came down to this. As we all know, it’s common practice in the software industry, including at Adobe, that when a certain aspect of a feature is considered an “implementation detail” and “not important to developers,” that aspect of the feature isn’t described in the documentation. Sometimes developers find out anyway, either through their own experimentation, or through experience, or whatever. Even if Adobe didn’t announce that the AIR local database engine was based on SQLite, it’s highly likely that it would have come out sooner rather than later. That’s fine — developers can choose to use the knowledge they acquire, and Adobe can choose to change things that aren’t documented.

As I’ve said, at the time the documentation was being written and finalized, the word I was going on was that the fact that the engine uses SQLite is an implementation detail. I gave some thought to whether we should explicitly mention that the database uses SQLite — certainly there were advantages and disadvantages either way. The issue was discussed by me, members of management, and the lead engineer for the feature. In the end, however, for the reasons listed above, and without any knowledge (at least on my part) of the very-soon-to-be-forthcoming Google Gears alignment announcement, we decided that the priorities fell on the side of not stating that the database uses SQLite.

Having said all that, as a result of the announcements relating to Adobe AIR and Google Gears, it is public knowledge that Adobe is using SQLite. Although it may not make sense to anyone but me, that announcement “changes the balance” of priorities in my mind, so in fact at this point I agree with Tim that the benefits of mentioning in the documentation that the database uses SQLite (giving credit where it’s due, and guiding developers to other SQLite tools that might help them) outweigh the potential downsides of stating it in the documentation (the unlikely but can’t-rule-it-out-completely possible future case in which we no longer use SQLite for the underlying database engine, and the possibility of distracting/confusing developers who read the SQLite documentation and find something that’s not supported in AIR and wonder why).

Even as I write this, I acknowledge that my stated set of reasons, and this description of trying to find the best balance between the tradeoffs of “officially” disclosing information versus “officially” keeping information “undocumented” sounds very fuzzy. And I agree that the value of giving credit to the authors of SQLite is a compelling reason for stating in the documentation that AIR uses SQLite. I’m afraid I can’t completely communicate how fast and furiously we were working to get this feature (and the associated documentation) done for the beta, and consequently how we tried to make the best choices we could in a limited time frame. And again, without the smallest clue of the then-forthcoming Google Gears announcement.

Fortunately, as Tim points out, “this is all beta, of course, so it can change.” So, Tim, allow me to tell you that your feedback has helped us to realize that the value of giving credit to the authors of SQLite outweighs any potential drawbacks, and I will shortly be adding explicit mention of the fact that the runtime uses SQLite for its local SQL database functionality. A week ago I asked for feedback on the SQL documentation, and while this wasn’t exactly what I had in mind, it is nonetheless appreciated and hopefully it’s clear that it has been taken into consideration.

2. “It’s unhelpful”

Tim makes the suggestion that it would be helpful to “set out exactly how AIR’s SQLite differs from the standard build.” I think that sounds like a useful suggestion; I’ve made a note to research the topic and see how difficult it would be to compile that information, and how we could usefully incorporate it into the documentation. I admit that the thought didn’t even occur to me (which doesn’t surprise me — I have some good ideas sometimes, but I certainly don’t ever have all the good ideas =).

Although I acknowledge that it sounds like an idea with merit, the devil’s advocate in me impels me to admit that specifying how AIR’s SQLite implementation is different from other SQLite implementations isn’t as much of a priority as some of the other tasks that I’ve got in the lineup. It turns out that there were several things that I wanted to write, and we just didn’t have time to get them all in for the beta release. Since the SQLite library is designed for use as an embedded database, and the target audience (developer-wise) for AIR is developers with web development experience, chances are the majority of the target audience for AIR hasn’t ever programmed for SQLite. That means that documentation comparing AIR’s implementation to other implementations will probably only be useful for a minority of AIR developers — which unfortunately is something that we have to take into account when we’re scheduling the “features” that are chosen to be included in the documentation.

Nevertheless, I do think that it’s a good suggestion, and in some ways I think that it will be useful to more advanced developers whether they’ve used SQLite or not, so I’ll see what I can do.

3. Skepticism that the AIR and Google Gears APIs will align

Hopefully my earlier background information has made it clear that the reason the APIs don’t align right now is really a matter of scheduling, engineering effort, design effort, and a desire on the part of both companies to get their technologies into the hands of developers, and not any sort of conspiracy. I will say that I know for certain that the effort to align the APIs is still going on.

“A big hole in the AIR sandbox”

Tim makes a side note at this point, that the difference between the AIR approach to SQLite and the Google Gears approach has some security implications. This is an important point, so I’ve written a separate post in which I’ve discussed why the two systems use different models, and how to address some of the potential security issues.

Summary: Tim’s wish list

Going back to Tim, he concludes with a “wish list” of three things he’d like to see happen in the AIR documentation and implementation:

• Proper credit for SQLite in the docs.
• Use the Gears code - full text search could be very useful - and deliver on the promise of aligning the API.
• Failing that, set out exactly how AIR’s SQLite differs from the standard build.

I’ll consider these one at a time:

Proper credit for SQLite in the docs

As Tim and I have both mentioned, SQLite is in the public domain, so in fact from a legal definition Adobe is already giving “proper credit” (that is, no credit required) for SQLite. I’m certain that’s not what Tim had in mind, and I’ve also mentioned that I believe it’s worthwhile to give credit to the authors of SQLite. As I’ve also said, I’m planning to add in at least a couple of prominent places a statement that AIR uses SQLite for its database functionality. If that’s not what you had in mind, Tim, please let me know.

Use the Gears code - full text search could be very useful - and deliver on the promise of aligning the API.

I’m 100% certain Adobe is not going to “use the [Google] Gears code,” at least not wholesale — the two products have already been developed in isolation much too much for that to work (in my opinion — but of course I’m not the engineer). Nevertheless, I agree that full text search could be very useful — I would love to see it make it in to AIR as well — and as I’ve said here and also last week, Adobe and Google are continuing to work on aligning their database APIs.

Failing that, set out exactly how AIR’s SQLite differs from the standard build.

This statement is actually a bit misleading, I think, since I’m certain Google Gears doesn’t use a 100% “standard”, out of the box SQLite build. (For that matter, I’m not sure what a “standard” SQLite build would be, since the whole point of SQLite is to be an embedded database, built into another product, and not to stand on its own.)

All that notwithstanding, as I’ve mentioned I have now assigned myself the task of researching the changes that we’ve made from what someone who’s used SQLite in another product might expect, and (time permitting) to add a section to the documentation describing those differences.

Conclusion

I realize this whole post is long, and meanders quite a bit, and probably doesn’t show the degree of concrete explanation (or completely serious consideration) that might be desirable. I believe that we made the decisions we made for good reasons, using the information we had available at the time. I’m also glad that we’ve only released a beta and not the final version yet, and I’m glad that Tim’s post caused me and others in Adobe to sit up and take notice, and reconsider some of our decisions in light of the new information that’s become available since the time when we previously made them.

And once again, if anyone has thoughts or suggestions about the AIR local SQL database documentation, please don’t hesitate to share them. I’ll try not to post an essay in response to each one =)

Okay, that sounds really boring. But I don’t mean it to. I’m actually incredibly excited by this, because it makes it a lot easier for people like me, with web app experience but not desktop app experience, to create data-driven apps and store persistent data using techniques that I’m familiar with.

And, on a personal note, it means that I finally get to talk about what I’ve been working on for the last couple of months. If you actually follow my web site, you’ve probably picked up on the fact that I was heavily involved in the ActionScript-related documentation for the Flash CS3 release. Well, naturally, now that Flash CS3 is out the door, I’ve been moved onto another project — onto Apollo/AIR, specifically.

More specifically, since I’ve been programming SQL databases for many years, as part of my web app development work, I got pegged (well, I actually volunteered) to do the documentation and samples for the local SQL databases feature.

When I first read the spec for the feature, I was completely floored. I was expecting some minimal support for a few things, but what we’ve got is much more than I could come up with use cases for. Want a good idea of the breadth of the functionality that’s available? Spend some time reading “SQL support in local databases” (it’s an appendix of the AIR language reference). Views? Indexes? Triggers? They’re in there.

In case you don’t have a free few hours, I’ll just point out my favorite parts of the feature. These will probably be most meaningful if you’ve already faced the joy and pain of working with web-database apps, especially with an OOP language:

• SQLStatement.itemClass: This was my immediate favorite. You specify a class, and SELECT statement result rows are automatically converted into instances of that class (saving lots of boilerplate code to loop through results and turn rows into instances of some other class). If I could have done this in ASP.NET, I’d probably have saved about 25% of the total code I wrote.
• SQLStatement.prepare() and SQLStatement.parameters: Now that I’ve spent some time building apps and working with the code, I’ve gotten a lot of respect for this method. Basically, this is the way to create the equivalent of pre-compiled stored procedures for your AIR app.
• SQLResult.lastInsertRowID: I had to lobby long and hard for this one, which, since I’m a remote employee, meant lots of email exchanges. Finally I managed to clearly articulate my reason, and sure enough, persistence paid off. If you’ve created a database app, chances are you’ve run into the case where you INSERT a row, and you need to get back the auto-generated primary key so that you can insert a related row. The wrong way to do it is SELECT MAX(id_column) FROM table. The right way, in AIR, is to use lastInsertRowID.

I’m excited that I can talk about this now. I’ve got some samples, practices, and information that I’m looking forward to sharing. I’ll start with an answer to a question that I’ve seen asked around (well, mostly I’ve just seen misinformation, not people asking whether it’s right) about the relationship between the AIR local SQL database API and the Google Gears SQL database API:

• Does Apollo “include” part of Google Gears? - No. There is no shared code between AIR and Google Gears (with the possible exception noted in the next answer).
• What do AIR and Google Gears have in common, then? - Both AIR and Google Gears let you create applications that access databases located on a users local machine. Both AIR and Google Gears chose to use SQLite, a free, public domain embedded SQL database engine, to provide that functionality. So whatever code AIR uses that hasn’t been modified from SQLite, is the same as the code that Google Gears uses that hasn’t been modified in its implementation of SQLite.
• What’s this about AIR including the same database API as Google Gears? - To be honest, although I’ve been involved in the AIR database API for a while, the first I heard of Google Gears’ database API was when the public announcements were made. Thinking back, I see now that discussions were going on for a while, and I even unknowingly provided some support to the management team and others who were involved in that discussion. Right now, although the underlying database engines are based on the same engine, since SQLite is written in C, any implementation that doesn’t use C/C++ needs to write its own API. The two implementations (Adobe’s and Google’s) weren’t developed together, and at this point (from what I’ve seen) the two APIs are pretty different. Case in point: synchronous versus asynchronous database operations. In Google Gears, data access operations are synchronous — calls to the database are blocking, meaning the runtime freezes at the line of code that called the database until the result is returned. In AIR, on the other hand, all data operations are asynchronous — you call SQLStatement.execute() to run a query, and when the result comes back an event listener function is called (at which point the result data can be accessed). That alone means a big difference in how you write code to work with the two systems.
• So wait a minute, what about the whole “Adobe and Google are working together on the database API” thing? - Adobe and Google are having “discussions,” and (from what I’ve heard) the plan is to hopefully make the APIs the same or similar enough that a developer who writes data access code for Google Gears will have an easy time writing data access code for AIR (and vice versa). In addition, since the SQL part of both runtimes really is dependent on SQLite much more than the particular runtime implementation, and SQL code probably is interchangeable between the two runtimes, assuming the same database schema etc.

So from me, and the other engineers and stakeholders inside Adobe, please try out the local SQL database functionality of Apollo, and please let us know what we can do to make it better. In particular, let me know what is missing or what you’d like to see in terms of documentation and samples — but don’t limit yourself to that. Please share your comments/suggestions!

On a more personal note…

I’m really excited about this. I really just can’t say in words how excited I am. When I decided to accept an offer to work full-time for Adobe, one of the first “regrets” that crossed my mind was when I considered that it was highly likely that I wouldn’t be doing any more database programming (since my work involves dealing with ActionScript, and up to now there hasn’t really been any direct database access from ActionScript). So I was excited to say the least when I heard about this feature and it was decided that I’d get to work on it.

Suffice it to say, this has been a pretty busy time. This feature was actually slated to appear in a later release, but at the near-last minute the decision was made to get it done in time for the public beta. That meant a lot of writing and application-building in a hurry! Then two weeks and a private beta release later, a group of people including me, engineers and QEs, and other interested folks, went through a few rounds of discussions on what was missing and what we could do to make the API better. The result, which of course still isn’t finished, is what you can download today.

And, although she isn’t a developer and doesn’t use Apollo/AIR at all, it’s an understatement to say that my wife is glad to see this beta out the door, if only because it means I don’t have to work evenings any more (it’s been a very busy month+ =).

Book summary

This book obviously covers ActionScript 3.0, the (as of this writing) most current version of ActionScript. ActionScript 3.0 is used in Adobe Flex, including Adobe’s Flex Builder tool; it is also the language used in the not-yet-but-soon-to-be-released Adobe Flash CS3 (a.k.a. “Blaze” or version 9). However, since the book was written primarily while Flex was in beta, and Flash was not even released as a public alpha, all the recipes that involve the IDE refer specifically to Flex Builder. The book is written and organized in the O’Reilly “cookbook” format, where each chapter includes several “recipes” written as a problem, a solution to the problem, and a discussion/explanation of the solution. I think of books like this as “task-based reference” books — they’re meant to be used like a reference, that you can look up something you want when you need it — but they show how to accomplish a particular task rather than showing how to use a particular language element. That way, if you know you want to do something in particular (e.g. “simulate rolling dice in ActionScript”) but don’t know which methods or properties you would use to accomplish the task, you can just look it up in the book and it will tell you.

What I liked best

There are several aspects of this book that offer a lot of value. The ones which stood out most to me are:

Coverage of specific use cases and more advanced functionality

Some parts of ActionScript 3.0 have very obvious uses—the DropShadowFilter class, for example, has a pretty obvious use. However, there are several aspects of the language (such as the Bitmap class, the ByteArray class, the DisplacementMap filter, the ConvolutionFilter, etc.) that provide very “open-ended” functionality. There are lots of different things you can do with them, but you have to know what they are and understand some particular programming topic (like graphics manipulation or working with byte data) in order to make use of them. This book describes how to perform some of the tasks that can be performed using these “open-ended” classes. This, in my opinion, is the perfect use of the cookbook format.

In the topics where it shines, this book really shines. I was very impressed with the sophistication of many of the topics that are covered (for example, topic 4.10 “Cards”).

Supplemental code library

The book has a significant library of supplemental code (available as a free download). Several of the recipes use the code in this library to accomplish their tasks. For example, the solution to the recipe “Simulating Dice” is to “use the NumberUtilities.random() method [from the supplemental code library] to generate random numbers in the desired range.” In truth I can see plusses and minuses to this approach. It definitely saves time for the reader — if you’re on a deadline and trying to build that Dungeons & Dragons simulator then having the code already written is a big benefit. It also saves pages in the book, and avoids the need for in-depth explanations (and nearly-redundant explanations, such as those for “Simulating a coin toss” and “Simulating dice”) since all the book needs is a few lines demonstrating how to call the method in the supplemental code. However, if you’re the reader who wants to learn more, or to understand the principles behind the solution as well as the code needed to carry out those principles, you’re left feeling pretty empty. I think one possible compromise (which isn’t done) might be to have a more in-depth explanation for such sections, perhaps showing a few relevent lines of code extracted from the code library, demonstrating how the code library works and how you might adapt it or build your own similar solution.

Breadth of topic coverage

The ActionScript 3.0 documentation that comes with Flex 2 includes two main parts: the reference documentation, and a book called “Programming ActionScript 3.0.” However, due to various factors there are several topics that aren’t covered in “Programming ActionScript 3.0” in the Flex 2 release. These include topics such as working with TextField objects, filters, and bitmap manipulation, among others. The “ActionScript 3.0 Cookbook” can help to fill in these gaps because it does provide coverage of some of those “missing” topics. Admittedly, one of the reasons those topics aren’t covered in the Flex 2 documentation is because they are largely irrelevent for a Flex-only application—for example, in Flex you use the TextArea component or TextInput component to display text, rather than just a TextField component. In any case, they do get some coverage in the “ActionScript 3.0 Cookbook.” As a side note, several new chapters are being added to “Programming ActionScript 3.0,” to be released with the next version of Flash, covering many of these parts of ActionScript that aren’t commonly used in Flex, such as text fields, movie clips, more on display programming, video, sound, filters, and so on.

Room for improvement

As you may have gathered from the previous section, one way I judge a computer book is how well it supplements the manufacturer-provided documentation rather than just rehashing the same material (see disclaimer). I also think it’s important for a book to be consistent to its purpose. If it’s supposed to be a reference, it should just be a reference. If it’s supposed to be an instructional book written as a series of lessons, it should stick to that format. With a topic like ActionScript there’s no way a single book can be all these things, so I think it’s important for the book to stick to what it does best, and let other books fill in other roles.

As the preceding paragraph implies, I have some disagreements with this book in terms of its overlap with the ActionScript 3.0 documentation and its consistency with its stated goal of being a “cookbook.”

Too much redundancy with the official documentation

The question I kept asking myself as I was reading through this book is “what is a cookbook, really?” In my mind, a “cookbook” is a book whose topics are more “edgy” or involved than what you might find in the core documentation. It should cover how to accomplish specific tasks that aren’t easily figured out and aren’t found elsewhere (again, especially not in the main documentation). It should also include “hacks” or workarounds to accomplishing things that aren’t readily available using the built-in functionality of the language. After all, I can learn (for example) the syntax for writing a class or the syntax for adding a display object to the screen by reading the built-in documentation, so why would I need to buy a cookbook to tell me how? On the other hand, the built-in documentation doesn’t (and likely will never) tell me how to do more specific implementation tasks, like “simulating rolling dice” or “creating a graphical texture,” but they’re common enough programming problems that those are topics I’d expect to find in a cookbook.

Admittedly, when I first started working with ActionScript 3.0, one of the first thoughts that came to me was “I wonder what they’re going to put in the ActionScript Cookbook.” ActionScript 3.0 by itself is a big improvement over the previous version, and many of the things that used to require workarounds are really straightforward now — so I wondered what they’d do to replace all of those topics in the book. Unfortunately it looks like they didn’t do anything to replace them.

As I mentioned in the “good” section, there are lots of topics covered in this book that fit squarely in what I consider to be an appropriate cookbook topic. But there are also plenty of topics that I think should have been left in the built-in documentation rather than needing to repeat them in the ActionScript 3.0 Cookbook. Some key examples are topics related to basic syntax. For example, “Creating a Custom Class” and its related topics “Creating Properties that Behave as Methods,” “Creating Static Methods,” “Creating Subclasses,” etc. All of these topics are covered in the built-in documentation, both in a basic form and in greater depth than this book can afford. In addition, these aren’t topics that a person is going to need to look up frequently. Chances are, a person who’s new to ActionScript or who’s been using it for a while and wants to “move up” to using custom classes will need that information. However, once a person has created a handfull of custom classes, they’re not going to need to look up the syntax in the book any more—they’ll already know it or else they’ll just look at a class they created, etc. So there’s little benefit to that content being provided in this book.

Too much discussion on some topics

This is related to the previous criticism. For example, I said that I thought it was redundant for the ActionScript 3.0 Cookbook to have a recipe for “Creating a Custom Class” since that topic is covered in detail in the in-product documentation. However, suppose the publisher wants to fill up the topic list. Or suppose a person who’s “moving up” to creating custom classes has read the chapter on creating a custom class in Programming ActionScript 3.0, and has a decent understanding of the concepts, but just can’t remember the syntax. I admit that there could be some value in having a quick reference place to turn to to find the syntax for creating a custom class. However, at that point the person doesn’t want to read through four pages of explanation about creating a custom class — they just want to see the recipe solution and copy it into their own code. Unfortunately, this book could do that, but it doesn’t. Rather than just give a nice model of a custom class, it spends four pages talking about it. The section on display programming is even more bulky — while they might justifiably have had several one-page-or-less-each recipes on things like “adding a display object to the display list,” “removing an object from the display list,” “reordering objects on the display list,” etc., the book spends 14 pages talking about what the display list is and how it works. That’s nice, but it’s not the point of this book in my opinion. The built-in documentation has even more thorough, detailed explanations about what the display list is, what types of objects can be used, etc. If the cookbook wants to do its readers a service, it should trim that fat, which would make it easier to find the specific method name or syntax — a quick resource to turn to for those “I know I’ve seen this before but I can’t quite remember how to do it” sorts of questions.

Conclusion

In summary, I have mixed feelings about this book. When it’s good, it really shines—the sections that go into more depth or into a more advanced topic than Adobe’s ActionScript 3.0 documentation are really valuable. However, a significant part of the book is redundant with the documentation, doesn’t cover it in as much detail as the built-in documentation, but covers it in so much detail that the benefits of the “cookbook” format are lost.

Book details

• Title: ActionScript 3.0 Cookbook (On Amazon.com) (Publisher’s page)
• Authors: Joey Lott, Darron Schall, and Keith Peters
• Publisher: O’Reilly
• Copyright year: 2007
• ISBN 10: 0-596-52695-4
• ISBN 13: 978-0-596-52695-5

Disclaimers

1. As a contract employee, I helped write the Flex 2 ActionScript documentation, including one chapter and parts of other chapters in “Programming ActionScript 3.0” as well as a handful of samples for the ActionScript language reference. I now work as a full-time employee for Adobe, and one of my current roles is as lead writer of “Programming ActionScript 3.0” for the Flash version 9 release—so I obviously I am not unbiased about the Adobe-provided ActionScript documentation.
2. I received this book at a heavily discounted price in exchange for writing this review. While it’s impossible to remove myself from that detail completely, I have tried my best to make this an unbiased review. Want to know how to get discounted books in exchange for making reviews? Contact your local Adobe Users’ Group.

The book is “Macromedia Flash 8 Advanced: Visual QuickPro Guide” (Peachpit Press), by Russell Chun and me.

The chapter is chapter 2, “Working with Video.” It covers converting video to FLV format (in depth), adding Flash elements/overlays/controls to a video, and rotoscoping with Flash video.

The chapter has been released as part of the sample eBook Library that Adobe has released in conjunction with the beta preview of the Adobe Digital Editions eBook reader. You can download the chapter from the Sample eBook Library page (you may need to install the reader first — I’m not sure since I had already installed it before I went to the library page).

The chapter that was chosen (I’m not sure whether Adobe or Peachpit selected this particular chapter) is Chapter 9, which covers sound control in ActionScript. This chapter is actually mostly the work of co-author Russell Chun. While I updated the code for the exercises to ActionScript 2, and made relevent updates to the text for Flash 8, the main ideas for the examples and much of the text were not written by me. (But don’t get me wrong — it’s still great information — I just want to give credit where it’s due.)

Anyway, that’s my excuse, and I apologize if it’s caused you any pain. Maybe once I’ve finished the book (not done yet, but getting very close) I’ll write a bit more about what it’s been like to work on a book. It’s certainly been a learning process for me, of course with the new Flash content, but also with becoming more efficient at using Word and Fireworks (the automation features of both programs are now well-used on my computer). And of course I’ve learned a lot about what it’s like to work with a publisher, too.

For the curious, the book is Macromedia Flash 8 Advanced for Windows and Macintosh: Visual QuickPro Guide, published by Peachpit Press. Since it is one of their “Visual QuickPro Guides” series, it is very task-focused — definitely more of a task-based reference than a sit-down-and-read book. This is the fourth edition of the book, although it is the first edition that I’ve worked on. Russell Chun is the principal author of the book; my job has been to update the existing material and add new material for Flash 8. That doesn’t sound like a lot (at least it doesn’t to me when I say it that way), but in truth (in my obviously very biased opinion) I think this edition is a significant update to the book. Nearly every chapter has significant new or updated content, practically every task has been updated at least to some extent, plus there is a new chapter on manipulating bitmaps (mostly using the BitmapData class, plus some things on filters).