Helma Logo
main list history
previous version  overview  next version

Version 8 by hannes on 20. February 2009, 23:00

helma.filestore is a simple, file based storage engine. It uses JSON as object serialization format and offers basic storage, retrieval and querying support for plain JavaScript objects.

A simple demo app for helma.filestore is <a href="https://dev.helma.org/trac/helma/browser/helma-ng/trunk/apps/storage">included in with Helma NG</a>.

To use helma.filestore you need to import the module and create a Store instance, passing it the root directory of the data store:

  // init store instance if doesn't already exist.
  var store = new db.Store("db");

Next you define a JavaScript constructor for your persistent model class. The constructor takes an object containing the properties of the instance as argument.

  function Book(properties) {
    this.properties = properties || {};
    return this;

To make the class persistable, you pass it to the <code>registerType()</code> method of your Store instance along with a description of the class's perstistent properties. This adds static retrieval methods such as <code>get(id)</code> or <code>all()</code> to the constructor and allows the store to use the constructor when retrieving objects.

  store.registerType(Book, {
    title: Text(),
    author: Reference(Author)

Of course you can add methods to your model object any way you like it, either in the constructor or through the constructor's prototype property.

For a full working application using the helma.filestore module have a look at the *storage demo app|http://dev.helma.org/trac/helma/browser/helma-ng/trunk/apps/storage* that comes with Helma NG. You can start the application with the following command.

  $ java -jar run.jar -i apps/storage/main.js

Go to http://localhost:8080/ to view the app in your browser. You also can work with the application interactively, using the shell (that's what the -i switch was for in the command line above).

  helma> include("model");
  helma> var b = new Book({ title: "Die kleine Hexe" });
  helma> b.author = new Author({ name: "Otfried Preußler" });

Voila, your first persistent object. Let's store it and see how the data retrieval objects work:

  helma> b.save()
  helma> b._id
  helma> Book.get("1");
  Book[Otfried Preußler: Die kleine Hexe]
  helma> Book.all()
  Book[Otfried Preußler: Die kleine Hexe]

One very powerful method is the <code>list()</code> method in the model's constructor. It allows you to get a filtered, ordered, and sliced view of the stored objects. For example, the following will give you a list of up to 10 books with the word "klein" in the title, ordered by author name and starting with the first book:

  helma> Book.list({
      >  orderBy: "author",
      >  order: "asc",
      >  filter: function(book) { return /klein/.test(book.title); },
      >  start: 0,
      >  max: 10
      > });
  Book[Otfried Preußler: Die kleine Hexe]

If you're done, use a book's <code>remove()</code> method to delete it from the data store.