exedio persistence

Persistence Framework for Java.

Introduction Trail

This is the initial trail of the documentation trails. It gives you a step-by-step introduction into the persistence framework.

If you already decided to use exedio persistence for a project, you may want to use the demoshop as a template. This way you can skip most of the steps described here. The demoshop is available under the The MIT License.
Download

Your first item

Creating a new persistent class is as easy as creating any java class. Make sure, the class extends Item:

class Customer extends Item
{
}

Now a persistent class isn't very useful without any persistent fields, so we also create our first one. To do this we declare a static final constant of the type StringField.

class Customer extends Item
{
   static final StringField email = new StringField();
}

Thats the way you declare persistent classes and fields. Now we have to setup the source code instrumentor.

Setting up the instrumentor

The instrumentor inserts a few methods and constructors into your source code, so you don't have to write it on your own. Don't worry, your code and the code generated by the instrumentor will peacefully coexist.

Put a copy of exedio-cope.jar, exedio-cope-instrument.jar, trove.jar and bsh-core.jar into the directory where you keep your third-party libraries. In the following we assume, this is lib.

Next we have to include the code instrumentor into your build process. Here we explain this for a build process managed by apache ant. We assume, that there is already a target compile which compiles your projects sources including class Customer created above located in directory src. Put the following into your build.xml

<taskdef name="instrument"
         classname="com.exedio.cope.instrument.AntTask">
  <classpath>
    <pathelement location="lib/exedio-cope-instrument.jar" />
  </classpath>
</taskdef>

<target name="instrument">
  <instrument verbose="false">
    <fileset dir="${basedir}/src">
      <include name="*.java" />
    </fileset>
  </instrument>
</target>

Parts in italics need to be adapted to your directory layout. Make target compile depend on target instrument and add lib/exedio-cope.jar to the classpath of the javac task.

Now the instrumentor is ready to run. On the command line type ant instrument.

Results of the instrumentor

After running the instrumentor, the class Customer contains a few more methods and constructors. Lets have a look, what these are useful for.

The first one in the default creation constructor:

Customer(String email)
{
   this(new SetValue[]{Customer.email.map(email)});
}

It creates a new customer and sets the initial value of the field email for that customer. Note, for brevity the code snippet above does not include javadoc comments generated by the instrumentor.

Next one is the generic creation constructor:

Customer(SetValue[] setValues)
{
   super(setValue);
}

It creates a new customer and sets the initial values for any set of fields for that customer. This comes handy if there are more fields in class Customer, since by default not all fields are set by the default creation constructor.

Next one is the activation constructor:

Customer(ActivationParameters ap)
{
   super(ap);
}

All you need to know about this for now is, that the framework uses this constructor internally and you don't have to care about. This constructor is one of the few things the framework has to demand for all persistent classes.

Next are the field getter and field setter for the field email:

String getEmail()
{
   return email.get(this);
}

void setEmail(String email)
{
   Customer.email.set(this, email);
}

These allow convenient read/write access to the values of the field, after the creation of the item.

Last but not least there is the type constant:

static final Type<Customer> TYPE =
    newType(Customer.class);

This is useful for all sorts of things, most prominently searching the database. For instance searching for all customers is as easy as Customer.TYPE.search(), which returns a List<Customer>. More on this in the Searching Trail.

Next we will really store some persistent data.

Make it run

First we have to tell the framework, which persistent types are to be maintained by the project. For now this will be type Customer only. So we write a new class Main:

class Main
{
   static final Model model = new Model(
         Customer.TYPE
      );
}

Of course, if you already have some central kind of main class, you can use this instead of writing a new one. Just make sure, that all your persistent types show up in the list.

Next we will setup the database connection to be used by exedio persistence. First put a jdbc driver (i.e. hsqldb.jar or mysql-connector-bin-3.1.12.jar) in your classpath.

Then create a file cope.properties with the following contents for hsqldb:

connection.url=jdbc:hsqldb:mem:copetest
connection.username=sa
connection.password=

or alternativly for mysql:

connection.url=jdbc:mysql://localhost/copetest
connection.username=user
connection.password=password

Parts in italics need to be adapted to your database. For mysql make sure, that the database does exist (create database copetest) and is accessible for the user.

Finally we can add a main method to class Main, that creates a customer in the database.

public static void main(String[] args)
{
   model.connect(
      new ConnectProperties(new File("cope.properties")));
   model.createDatabase();
   model.startTransaction();
   Customer c = new Customer("copetest@exedio.com");
   System.out.println("email:"+c.getEmail());
   c.setEmail("copetest@exedio.com");
   System.out.println("email2:"+c.getEmail());
   model.commit();
}

The call to createDatabase builds the schema of the database. For this example it issues an sql statement like create table Customer ( email varchar(100) ) to the database. Note, that for mysql the main method work once only. On any subsequent calls createDatabase fails, because table Customer already exists. On hsqldb the method work multiple times, because the database is in-memory only.