Keel 2.1RC2

Package org.keel.services.persist

Persistence Service - Storing objects in databases and other persistent stores.

See:
          Description

Interface Summary
DatabaseType A DatabaseType provides information and methods that allow persistent objects to talk to a specific kind of database.
Helper A "Helper" is an object that is related to a particular persistent object, containing methods and logic that are connected logically to the persistent object itself.
Persistent A persistent object.
PersistentFactory A PersistentFactory is a class that generates new Persistent objects, Transactions, and Queries.
PersistentMetaData This object contains the "definition" of a Persistent, all of the Meta-data that associates it with a particular database table.
Relation A relationship between two persistents.
Transaction Request an instance of this interface from the PersistentFactory
 

Class Summary
AbstractHelper Abstract helper is simply a handy superclass that implements the Helper interface.
AdvancedPersistentServiceTest  
BasicPersistentServiceTest  
 

Exception Summary
PersistenceException Used to report a problem at the persistence level
 

Package org.keel.services.persist Description

Persistence Service - Storing objects in databases and other persistent stores.

Overview

This package contains the interfaces for the persistance services, which provides service for persisting objects in a number of different stores, via a number of different implementations.

Note that this service is quite different from JDO, even though some of the object and method names are similar, in that the isolation from the underlying data store is not as large, and we are assuming that we're talking to a relational database via JDBC, which JDO does not. This package does not use any kind of byte-code enhancement, and allows full access to SQL as a query language. There is, of course, no reason why keel might not also incorporate at a later time a JDO-compliant persistence service, either as an implementation of this service or an entirely seperate service. It's all about choice, after all! We will also be keeping a close eye on the ObjectRelationalBridge project, recently moved to Apache.

In this top-level package are the interfaces that define the services provided by this service.

PersistantFactory is the primary service. The service manager should be used to get your PersistantObjectFactory of choice, which is then used to create PersistantObject objects as required for your application. If you're doing this from within a Model object, use the getService method in the ModelRequest object.

These objects are then used to store object data to and from the supported store mechanisms.

You can use three different methods to define persistent objects in your application:

JavaBeans

You can define classes that follow the JavaBean signatures, e.g.

public class Book {
  private String title = null;
  private String author = null;

  public void setTitle(String newTitle) {
    title = newTitle;
  }

  public String getTitle() {
    return title;
  }

  public void setAuthor(String newAuthor) {
    author = newAuthor;
  }

  public String getAuthor() {
    return author;
  }
}

Such classes can be handled directly by the PersistentFactory, which simply "wraps" them as a Persistent object, creating the necessary "Peer" persistent object on the fly as required.

You can do this kind of thing:

Book myBook = new Book();
myBook.setAuthor("fred");
myBook.setTitle("Some Book");

PersistentFactory pf = PersistentFactory.getInstance(req.getContext());
pf.add(myBook);

This stores the myBook fields in the proper database table - where the table is defined in the XML configuration, just the same as other Persistent objects.

This method is useful when you have methods that perform some kind of logic in the Bean, as well as the getters and setters for the bean properties (although you can do this with Helper objects, discussed later, if you prefer).

DynaBeans

You can define classes that follow the DynaBean signatures, e.g. use get(String) and set(String, Object) methods to define their fields, e.g.
public class Book extends AbstractPersistent {
  public void set(String fieldName, Object value) {
     ... do something ...
     super.set(fieldName, value);
  }

  public Object get(String fieldName) {
    ... some some other stuff ...
    return super.get(fieldName);
  }
}

This method is useful where you have some logic in the Book class - e.g. it is not just a collection of methods - but you don't want to go all the way to a generic JavaBean-type object like the first example. This method also makes it easy to put in custom validations directly in the object - although again this can be done with helper objects, as we discuss below.

A variation on this approach is to have your Book class not extend an AbstractPersistent, but instead "wrap" one, like so:

public class Book implements Persistent {

  private myPersistent = null;

  public void set(String fieldName, Object value) {
     ... do something ...
     myPersistent.set(fieldName, value);
  }

  public Object get(String fieldName) {
    ... some some other stuff ...
    myPersistent.get(fieldName);
  }

  public void add() {
    myPersistent.add();
  }
}

This approach is useful when you do not have control over the object hierarchy (e.g. you must inherit from something else), but it does require a lot of methods to be implemented for the Persistent interface.

Generic Persistent objects

You can avoid defining any classes, and have the PersistentFactory just create generic Persistent objects for you as required.

PersistentFactory pf = PersistentFactory.getInstance(req.getContext());
Persistent myBook = pf.create("book");
myBook.setField("author", "fred");
myBook.setField("title", "Some Book");
myBook.add();

These generic objects are not of a specific class - they are all of class Persistent. To add custom methods to persistent objects created this way, you must use a Helper object. This can be any kind of class that implements the Helper interface, or it can be a sub-class of the handy AbstractHelper abstract class, so you can just override or extend the methods you need. Helper methods are called for all significant events on the Persistent class they are associated with, and a seperate instance of the helper is created for every instance of the Persistent itself.

So, which approach do you use in your Model objects? We recommend the latter one - generic Persistent objects. It is by far the easiest to use, and simple is good. If you find it cannot do the job for you entirely, try adding a Helper object. If this also isn't cutting it, then you may have to fall back on the DynaBean or regular JavaBean methods described above, but they are definitely more work and more maintenance.


Keel 2.1RC2

Please see keelframework.org for information about new Keel releases.