Spif in detail

This document describes the core functionality of Spif in detail. Eeven more details are found in the Javadoc.

The Store API

The core of Spif is a simple API for accessing objects called StoreChain:

public class StoreChain {

    public Object get(Id id,boolean writable);

    public Id put(Id id,Object object);

    public boolean remove(Id id);

}

The Id class is also a part of Spif. You will probably want to subclass it to make id classes for your business objects.

By employing a general and carefully thought out interface for the most common task of every distributed oo application, a lot of code is saved since there is no need to make separate mechanisms for different object types. But more importantly, it provides great opportunity for changing the infrastructure carrying out the access requests without changing the business code making the requests. This is done by supporting chain of resposibilities in the API:

public class StoreChain {

    public Object get(Id id,boolea writable);

    public Id put(Id id,Object object);

    public boolean remove(Id id);

    public StoreChain setChained(StoreChain chain);

}

So, the business code makes calls to a single, well known StoreChain implementation, without having to worry about which store chain is actually carrying out the requests. The well known implementation is called Store and contains static versions of the interface methods for convenience. It contains no behaviour apart from forwarding to whatever is chained to it.

So to use Spif, you write business code which uses Store:

import net.sf.spif.Store;
....
    public void increaseSalary(EmployeeId id) {
        boolean writable=true;
        Employee employee=(Employee)Store.get(id,writable);
        employee.setSalary(employee.getSalary()*1.5);
        Store.put(id,employee);
    }

Store chains

Store.setChained(new HashStore());

Store.setChained(new StoreAccumulator()).
      setChained(new StoreCache(1000,false)).
      setChained(new StoreClient());

Store.setChained(new StoreLocker()).
      setChained(new StoreCache(1000,true)).
      setChained(new StorePersister());

This uses the relational persistence store chain class supplied with Spif. Some prefer to write chain classes adapting to other persistence layers, e.g. entity beans or Hibernate.

In addition to the supplied store chains, all projects write their own. In fact you'll find that you can add lots of functionality in no time by writing store chains. Typical tasks which has successfully been handles by Spif chains are:

• access checking on object level (not method level as build into EJB)
• reference integrity, for instance cascading deletes on the object level or denying deletes unless certain conditions hold
• updating third-party objects which needs to know about changes in some objects. For instance updating a collection of tree roots for tree node objects sent through the chain.

You can probably think of many other uses. Being able to intercept any operational object access by writing a few lines of code is a very powerful thing. If you write some reusable chain class, please send it to me, or ask to be granted Spif cvs checkin rights.

The supplied store chains classes

The following subclasses of StoreChain are included. You do not need to use any of them to use Spif, you just need to be model centric, have Id's for you main classes and access them through Store. But skim through the list before you consider writing your own ones.

Thats all! Spif isn't just the simples infrastructure framework around, it is also the smallest. Its most effective feature is not the supplied chain implementations but that it helps organizing a system in a beneficial way, not by force, but by being the simplest way to get things done.

An example model object for use with Spif

For completeness, I include an example model object, as it would typically be implemented when used with Spif. The thing of importance here is that the id of the model object extends net.sf.spif.Id and is named >Modelclassname<Id. This fact makes it possible for methods of Id to infer the model class type from the id, which is often useful for Spif chain classes.

The full source of the example classes is included in the source of the Spif distribution.

package net.sf.spif.example;

import java.util.List;
import java.util.Iterator;
import java.util.Collections;

public class Person {

  private PersonId id=null;

  private String name;

  private Address address;

  private List children=new java.util.ArrayList();

  /** 
   * Create a person and assign a unique id in some way I am
   * not going into here. You may also have some store chain create
   * the id on put: PersonId newId=Store.put(null,newPerson);
   */
  public Person(String name) {
    if (name==null) 
      throw new NullPointerException("A persons name can not be null");
    this.name=name;
    setId(new PersonId(name)); // Not suited for production
  }

  /** Public for state restoration only, i.e. persistence */
  public void setId(PersonId id) {
    if (this.id!=null) 
      throw new IllegalStateException("Refusing to change id of " + this);
    this.id=id;
  }

  public PersonId getId() {
    return id;
  }  

  public void setName(String name) {
    this.name=name;
  }

  public String getName() {
    return name;
  }

  /** 
   * (The address is a dependent object - 
   * part of the same edit bubble)
   */
  public void setAddress(Address address) {
    this.address=address;
  }

  public Address getAddress() {
    return address;
  }

  /** 
   * Returns an iterator of the ids of the children of this class.
   * (So this is not part of the sane edit bubble, although 
   * collections may very well be)
   *
   * @return a read-only iterator of children personId's,
   *         or an empty iterator if there is no children
   */
  public Iterator getChildren() {
    return Collections.unmodifiableList(children).iterator();
  }

  public void addChild(PersonId childId) {
    if (childId.equals(id)) 
      throw new IllegalArgumentException("Come on! Not even " + this +
                                         " is it's own child");
    children.add(childId);
  }

  /** @return true if the child was removed, false if it wasn't present */
  public boolean removeChild(PersonId childId) {
    return children.remove(childId);
  }

  // If the class is used by rich clients you'll often need positional
  // methods for collections, at least getChildCount()
  // getChild(int position):PersonId and indexOf(PersonId):int 
  // and some order determinism (sorting)

  public String toString() {
    return name + " ( " + id + ")";
  }

}

package net.sf.spif.example;

public class PersonId extends net.sf.spif.Id {

  public PersonId(String idString) {
    super(idString);
  }

}

package net.sf.spif.example;

/** 
 * Notice that dependent objects does not need an id.
 * Apart from that, I know the simplicity here will offend anyone 
 * who has worked with customer addresses in real systems.
 */
public class Address {

  /** The street, including street number */
  private String street;

  private int zip;

  private String city;

  public Address(String street,String city,int zip) {
    // TODO: Validate
    this.street=street;
    this.city=city;
    this.zip=zip;
  }

  // TODO: Simple getters and setters

}

By Jon S Bratseth. Last updated 2002-12-29.