Active Record Pattern

This pattern belongs to Data Source Architectural Patterns Catalog and this Catalog belongs to Patterns of Enterprise Application Architecture.

Intent

An object that wraps a row in a database table or view, encapsulates the database access and adds domain logic on that data.

Explanation

Each Active Record is responsible for saving and loading to the database and also for any domain logic that acts on the data.

An object carries both data and behavior. Much of this data is persistent and needs to be stored in a database.

Active Record uses the most obvious approach, putting data access logic in the domain object. This way all people know how to read and write their data to and from the database.

The principal difference between the Row Data Gateway and Active Pattern is the Row Data Gateway pattern does not contain domain logic methods and the Active Pattern object contains domain logic methods.

As an example, imagine we needed some domain logic methods to the StudentGateway to determine if a student has a passing grade or if they’re on probation :
 public boolean passes() {
  return grade!='F';
 }
 public boolean onProbation() { // a grade of D or F
     // results in being put on probation…
  return grade>='D';
 }

How It Works

The essence of an Active Record is a Domain Model in which the classes match very closely the record structure of an underlying database. Each Active Record is responsible for saving and loading to the database and also for any domain logic that acts on the data.
The Active Record class typically has methods that do the following:
  • Construct an instance of the Active Record from a SQL result set row
  • Construct a new instance for later insertion into the table
  • Static finder methods to wrap commonly used SQL queries and return Active Record objects
  • Update the database and insert into it the data in the Active Record
  • Get and set the fields
  • Implement some pieces of business logic
Active Record is very similar to Row Data Gateway. The principal difference is that a Row Data Gateway contains only database access while an Active Record contains both data source and domain logic.

When to Use It

Active Record is a good choice for domain logic that isn't too complex, such as creates, reads, updates, and deletes. Derivations and validations based on a single record work well in this structure.

Sample Code

Example: A Simple Person (Java). Let's create a Class Diagram for the sample code of Person class to demonstrate this pattern.

This is a simple, even simplistic, example to show how the bones of Active Record work. We begin with a basic Person class.
public class Person {   private int id;
   private String lastName;
   private String firstName;
   private int numberOfDependents;
   // getter and setter methods
}
The database is set up with the same structure.
create table people (ID int primary key, lastname varchar,
                     firstname varchar, number_of_dependents int) 
To load an object, the Person class acts as the finder and also performs the load. It uses static methods in the Person class.
public class Person{
  private final static String findStatementString =
         "SELECT id, lastname, firstname, number_of_dependents" +
         "  FROM people" +
         "  WHERE id = ?";
   public static Person find(Long id) {
      Person result = (Person) Registry.getPerson(id);
      if (result != null) return result;
      PreparedStatement findStatement = null;
      ResultSet rs = null;
      try {
         findStatement = DB.prepare(findStatementString);
         findStatement.setLong(1, id.longValue());
         rs = findStatement.executeQuery();
         rs.next();
         result = load(rs);
         return result;
      } catch (SQLException e) {
         throw new ApplicationException(e);
      } finally {
         DB.cleanUp(findStatement, rs);
      }
   }
   public static Person find(long id) {
      return find(new Long(id));
   }
   public static Person load(ResultSet rs) throws SQLException {
      Long id = new Long(rs.getLong(1));
      Person result = (Person) Registry.getPerson(id);
      if (result != null) return result;
      String lastNameArg = rs.getString(2);
      String firstNameArg = rs.getString(3);
      int numDependentsArg = rs.getInt(4);
      result = new Person(id, lastNameArg, firstNameArg, numDependentsArg);
      Registry.addPerson(result);
      return result;
   }
}
Let's add the update method to Person class.
public class Person{
   private final static String updateStatementString =
         "UPDATE people" +
         "  set lastname = ?, firstname = ?, number_of_dependents = ?" +
         "  where id = ?";
   public void update() {
      PreparedStatement updateStatement = null;
      try {
         updateStatement = DB.prepare(updateStatementString);
         updateStatement.setString(1, lastName);
         updateStatement.setString(2, firstName);
         updateStatement.setInt(3, numberOfDependents);
         updateStatement.setInt(4, getID().intValue());
         updateStatement.execute();
      } catch (Exception e) {
         throw new ApplicationException(e);
      } finally {
         DB.cleanUp(updateStatement);
      }
   }
}
Let's add the insert method to Person class.
public class Person{
   private final static String insertStatementString =
         "INSERT INTO people VALUES (?, ?, ?, ?)";
   public Long insert() {
      PreparedStatement insertStatement = null;
      try {
         insertStatement = DB.prepare(insertStatementString);
         setID(findNextDatabaseId());
         insertStatement.setInt(1, getID().intValue());
         insertStatement.setString(2, lastName);
         insertStatement.setString(3, firstName);
         insertStatement.setInt(4, numberOfDependents);
         insertStatement.execute();
         Registry.addPerson(this);
         return getID();
      } catch (Exception e) {
         throw new ApplicationException(e);
      } finally {
         DB.cleanUp(insertStatement);
      }
   }
}
Any business logic, such as calculating the exemption, sits directly in the Person class.
public class Person{
   public Money getExemption() {
      Money baseExemption = Money.dollars(1500);
      Money dependentExemption = Money.dollars(750);
      return baseExemption.add(dependentExemption.multiply(this.getNumberOfDependents()));
   }
   
   public boolean isFlaggedForAudit() {
      // Business logic 
   return true;
   }
   
   public String getTaxableEarnings() {
      // Business logic
   }
}

References

Comments