On Sunday I finished the README and instructions for working with AMASS, the AJAX MAssive Storage System that makes it possible to permanently store large amounts of data on the client-side of browsers, opening the door to new kinds of AJAX applications. Download the latest alpha release of AMASS, or view the README file.

The README file:

• What is This?
• News
• Versions
• Contributors
• License
• How Do I Use This?
• How Does It Internally Work?
• Articles
• Demos and Examples
• Support
• Download
• Known Issues

What is This?

The AJAX MAssive Storage System (AMASS) uses a hidden flash applet to allow
JavaScript AJAX applications to store an arbitrary amount of sophisticated information
on the client side. This information is permanent and persistent; if a
user closes their browser or navigates away from the web site, the information
is still present and can be retrieved later by the web page. Information stored
by web pages is private and locked to a single domain, so other web sites
can not access this information.

AMASS makes it possible to store an arbitrary amount of sophisticated
data, way pass the 4K limit of cookies or the 64K limit of Internet Explorer's
proprietary client-side storage system. An AMASS-enabled web site can store up to 100K without user permission. After 100K,
users are prompted on whether the web site can store the requested amount of
information. Users can approve or deny the storage request. The AMASS system
informs the client-side application on whether the storage request was allowed
or denied. In my own testing I have been able to store up to ten megabytes
with good performance; I'm sure even more information can be stored, I just
have never tried beyond this amount.

AMASS works on Internet Explorer 6+ and Gecko-based browsers, like
Firefox. Users must have the Flash plugin version 6+ installed to use
AMASS; Flash 6+ is installed in 95% of machines, however.

News

• [MM-DD-YY] - Some news item here.

Versions

The most recent version of AMASS is version 0.02.

• Version 0.02 - Alpha release of AMASS that can serialize both
  JavaScript objects as well as giant strings with good performance.

Contributors

The primary developer on AMASS is Brad Neuberg.

License

AMASS is available under a BSD license.

How Do I Use This?

Working with AMASS is simple. The AMASS framework creates the abstraction of
a permanent hash table that persists even after the user has left the page
or closed their browser.

The first step in working with AMASS is to load the AMASS script:

<!-- Load the Permanent Storage framework -->
<script src="storage.js"></script>

AMASS must wait for its internal machinery to finish loading. In order
to use AMASS, you must wait until it is finished loading by adding
a listener:

storage.onLoad(initialize);

function initialize() {
}

Once AMASS is loaded, you can begin to work with it by using it's hash table
methods, such as put, get, and hasKey:

var keyName = "message";
var keyValue = new Object();
keyValue.message = "hello world";
keyValue.testArray = ["test1", "test2", "test3"];
keyValue.testObject = {someProperty: "someValue"};

if (storage.hasKey(keyName) == false) {
storage.put(keyName, keyValue, statusHandler);
}
else {
var results = storage.get(keyName);
}

The AMASS framework makes it possible for you to serialize entire JavaScript
objects into the storage system, such as the keyValue object we
serialize above. Note that DOM nodes and browser objects, such as the
XMLHttpRequest object, will not be serialized.

Applications can store up to 100K without user permission. After this,
a popup generated by the underlying Flash system is created that prompts the
user for permission. The AMASS framework knows when the popup appears, generating
a DIV and bringing the Flash file to the forefront of the application, centering
it on the screen:

Users can either APPROVE or DENY a storage request. You must create your

application ready to have its storage request denied. The put()
method takes a status handler as its third argument that informs your code on whether the storage
request was successful or not. In the code above, statusHandler
is a callback function that will receive whether the request was successful
or failed:

function statusHandler(status) {
 if (status == Storage.SUCCESS) {
   var results = storage.get(keyName);
   alert("Results from statusHandler="+results);
 }
 else if (status == Storage.PENDING) {
   alert("Results pending approval of storage space from user");
 }
 else if (status == Storage.FAILED) {
   alert("Storage request denied");
 }
};

Status can be one of three values: Storage.SUCCESS,
Storage.PENDING, or Storage.FAILED. If the popup
appears, you will get a callback of Storage.PENDING. Later, if
the user approves the request, you will receive a Storage.SUCCESS;
if the request was denied, you will receive Storage.FAILED. When
the user approves the request, they can also indicate whether they give
permission to future requests to automatically store information without
having to popup the permission dialog again.

When working with giant strings or XML, you should not use the default
put() or get() methods. Instead,
you should use the putString() and getString()
methods. The put and get methods attempt to
unserialize a stringified JavaScript object back into a real one, using
eval(). If you are just storing a dumb string or XML than this
will major impact your performance, especially for large datasets. For
very large datasets you should definently storage your information as XML
strings or just plain strings using the putString and
getString methods.

How Does It Internally Work?

Internally, we use a hidden Flash file and Flash's SharedObject
functionality to permanently store the information. We script the Flash
file using it's ActiveX methods on IE and it's LiveConnect methods on
Firefox. We use Flash's SharedObject's callbacks to detect
when the request storage dialog is on the screen, and pass these back to
the JavaScript application. We also center these values on screen.

Articles

The O'Reilly Network will be publishing
a forthcomming article, titled "Permanent Storage for AJAX Applications."
This article will go into much more detail, with full examples, than this README
can accomodate.

Demos and Examples

The O'Reilly Network article will have full examples. Until then, see the
testing class for the AMASS framework for sample code:

• test.html

Support

My primary means of support is through open source consulting using the
kinds of frameworks I create and give away. For this reason
I generally charge for support. I can answer simple questions, but beyond
that we should structure a consulting arrangement to solve your problems
using the AMASS framework. For details, email at
bkn3@columbia.edu
or call me at 510-938-3263.

Download

Download the latest release of the AMASS framework.

Known Issues

• We currently do not check to make sure Flash or the correct version of
  Flash is already installed.


• This is broken on the Mac, including on Mac Firefox.


• I have not tested on Linux yet.


• When the showSettings() method is called, the dialog does not fully
  disappear when dismissed.


• This is still alpha and needs alot more testing.