Repositories

A repository is a special-purpose service object for keeping track of objects.

Below some design principles for repositories are stated.

• A repository is not the same as an RDBMS

  The mechanism used for keeping track of the objects can be anything.

  What is it with RDBMS as a default persistence mechanism anyway...

  All too often the management of application data is externalized from the application to a standalone data management system like a relational database management system (RDBMS). Data conserns like data aggregation, data access control, and data retrieval latency are important application design issues. Application data should by default belong to and be under strict control by the application (team) itself.

  The translations between the two-dimensional relational data model, and the three-dimensional object model are most often (yet again) externalized to an object-relational-mapping (ORM) tool. The use of an ORM tool brings tremendous, and most often unessesary, complexity into your application design. Bringing an ORM tool into a low-end application is an overkill. Also, at the other end of the scale; an RDBMS is not suitable for high-volume/high-throughput data applications unless elaborate tuning is applied. What's left is medium-range applications. One valid argument in favour of an ORM/RDBMS solution is if data is already placed in a RDBMS and in use by several other applications. Perhaps is it also already included in some data-mining activities. Only then the choice to stick with the RDBMS seems like an obvious one. Otherwise, you should think twice before choosing an ORM/RDBMS solution. At least, investigate some alternatives while you still have the chance.

• A repository is not the same as persistence

  As stated above, a repository is a special-purpose service object for keeping track of entity objects. That is, holding your entities so they are not garbage collected. Also, your entities should be easy to retrieve and otherwise manage. Persistence, albeit necessary in most non-trivial cases, is not a mandatory requirement for a repository.

• Repositories should be out-of-the-box

  When you need a repository, it should be just to pick an implementation, instansiate it, and start using it following a well-known API with consistent semantics. If you need another repository type inhibiting other properties, it should be easy to migrate your data. Importing and exporting application data should be a trivial task. Data should be a liquid asset.

• Queries should have a native look-and-feel

  A Java-based application should query for objects using Java. The query expressions should be consise, highly readable, and easy to maintain. Specifications are perfect as a query construct, but it does not stop there. Specifications define object spaces, so thay are perfect for partitioning your objects as well.

Domian Repositories

Domian repositories only keep track of entity objects. This is because of the transient nature of value objects. Value objects should not be put aside and reused in any way, but rather purged and recreated when needed.

Domian repositories are described by this interface:

public interface Repository<T extends Entity> {
    <V extends T> void          put                           (V entity);
                  void          putAll                        (Collection<? extends T> collectionOfEntities);
                  Long          countAllEntitiesSpecifiedBy   (Specification<? extends T> specification);
    <V extends T> Iterator<V>   iterateAllEntitiesSpecifiedBy (Specification<V> specification);
    <V extends T> Collection<V> findAllEntitiesSpecifiedBy    (Specification<V> specification);
    <V extends T> V             findSingleEntitySpecifiedBy   (Specification<V> specification);
    <V extends T> void          update                        (V entity);
    <V extends T> Long          removeAllEntitiesSpecifiedBy  (Specification<V> specification);
    <V extends T> Boolean       remove                        (V entity);
}

The interface also contains aliased methods, many of them compacted versions. See the net.sourceforge.domian.repository.Repository Javadoc for the complete listing.

Repository types

Figure 1 - Domian Repository Types

Repository<Customer> customerRepo = new InMemoryRepository<Customer>();

import static java.util.Arrays.asList;
...
Customer myCustomer = new Customer(1L, today);
Customer anotherCustomer = new Customer(2L, yesterday);
customerRepo.put(myCustomer);
customerRepo.put(anotherCustomer);
// or just
customerRepo.putAll(asList(myCustomer, anotherCustomer));

import static net.sourceforge.domian.specification.SpecificationFactory.*;
...
Collection<Customer> allCustomersCollection = customerRepo.find(all(Customer.class));
...
Specification<Customer> customersRegisteredBeforeToday = all(Customer.class).where("membershipDate", isBefore(today));
Collection<Customer> customersRegisteredBeforeTodayCollection = customerRepo.findAll(customersRegisteredBeforeToday);

Iterator<Customer> customerIterator = customerRepo.iterate(all(Customer.class).where("membershipDate", is(yesterday)));

myCustomer.setName("Chris the Customer");
customerRepo.update(anotherCustomer);
...
// some other thread...
Specification<Customer> customersWithKnownNames = allInstancesOfType(Customer.class).where("name", is(not(a(blankString()))));
Collection<Customer> customersWithKnownNamesCollection = customerRepo.findAll(customersWithKnownNames);

customerRepo.remove(myCustomer);

public interface PersistentRepository<T extends Entity> extends Repository<T> {
    String                getRepositoryId();
    PersistenceDefinition getPersistenceDefinition();
    void                  load();
    void                  persist();
    void                  close();
}

PersistentRepository<Customer> customerRepo = new InMemoryAndXStreamXmlFileRepository<Customer>("customers");

customerRepo.load();

Customer myCustomer = new Customer(1L, today);
Customer anotherCustomer = new Customer(2L, threeDaysAgo);
customerRepo.putAll(asList(myCustomer, anotherCustomer));

customerRepo.persist();

customerRepo.close();

public interface PartitionRepository<T extends Entity> extends Repository<T> {
    <V extends T> PartitionRepository<V> addPartitionFor(Specification<V> partitionSpecification);
    <V extends T> PartitionRepository<V> addPartitionFor(Specification<V> partitionSpecification, String repositoryId);
    <V extends T> PartitionRepository<V> addPartitionFor(Specification<V> partitionSpecification, Repository<? extends V> partitionRepository);
    <V extends T> PartitionRepository<V> findPartitionFor(Specification<V> specification);
    <V extends T> Boolean                repartition(V entity);
                  void                   repartition();
}

PartitionRepository<Entity> repo = new InMemoryRepository<Entity>().makePartition();

repo.addPartitionFor(all(Order.class));

Specification<Customer> activeCustomers = all(Customer.class).where("orders", haveSizeOf(moreThan(100)));
...
repo.addPartitionFor(all(Customer.class), new InMemoryAndXStreamXmlFileRepository<Customer>("customers"));
repo.addPartitionFor(activeCustomers, new InMemoryAndXStreamXmlFileRepository<Customer>("active-customers"));

Specification<Pearl> blackPearls = all(Pearl.class).where("colour", is(BLACK));
Specification<Pearl> greyPearls = all(Pearl.class).where("colour", is(GREY));

PartitionRepository<Pearl> pearlRepo = new HashSetRepository<Pearl>().makePartition();
pearlRepo.addPartitionFor(blackPearls);

// insert a lot of pearls...

Collection<Pearl> blackPearlCollection = pearlRepo.findAll(blackPearls);
Collectio<Pearl> greyPearlCollection = pearlRepo.findAll(greyPearls);

PartitionRepository<Entity> repo = new InMemoryRepository<Entity>().makePartition();                                    // INMEMORY
repo.addPartitionFor(all(Configuration.class),         new XStreamXmlFilePerEntityRepository<Configuration>("config")); // FILE
repo.addPartitionFor(all(Customer.class),              new InMemoryAndXStreamXmlFileRepository<Customer>("customers")); // INMEMORY_AND_FILE
repo.addPartitionFor(all(Order.class),                 new InMemoryAndXStreamXmlFileRepository<Order>("orders"));       // INMEMORY_AND_FILE
repo.addPartitionFor(all(OrderProcessingTicket.class), new InMemoryRepository<OrderProcessingTicket>());                // INMEMORY

PersistentRepository<Entity> repo = new InMemoryAndXStreamXmlFileRepository<Entity>("entities");
Customer myCustomer = new Customer(1L, today);
Customer anotherCustomer = new Customer(2L, threeDaysAgo);
repo.putAll(asList(myCustomer, anotherCustomer));
repo.persist();

// migrate
PersistentRepository<Entity> newRepo = new XStreamXmlFilePerEntityRepository<Entity>("migrated_entities");
PartitionRepository migratedRepo = repo.makePartition().addPartitionFor(all(Entity.class), newRepo);

// clean up old repo
repo.remove(all(Entity.class));
repo.persist();