WFS: The Wonderland File System in v0.5

One of the major seismic shifts that occurred when we re-architected Project Wonderland from our 0.4 to 0.5 versions was the way in which users assemble worlds. (I talk about the new World Assembly tools in the recent blog World Assembly in v0.5). One technology, the Wonderland File System (WFS), that played a prominent role in 0.4 plays a much different role in 0.5. In this blog, I talk about the role WFS once played, and its new role in the most recent version.

The way it was before version 0.5…

I won’t dwell on the past too much, but I wanted to briefly summarize the role WFS played before we re-architected the system for 0.5. In 0.4, WFS was the way to assemble worlds. Sometimes users employed tools, like the World Builder, but more often than not, world assembly entailed hand-editing parameters within XML files. No one could escape this fate (really), so the details of WFS needed to be exposed to all users. In version 0.5, in-world tools let users create, position, and edit the properties of Cells without needing to hand-edit XML files. 

Does it still exist?

The answer is: yes, WFS still exists in 0.5, but plays a much different role now that the primary means of world assembly are the tools built into the client. Unlike version 0.4, version 0.5 also automatically persists the live world state: Wonderland depends upon the mechanisms built into the Darkstar middleware layer for this persistence.

WFS now primarily serves as a mechanism to import "initial" world state or export state as a "snapshot". The structure of a WFS, by and large, has not changed since 0.4: it still consists of a collection of XML files arranged hierarchically on disk that conform to certain naming conventions (e.g. Cell files have a -wlc.xml suffix and extension). The actual format of the XML has become considerably simpler from our switch from Java Bean Persistence to JAXB as the binding mechanism between the XML and their Java object counterparts. Unlike 0.4 though, we won’t be explicitly documenting how the properties of each Cell type map onto an XML schema in WFS, since hand-editing XML files is far less common.

Initial worlds and snapshots

Snapshots Web UIIn 0.5, WFS manifests itself in the Web Administration UI under the Manage Snapshots tab. Users can perform a couple of actions here. First, users can capture the current state of the world as a WFS by taking a snapshot. (This action has the side effect of re-starting the Darkstar server to insure the world exists in a quiescent state before taking the snapshot). The snapshot then appears under the World Snapshots heading. Second, users can reset the state of the world (and restart the Darkstar server as a result) to any entry under the Initial Worlds or World Snapshots headings. All of these entries are WFSs sitting on disk on the server machine.

I won’t dwell on the uses of this mechanism, since I think there are many, but here’s one example: a teacher can assemble a world to use as an interactive classroom, allow students to interact with it, store the results of their interactions as a snapshot to re-visit later, and then reset to the original world state for the next group of students. 

Where are the WFSs stored on the server?

All of Initial Worlds and World Snapshots found are WFSs sitting on disk on the server machine in the ~/.wonderland-server/0.5-dev/wfs directory. Beneath the wfs/ directory exists two sub-directories: worlds/, which store initial world state and snapshots/, which store the snapshots of world state. Users can find the XML files belonging to a WFS found beneath a directory with the standard -wfs suffix.

Like in 0.4, users are free to edit any WFS found in these directories by hand. The restore link next to each of the entries beneath Initial Worlds and World Snapshots re-reads the WFS and restores the world state to it.

Packaging a WFS in a module

Our module system in 0.5 allows users to package a WFS inside a module; when that module is installed on a server, the WFS is then automatically installed under Initial Worlds to use. This is how we distribute the set of Initial Worlds that you see as part of Wonderland out-of-the-box. Anyone is free to use the module system to distribute initial world to others too, here’s a manual set of steps to follow. (It would be great to be able to "select" a subset of a world and export it as a WFS in a module, but that’s future work). These steps assume you are familiar with Wonderland modules and developer tools such as ant. I’ve included the example module that I put together for this blog: .tar.gz and .zip.

  1. Launch a Wonderland server and client. In the client, assemble a world as you like. I started with an empty world and added the SVG Whiteboard.
  2. In the Web Administration UI, under the Manage Snapshots tab, create a new snapshot. It should create a snapshot beneath the snapshots/ directory, using the time and date the snapshot was created as a subdirectory name. For example, my snapshot is found under the 2009-06-24-14-24-40.86/world-wfs/ subdirectory.
  3. Set up a new, empty module project. (You can take the module I attach above and just replace my WFS). Make sure you edit the file to rename your module (as you see fit) and to point it to your installation of the Wonderland code base.
  4. Beneath the wfs/ directory in the module, copy your world-wfs/ directory. The name of the directory (without the -wfs suffix) becomes the name that appears in the Initial Worlds list. I named my WFS myworld-wfs/ in the example attached above. Also note how the build.xml includes the <part name="wfs" dir="${current.dir}/wfs"/> tag between the <module></module> tags — this tells the build system to bundle everything beneath the wfs/ directory into the module.
  5. To build and deploy the module to the running server, enter ant deploy on the command-line within the module directory.
  6. Refresh the Manage Snapshots tab in the Web Administration UI and notice how myworld-wfs appears beneath the Initial Worlds heading. Clicking the make current link next to myworld-wfs will reset the state of the world to the WFS.

While in this example the module only contains a single WFS, modules may contains multiple WFSs, code, and art work
, just like any module in Wonderland.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: