We present now a brief tutorial about JSO. After reading the tutorial please take a time to see some examples.

Coding storable classes

To create a storable class you need to respect some rules, but basically you just need to declare it is storable and create a void constructor. To declare the class is storable simply make it implement the Storable interface. This interface is only a marker an no extra work is needed, although more things can be done as we will see.

import net.sf.jso.Storable;

public class MyStorableClass implements Storable {

  public MyStorableClass() {
    // void constructor must exist!


Specifying class metadata

Storable classes are inspected by JSO at the first time they are used. Many characteristics can be obtained, but some others can not. For instance, how could you declare indices for you class? Or the fields that compose class' summary? All this can be informed through class metadata.

To inform class metadata to JSO you need to create a static method, named jsoClassMetadata(), that returns an object of the class StorableClassMetadata. This object will be used by JSO to obtain more "storable" characteristcs of the class. Below we show a classe declaring metadata with information about indices and summary fields.

import net.sf.jso.Storable;
import net.sf.jso.schema.StorableClassMetadata;
import net.sf.jso.schema.StorableIndex;

public class User implements Storable {

  // Class metadata.
  private static StorableClassMetadata classMetadata;
  // Returns class metadata.
  private static StorableClassMetadata jsoClassMetadata() {
    if(classMetadata == null) {
      // Summary fields.
      String[] summary = new String[] {"name","login","email"};
      // Index for name and unique index for login.
      StorableIndex nameNdx = new StorableIndex("name",new String[] {"name"});
      StorableIndex loginNdx = new StorableIndex("login",new String[] {"login"},true);
      StorableIndex[] ndxs = new StorableIndex[] {nameNdx,loginNdx};
      // Informs summary and indices.
      classMetadata = new StorableClassMetadata(summary,ndxs);
    return classMetadata;


Object metadata

Sometimes may be useful to know a little more about the storage process of an object. For that reason JSO provides a way to make such information available to you, through object metadata.

Storable classes may declare a field, named jsoMetadata(), that will hold storate metadata as an object of the class (actually an interface) StorableMetadata. After every persistence operation on the object, JSO will update storage metadata on this field. The class below implements a method to make objects' OIDs available to the application.

import net.sf.jso.OID;
import net.sf.jso.Storable;
import net.sf.jso.StorableMetadata;

public class User implements Storable {

  // Object metadata.
  private StorableMetadata jsoMetadata;

  public OID getOID() {
    OID oid = null;
    if(jsoMetadata != null) {
      oid = jsoMetadata.getOID();
    return oid;



Callback methods

Another feature offered by JSO are the callback methods. A storable class may declare the methods jsoPreStore(), jsoPostRetrieve() and jsoPreDelete() to become aware of persistence events. As showed below the storable class declares two transient fields, that will not be stored. However, it also implements the jsoPostRetrieve() method, so that when an object is retrieved from the database its value (all fields) will be consistent.

import net.sf.jso.Storable;

public class ComplexNumber implements Storable, Cloneable {

  // Using name "real_" instead of "real" to avoid database reserved words.
  private double real_;
  private double imaginary;
  private transient double modulus;
  private transient double argument;
  public ComplexNumber() {

  public ComplexNumber(double r, double i) {

  public void set(double r, double i) {
    real_ = r;
    imaginary = i;

  private void jsoPostRetrieve() {
    // Only cartesian coordinates are stored.
    // After retrieval polar coordinates are calculated.

  private void calculatePolar() {
    modulus = Math.sqrt(real_*real_ + imaginary*imaginary);
    argument = Math.atan2(imaginary,real_);



Storage environment

Before start requesting persitence services to JSO, an application program must start the storage controller and the storage manager. Or, in case of a distributed application, the program must start a manager and connect it to the controller. To make things more easy JSO has a class that represents the storage environment of the application. The interface StorageEnvironment, implemented by the class JSOEnvironment, has some methods to facilitate environment start up and shut down.

import net.sf.jso.StorageEnvironment;
import net.sf.jso.StorageManager;
import net.sf.jso.engine.JSOEnvironment;

public class MyProgram {

  public static void main(String[] args) throws Exception {
    // Starts storage environment to a local application.
    StorageEnvironment env = new JSOEnvironment();
    // Gets reference to the storage manager.
    StorageManager manager = env.getManager();


    // Stops storage environment.

When the environment is started, the storage manager may be accessed through the manager reference and persistence services can be requested.

Storing an object

An object may be stored through a call to one of the store() methods. The OID of the stored object is returned.


    // Creates clients and accounts and makes deposits. 
    Client xexeo = new Client("Geraldo Xexeo","987.654.321-01","Fake St. 123");
    Client joao = new Client("Joao Alexandre","123.456.789-10","Evergreen Tr. 742");
    SpecialAccount account1 = new SpecialAccount(1,xexeo,10000);
    Account account2 = new Account(2,joao);

    // Stores clients.
    // Accounts and operations are also stored. (persistence by reachability)


Retrieving an object

An object may be retrieved from the database through a call to one of the retrieve() methods. The OID of the stored object must be informed. If the OID is not known then a query must be done.


    // Creates a complex number and clone it.
    ComplexNumber c1 = new ComplexNumber(3,4);
    ComplexNumber c2 = (ComplexNumber)c1.clone(); 

    // Stores the complex number.
    OID o1 = manager.store(c1);

    // Destroys the reference and retrieve the object whit a new one.
    c1 = null;
    ComplexNumber rc1 = (ComplexNumber)manager.retrieve(o1);


Updating an object

Updating an object means retrieving an object, modifying it and storing it with its new value.


    // Creates an user.
    User ned = new User();
    ned.setName("Ned Flanders");
    ned.setAddress("Evergreen Tr. 743");
    ned.setComments("Hello, I'm Ned Flanders.");

    // Stores the user.
    OID oidNed = manager.store(ned);

    // Destroys the reference and retrieve the object whit a new one.
    ned = null;
    User retNed = (User)manager.retrieve(oidNed);

    // Modifies the user.
    retNed.setComments("Heydilly-ho! I'm Ned Flanders! Okily-dokily-doo!");

    // Updates the user.


Deleting an object

An object may be delete through a call to one of the delete() methods. The OID of the stored object or the object itself may be used.

    // Stores the complex number.
    OID o1 = manager.store(c1);

    // Destroys the reference and retrieve the object whit a new one.
    c1 = null;
    ComplexNumber rc1 = (ComplexNumber)manager.retrieve(o1);


    // Deletes the object.
    // Can use this method.
    // (In this case callback method jsoPreDelete() will not be called)
    // Or can use this one.
    // (In this case jsoPreDelete() will be called)


Using transactions

Every persistence operation, performed through the methods discussed above (store(), retrieve() and delete()), is executed within a transaction. If none has been specified by the program JSO automatically uses one. JSO starts a transaction, executes the operation and then commits the started transaction. However, if a some task must perform more than one operation a transaction should be explicitly used.

JSO allows each thread to have one (and only one) transaction. A reference to current thread's transaction may be obtained through storage manager's getTransaction(). The Transaction interface has methods to begin, commit and roll back the transaction.


    // Begins a transaction.
    Transaction tx = manager.getTransaction();


    Account account = (Account)accounts.get(0);
    System.out.println(account.getNumber() + ": " + account.getClient().getName());
    System.out.println("Initial balance: " + account.getBalance());
    // Withdraws.
    // Stores account after operations.

    // Ends transaction.

If any exceptions are thrown during the execution of the transaction JSO automatically rolls it back. The reference to the transaction becomes unusable and a new reference should be acquired by the thread.

Querying the database

JSO allows querying the database through methods count(), countPages() and retrieve() of the interface QueryProcessor, which is extended by the StorageManager interface. These methods receive parameters that inform JSO which objects should be returned (or counted) from the database. The class Parameters can hold information about selection and order criteria, pagination, summarization and the usage of polymorphism. It also holds an array of Variables.

The variables represent the objects processed during query execution. A variable has an unique name within the parameters and has a class. At least one variable must be used, and if more than one is used the first one is considered as the "main" variable. The objects corresponding to the "main" variable are the ones retrieved by the query.

Selection criteria is done by the Criteria class. This class is actually used to build criteria expressions, while the Predicate class can in fact define selection criteria. A predicate is formed of a left operand, an operator (CriteriaOperator) and a right operand. The left operand always refers to the field of a variable. If no variable is specified to the left operand JSO uses the "main" variable. The right operand may be a value or field of a variable. In the last case a variable must be specified. Whenever more than one predicate must be used a Criteria object is used to create a predicate expression.

To order the results the Order and FieldOrder classes may be used. In an analogous way to the selection criteria the Order class is used to create expressions, while the FieldOrder class effectively defines order criteria. Such definitions consists of the field of a variable and an operator (OrderOperator). Again, if no variable is specified JSO uses the "main" variable.

Parameters also allow the list of objects selected by a query to be devided in pages, of pageSize objects, and make the result equal to the objects listed in a defined page.

Last, but not least, parameters hold indications whether summary objects should be returned and if polimorphism should be used (default).

Below, two examples of queries are shown.


    // Lists clients.
    Parameters paramsClients = new Parameters(Client.class);
    // Order by name.
    paramsClients.order = new FieldOrder("name",OrderOperator.ASC);
    // Use summaries.
    paramsClients.summaries = true;
    List clients = manager.retrieve(paramsClients);
    System.out.println(clients.size() + " client(s) found:");
    for(int i = 0; i < clients.size(); ++i) {
      Client client = (Client)clients.get(i);
      System.out.println(client.getName() + " - " + client.getIdentity());


    // Gets account 1.
    Parameters params = new Parameters(Account.class);
    // Account number.
    Integer number = new Integer(1);
    // Search predicate.
    params.criteria = new Predicate("number",CriteriaOperator.EQUAL,number);
    List accounts = manager.retrieve(params);
    // We know account 1 exists, but query result could be empty...
    Account account = (Account)accounts.get(0);
    System.out.println(account.getNumber() + ": " + account.getClient().getName());

The lists returned as the results of the queries are unmodifiable.

Using text fields

Text fields should be use whenever you would like to store long strings (longer than 255 characters). The Text class can be used almost seamlessly as the String class. The class below uses a text field and implements helper methods that receive Strings to set the field's value.

import net.sf.jso.Storable;
import net.sf.jso.text.Text;

public class User implements Storable {

  private String name;
  private String login;
  private String email;
  private String address;
  private String phone;
  private Text comments;
  public User() {

  public void setComments(String someComments) {
    comments = new Text(someComments);

  public void setComments(Text someComments) {
    comments = someComments;

  public Text getComments() {
    return comments;

JSO will use a LONGVARCHAR column to store this field.