Specification Pattern as a Refactoring Tool

The Specification pattern in its core is simple, it consists of an interface with one method:

To reach our goals set up above, Evans extends it using the GoF Composition and Decorator patterns to give it some more operations:

We can implement this with one interface, one abstract class and three specialized classes, one each for the AND, OR, and NOT operations:

public interface Specification {

  boolean isSatisfiedBy(Object o);

  Specification and(Specification specification);

  Specification or(Specification specification);

  Specification not(Specification specification);
}


public abstract class AbstractSpecification implements Specification {

  public abstract boolean isSatisfiedBy(Object o);

  public Specification and(final Specification specification) {
    return new AndSpecification(this, specification);
  }

  public Specification or(final Specification specification) {
    return new OrSpecification(this, specification);
  }

  public Specification not(final Specification specification) {
    return new NotSpecification(specification);
  }
}


public class AndSpecification extends AbstractSpecification {

  private Specification spec1;
  private Specification spec2;

  public AndSpecification(final Specification spec1, final Specification spec2) {
    this.spec1 = spec1;
    this.spec2 = spec2;
  }

  public boolean isSatisfiedBy(final Object o) {
    return spec1.isSatisfiedBy(o) && spec2.isSatisfiedBy(o);
  }
}


public class OrSpecification extends AbstractSpecification {

  private Specification spec1;
  private Specification spec2;

  public OrSpecification(final Specification spec1, final Specification spec2) {
    this.spec1 = spec1;
    this.spec2 = spec2;
  }

  public boolean isSatisfiedBy(final Object o) {
    return spec1.isSatisfiedBy(o) || spec2.isSatisfiedBy(o);
  }
}


public class NotSpecification extends AbstractSpecification {

  private Specification spec1;


  public NotSpecification(final Specification spec1) {
    this.spec1 = spec1;
  }

  public boolean isSatisfiedBy(final Object o) {
    return !spec1.isSatisfiedBy(o);
  }
}

Now, lets see how we can implement

our rules. Implementing the color rule is straight-forward, like this:

public class CarColorSpecification extends AbstractSpecification {
  private Color color;

  public CarColorSpecification(Color color) {
    this.color = color;
  }

  public boolean isSatisfiedBy(Object o) {
    if (o instanceof Car) {
      Car car = (Car) o;
      return car.color() == color;
    } else {
      throw new ClassCastException("I only deal with cars, you gave me: " +
         o.getClass().getCanonicalName());
    }
  }
}

Our example now looks like this:

public class CarServiceImpl implements CarService {

  private CarRepository repository;

  public void setRepository(final CarRepository repository) {
    this.repository = repository;
  }

  public Collection<Car> findCandidateCars() {

    final Collection<Car> keepers = new HashSet<Car>();

    final CalendarDate today = Clock.now().calendarDate(TimeZone.getTimeZone("GMT"));

    final Specification approvedAge = new CarAgeSpecification(today, 5);
    final Specification colorRed = new CarColorSpecification(RED);
    final Specification convertible = new ConvertibleCarSpecification();
    final Specification approvedState = 
  new CarOwnerRegionSpecification(getAuthorizedRegions());

    final Specification candidateCarSpecification =     
             colorRed.and(approvedState.and(approvedAge).or(convertible));

    final Collection<Car> cars = repository.findAllCarsInStock();

    for (Car car : cars) {
      if (candidateCarSpecification.isSatisfiedBy(car))
        keepers.add(car);
    }

    return keepers;
  }

  private Set<Region> getAuthorizedRegions() {
    Set<Region> regions = new HashSet<Region>();
    regions.add(Region.SOUTH_WEST);
    regions.add(SOUTH_EAST);
    regions.add(SOUTH);

    return regions;
  }
}

Nice! This almost reads like natural language, the individual specifications are straightforward to test and the rules can easily be reused in other parts of the application. If we would like to make some or all of the rules externally configurable it is trivial to inject pre-configured specification instances via a dependency injection framework, like Spring. We may not end up with fewer lines of code, actually, counting the specification classes it’s certainly more lines, but I like this code a lot better than what we had before due to its clarity.

But we are not done yet. Let’s revisit the CarColorSpecification. This class looks quite good, but with a little help from Java 5 and Generics we can clean it up a bit. After updating the interface and classes to work with Generics, the specification can be written as:

public class CarColorSpecification extends AbstractSpecification<Car> {

  private Color color;

  public CarColorSpecification(Color color) {
    this.color = color;
  }

  public boolean isSatisfiedBy(final Car car) {
    return car.color() == color;
  }
}

Now we have compile-time type checking. We can get rid of that ugly instanceof cast, and also throw out some pointers in the Javadoc that now are explicitly stated in the method signature. The specifications are part of the domain, they are really specialized Value Objects, and by modifying our service just a little bit we can extract the specifications from the service implementation and make the service more general and the domain concepts even more explicit. The service will pull from the repository whatever we specify it to get:

public class CarServiceImpl implements CarService {

[...]

  /**
   * Check the national used car repository and find 
   * cars satistfying the given specification.
   *
   * @param specification Car specification.
   * @return Candidate cars.
   */
  public Collection<Car> findCandidateCars(Specification<Car> specification) {

    final Collection<Car> keepers = new HashSet();
    final Collection<Car> cars = repository.findAllCarsInStock();

    for (final Car car : cars) {
      if (specification.isSatisfiedBy(car))
        keepers.add(car);
    }
    return keepers;
  }

[...]

}

We could also adjust the CarRepository interface to accept the specification, arguing that this is really all about searching the repository for matching cars, and that is the responsibility of the CarRepository.

This pattern is nice to use when modeling and designing right from the start of a project, but as presented above it is also a nice tool for refactoring existing code.

For a more detailed discussion on the Specifications pattern, see Domain-Driven Design by Eric Evans. In the book you will also see examples of how we can express selection specifications, like the one described here, in a query language such as SQL, or in a combination of SQL and other languages. This will help performance, enabling us to actually use specifications for our next eBay application. You will also find examples of using the Specifications pattern for validation and creation, e.g. build me an instance of Car that fulfills this specification.

All the code above, complete with running scenario tests, is available for download at http://code.google.com/p/specification/. There you will also shortly find a packaged JAR-file with the generic specification classes above, ready for immediate use in your project!