Build a Hibernate Store

This guide uses an example where you will create a Hibernate store for an object called Person. A store is a class that performs CRUD operations (create-retrieve-update-delete) on an object. We stronly suggest you have a look at the existing store implementations, eg. DataElementStore/HibernateDataElementStore, which can be found in the dhis-api and dhis-service-core projects respectively.

The interface

Create an interface called PersonStore. The interface should be placed in the dhis-api project in a package called org.hisp.dhis.person. Include methods for CRUD operations. A typical set of methods would be:

public interface PersonStore
{
	int addPerson( Person person );
	Person getPerson( int id );
	void updatePerson( Person person );
	void deletePerson( Person person );
 	Person getPersonByName( String name );
	Collection<Person> getAllPersons();
}

The implementation

Create an implementation called HibernatePersonStore which should implement the newly created interface. Remember to install the dhis-api project with Maven to access the interface. Put the implementation in a separate project called dhis-service-person or in the dhis-service-core project, in a package called org.hisp.dhis.person.hibernate. The implementation should utilize the SessionManager, which can be accessed by putting the dhis-support-hibernate project on the classpath (add dependency in Maven's pom.xml file). The SessionManager will give you access to the current HibernateSession, which can be used to perform persistence operations on your objects. A typical implemenation would look like:

public class HibernatePersonStore
	implements PersonStore
{
	private SessionManager sessionManager;

	public void setSessionManager( SessionManager sessionManager )
	{
		this.sessionManager = sessionManager;
	}

	public void addPerson( Person person )
	{
		Session session = sessionManager.getCurrentSession();

		session.add( Person person );
	}

	public Person getPerson( int id )
	{
		Session session = sessionManager.getCurrentSession();

		return (Person) session.get( Person.class, id );
	}

	// Other methods from interface, have a look at eg. HibernateDataElementStore for hints
}

Spring bean mapping

The store will have to be mapped as a bean and injected with dependencies in Spring. Spring's configuration file is called beans.xml and can be found / located in src/main/resources/META-INF/dhis in your project. A mapping for the HibernatePersonStore can look like this, note that we use the fully qualified package name for the interface as bean identifier in order to ensure uniqueness:

<bean id="org.hisp.dhis.person.PersonStore"
	class="org.hisp.dhis.person.hibernate.HibernatePersonStore">
	<property name="sessionManager"
		ref="org.hisp.dhis.hibernate.HibernateSessionManager"/>
</bean>

Transaction management mapping

DHIS 2 applies transaction management to persistence operations through Spring AOP mappings. The mappings should be put in the beans.xml and are separated in read-only transactions (get-methods) and read-write operations (add, update, delete-methods). If you add your store to dhis-service-core you should append your mappings to the existing element. A typical mapping looks like this:

<!-- Read-only -->

<bean class="org.springframework.aop.support.RegexpMethodPointcutAdvisor">
	<property name="advice" ref="readOnlyTransactionInterceptor"/>
	<property name="patterns">
		<list>
			<value>.*\.DataElementStore\.get.*</value>
			<value>.*\.PeriodStore\.get.*</value>
		</list>
	</property>
</bean>

<!-- Read-write -->

<bean class="org.springframework.aop.support.RegexpMethodPointcutAdvisor">
	<property name="advice" ref="readWriteTransactionInterceptor"/>
	<property name="patterns">
		<list>
			<value>.*\.DataElementStore\.add.*</value>
			<value>.*\.DataElementStore\.update.*</value>
			<value>.*\.DataElementStore\.delete.*</value>
			<value>.*\.PeriodStore\.add.*</value>
			<value>.*\.PeriodStore\.update.*</value>
			<value>.*\.PeriodStore\.delete.*</value>
		</list>
	</property>
</bean>

That should be it. In the DHIS 2 architecture a service layer will typically be put on top the store. Have a look at eg. the DefaultDataElementService in the dhis-service-core for hints.