In-memory repositories

The simplest implementations of the repository interface are part of the in-memory repository family that put their content in Java collections.

Such implementations seem useless as its content is not persisted in any way. But this is not true. Each implementation was developed for a specific use in mind.

The main purpose of MemoryRepository is testing. If a class under test needs a repository, you can create an instance of MemoryRepository and initialize it with testing data. So you will not need to access the real data store to test your class. This is very important especially for complex model classes where you have to concentrate yourself in testing the business logic.

CollectionRepository, instead, was developed as an adapter to present an existing collection with the repository interface.

Suppose you have a class (like the ApplicATE ListBrowser) that takes a repository. If you want to pass a collection to it you need and adapter, so create a CollectionRepository passing the collection to its constructor.

A similar purpose has the EmptyRepository. As its name suggest it is a repository without content. If a class needs a repository but you have no content to be accessed you can pass an EmptyRepository to it.

Hibernate repositories

As their name suggests Hibernate repositories are used to access entities that are persisted on a relational database using Hibernate.

There are two implementations:

• ClassHibernateRepository
• CollectionHibernateRepository

ClassHibernate repository is the most important of the two. It gives you access to all the entities of a specified class. The class must be passed to the repository constructor:

Repository<Long,MyEntity> rep = new ClassHibernateRepository<Long,MyEntity>(MyEntity.class);

The repository will use the Hibernate Session interface to do its work.

CollectionHibernateRepository, instead, is a wrapper around a persistent collection and use Hibernate filter to query against this collection:

MyEntity e = rep.get(1L);
Repository<Long,YourEntity> collRep = new CollectionHibernateRepository<Long,YourEntity>(e.getYourCollection());

The main difficulty in using Hibernate repositories is understanding how they retrieve the Hibernate session they need to perform their job.

The repositories get their sessions using a HibernateSessionManager, a class that manage the life-cycle of a session. There are two possible life-cycles:

• Thread local
• Long running

The life-cycle must be specified in the constructor of the session manager.

The first time the getSession() method will be called a new session is created. In each subsequent call to getSession() in the same thread, the same session will be returned.

The difference between the two life-cycles is in session destruction. When the static disconnectAll() method is called a loop on all the open sessions will be performed but, while thread-local sessions are closed, long-running sessions are simply disconnected.

In this way long-running sessions can be re-opened when the getSession() method is called again on the same session manager while thread local sessions, being completely closed, need to be recreated.

To completely close a long-running session you can use the release() method.

Consider the following typical use case:

HibernateSessionManager sMgr = new HibernateSessionManager(.......);
Session s = sMgr.getSession();
/* Use the session here */
HibernateSessionManager.disconnectAll();

Session s = sMgr.getSession();
/* Use the session here */
HibernateSessionManager.disconnectAll();

sMgr.release();

If, in the first row, LONG_RUNNING is passed to the constructor, the two blocks will use the same session. If, otherwise, THREAD_LOCAL is used, the two blocks will use different sessions.

A session manager should not be used after it has been released.

Repositories don't create session managers by their own, instead they retrieve them from a SessionManagerRegistry, a singleton that manage a stack of session managers for each thread.

Calling currentSessionManager() on the registry will retrieve the session manager on the top of the stack. If the stack is empty a new session manager with thread-local life-cycle is created.

You can put a session manager on the stack using the useSessionManager() method and with releaseSessionManager() the session manager on the top of the stack is removed.

So to use a Hibernate repository with a thread local life-cycle session you can simply do the following:

Repository<Long,MyEntity> rep = new ClassHibernateRepository<Long,MyEntity>(MyEntity.class);
/* use the repository here */
HibernateSessionManager.disconnectAll();

while for long running sessions

HibernateSessionManager sMgr = new HibernateSessionManager(LONG_RUNNING);

Repository<Long,MyEntity> rep = new ClassHibernateRepository<Long,MyEntity>(MyEntity.class);
SessionManagerRegistry.useSessionManager(sMgr);
/* use the repository here */
SessionManagerRegistry.releaseSessionManager();
HibernateSessionManager.disconnectAll();

SessionManagerRegistry.useSessionManager(sMgr);
/* use the repository here */
SessionManagerRegistry.releaseSessionManager();
HibernateSessionManager.disconnectAll();

sMgr.release();

Developing a custom repository

Bridged repositories

In certain cases you need to extend your repository and add new methods. This is true mainly for specialized query methods that could add expressivity to the code. For example to a Person repository you would add a findByFirstName() method.

Typically these methods can be constructed using basic methods from the repository interface. For example the previously mentioned findByFirstName() query method can be implemented using a specification and the list() method.

But to do this you need to extend a concrete repository like ClassHibernateRepository. And if you need two of these repositories (for example, one hibernate repository for production and one memory repository for test purposes) you need to create two classes replicating these methods. The result can be similar to the following:

This is problematic for various reasons. Not least a clear violation of the DRY (Don't Repeat Yourself) principle.

A better solution involves the use of the Bridge pattern like in this article.

To simplify the implementation of this pattern you can use the AbstractRepositoryBridge class. Implement you repository extending this class. You can add your methods and call the other Repository methods in them.

Then, when you instantiate your repository, you can pass the base repository to the constructor. The AbstractRepositoryBridge class will delegate to this base repository.

So, in our person repository example, we can do something like:

public class PersonRepository extends AbstractRepositoryBridge<Long,Person> {

        public PersonRepository(Repository<Long,Person> bridged) {
        super(bridged);
        }
        
        public List<Person> findByFirstName(String firstName) {
        PersonSpecification spec = new StringSpecification<Person>("firstName");
        spec.setValue(firstName);
        spec.setComparisonType(ComparisonType.EXACT);
        return list(spec);
        }

}

and the, when we need a person repository, we can do

  PersonRepository rep = new PersonRepository(new ClassHibernateRepository(Person.class));

if we need an Hibernate based repository, or

  PersonRepository rep = new PersonRepository(new MemoryRepository());

if we need an in-memory repository.

This can be done in repository factory, like described in the following chapter.

Repository factories and the repository registry

The best way to retrieve a repository for the entities of a given class is using the RepositoryRegistry singleton:

  Repository<Long,MyEntity> r = RepositoryRegistry.instance().getRepository(MyEntity.class);

But before using it you have to set the repository factory class that the registry will use to create repositories instances:

  RepositoryRegistry.instance().setRepositoryFactoryClass(MyRepositoryFactory.class);

This class must implement RepositoryFactory, an interface with a two methods:

• one that create a repository given the entity class
• one that create a collection repository given the collection to be adapted

Instead of implementing this interface you can extend AbstractRepositoryFactory. This class has a default implementation for the class repository factory method. It tries to find a custom factory method, if it doesn't find this method it will call getDefaultRepository(), an abstract method that you have to implement. The custom factory method for a repository of class MyClass must be called getMyClassRepository().

For example, if you want to customize the way the repository for class MyEntity is instantiated you can do the following:

public class MyRepositoryFactory extends HibernateRepositoryFactory {

    public Repository<Long, MyEntity> getMyEntityRepository() {
        MyRepository<Long, MyEntity> r = new MyRepository<Long, MyEntity>();
        return r;
    }
    
    public <I extends Serializable,T extends Entity<I>> Repository<I, T> getDefaultRepository(Class<T> c) {
        // create and return the default repository
    }
    
    public <I extends Serializable,T extends Entity<I>> Repository<I, T> getRepository(Collection<T> c) {
        // create and return the collection repository
    }

}

For Hibernate repositories exists HibernateRepositoryFactory that return a standard ClassHibernateRepository if the given entity class is mapped with Hibernate, otherwise it returns null.

HibernateRepositoryFactory extends AbstractRepositoryFactory so you can customize the way a repository is created implementing a custom factory method.

For example, if you want to customize the way the repository for class MyEntity is instantiated you can do the following:

public class MyRepositoryFactory extends HibernateRepositoryFactory {

    public Repository<Long, MyEntity> getMyEntityRepository() {
        ClassHibernateRepository<Long, MyEntity> r = new ClassHibernateRepository<Long, MyEntity>();
        // do here all your repository customization
        return r;
    }

}

Now, if you do:

  RepositoryRegistry.instance().setRepositoryFactoryClass(MyRepositoryFactory.class);
  
  Repository<Long, MyEntity> rep = RepositoryRegistry.instance().getRepository(MyEntity.class); 

you will get your customized repository.

Existing specifications

DominATE provides a set of specification classes that can be used in most common cases. For example an instance of StringSpecification can be used to check if a string property of an object is similar to a given string.

 StringSpecification<Person> s = StringSpecification.newInstance("firstName");
 s.setValue("John");
 if (s.isSatisfiedBy(person)) {
     ..........................
 }

All the provided specifications supports both memory and hibernate repositories. To ensure this compatibility you always need to create them using the newInstance() static factory method.

 StringSpecification<Person> s = StringSpecification.newInstance("firstName");
 s.setValue("John");
 if (s.isSatisfiedBy(person)) {
     ..........................
 }

 StringSpecification<Person> s = StringSpecification.newInstance("firstName");
 s.setValue("John");
 s.setComparisonType(ComparisonType.EXACT);
 if (s.isSatisfiedBy(person)) {
     ..........................
 }

 LongSpecification<Person> s = LongSpecification.newInstance("age");
 s.setValue(30L);
 if (s.isSatisfiedBy(person)) {
     ..........................
 }

Developing a custom specification

Why may you need a custom specification? There are two main reasons:

• You need to repeatedly apply a condition more complex than what you can accomplish with the provided ones.
• You developed a custom repository and you want to use specifications with it

  We saw in the previous chapter that the first point can be accomplished using a specification composite. But creating every time a new composite from scratch can be boring and really error prone. To solve this problem we can create a custom specification.

  So the first/last name example of the previous chapter can be rewritten like this:

  public class PersonSpecification extends ConjunctionSpecification<Person> {
      private StringSpecification<Person> firstNameSpec = StringSpecification.newInstance("firstName");
      private StringSpecification<Person> lastNameSpec = StringSpecification.newInstance("lastName");
      
      public PersonSpecification() {
          addSpecification(firstNameSpec);
          addSpecification(lastNameSpec);
      }
      
      public String getFirstName() {
          return firstNameSpec.getValue();
      }
      
      public void setFirstName(String value) {
          firstNameSpec.setValue(value);
      }
      
      public String getLastName() {
          return lastNameSpec.getValue();
      }
      
      public void setLastName(String value) {
          lastNameSpec.setValue(value);
      }
  }

  In this way we completely encapsulated the string specifications so the users of our PersonSpecification only have to set the first/last name and check it as any other specification.

Validator

Validator is an interface with four methods: two are used to perform validation while the other two are used to retrieve validation meta-data.

A Validator implementation should be constructed passing in the object to be validated.

    Validator v = new DefaultValidator(myObject);
    ValidationResult vr = v.validateProperty("myProperty", newValue);
    if (vr.getType().equals(ValidationResult.ResultType.VALID)) {
        myObject.setMyProperty(newValue);
    }
    

    public void setMyProperty(String newValue) {
        Validator v = new DefaultValidator(this);
        ValidationResult vr = v.validateProperty("myProperty", newValue);
        if (!vr.getType().equals(ValidationResult.ResultType.VALID)) {
            throw new InvalidArgumentException();
        }
        this.myProperty = newValue;
    }

    ValidationResult vr = v.validateProperty("myProperty", myObject.getMyProperty());

Validation using Hibernate Validator

Using Hibernate Validator is surely the simplest way to attach validation constraints to an object. At this moment only the legacy Hibernate Validator is supported (Version 3.x.x). Version 4 with JSR 303 support will be included when it will be GA.

With Hibernate Validator constraints are attached to objects using annotations. In the following example

    public class Person {
        private String name;
        private String surname;
        
        @NotNull
        @Length(max=20)
        public String getName() {
            return name;
        }
        
        public void setName(String name) {
            this.name = name;
        }
        
        @NotNull
        @Length(max=20)
        public String getSurname() {
            return surname;
        }
        
        public void setSurname(String surname) {
            this.surname = surname;
        }
    }

the "name" and "surname" properties of the person class are constrained to be both not-null and with maximum length of 20 characters.

Check Hibernate Validator site for details about available annotations and on how to define your own constraint annotations.

Validation using validation methods