2-minute Tutorial

Authors: cv and Jon Tirsen

Eager to try out Prevayler? Ok, this tutorial should give you the bare basics you need to know, while developing a really simple prevalent system to give you an idea of what to expect. If you have any questions, please post them as comments, or get in touch by e-mail.

So, let's get started! Download Prevayler and put the JAR in your CLASSPATH.

Implementing your business objects

We're going to create a simple system to manage a quick-and-dirty to-do list. The very first thing we need to create, then, is a Task:

An error occurred: cvs.prevayler.codehaus.org. The system administrator has been notified.

Notice that the Task class must implement java.io.Serializable, and all its fields must be serializable, too.

Then, we proceed to create a TaskList:

An error occurred: cvs.prevayler.codehaus.org. The system administrator has been notified.

On this TaskList, we have two methods that change the data on our system: addTask() and removeTask(). Because of the way Prevayler works (saving every change to the system, instead of the data itself), we must wrap any calls to these methods inside Transaction objects (Command Pattern).

Implementing your transactions

Every Transaction represents one or more changes to the system, and you can think of everything that goes inside the executeOn() method as pertaining to a BEGIN ... COMMIT block in your database.

In the case of our AddTask transaction, it's helpful to return the Task we just created to the users, so they can manipulate it further. We implement TransactionWithQuery:

An error occurred: cvs.prevayler.codehaus.org. The system administrator has been notified.

The RemoveTask code is pretty much the same, but it implements Transaction (as it doesn't need to return anything):

An error occurred: cvs.prevayler.codehaus.org. The system administrator has been notified.

In both cases, we have encapsulated the changes to be made to our system into small chunks of reusable code.

Starting up Prevayler and manipulating data

Next, we need a way to execute those transactions. For that, we first need a reference to a Prevayler object:

An error occurred: cvs.prevayler.codehaus.org. The system administrator has been notified.

These two lines are doing a lot of things behind the scenes. When you create a new Prevayler, it checks if you have any transaction logs or snapshots into your "prevalence base", in our case, the /tasklist-base directory, and tries to load them up, so you have all your data and state back. It's very important to call prevalentSystem() here, or you will not get the correct object.

Then we can add and remove tasks to our heart's content:

An error occurred: cvs.prevayler.codehaus.org. The system administrator has been notified. An error occurred: cvs.prevayler.codehaus.org. The system administrator has been notified.

Simple, isn't it?

Taking snapshots

Every other day we can take a snapshot, that is, save the contents of our whole object graph to disk so we don't have to replay all the transaction logs again when we start the system:

An error occurred: cvs.prevayler.codehaus.org. The system administrator has been notified.