Package net.sourceforge.hivetranse.transaction.hibernate3

This is the main package for Hibernate-specific transaction handling under HiveMind.

See:
Description

Interface Summary

SessionFactoryBuilder	Utility interface to build Hibernate SessionFactory.
SessionsRepository	Interface implemented by the object returned by HibernateTransactionService.getCurrentTransaction.

Class Summary

HibernateMappingContribution	Represents a mapping element of a HibernateSettingsSchema.
HibernateTransactionService	Service managing Hibernate sessions & transactions, without JTA.
SessionFactoryBuilderImpl	Utility class to build Hibernate SessionFactory.
SessionFactoryContribution	Represents a configuration parameter to the SessionProxyFactory configured for building a Session service.
SessionProxyFactory	This service creates Proxys to Hibernate Sessions.
SessionsRepositoryImpl	Actual implementation class for SessionsRepository.
SessionsRepositoryImpl.TransactionEntry

Package net.sourceforge.hivetranse.transaction.hibernate3 Description

This is the main package for Hibernate-specific transaction handling under HiveMind.

It implements the TransactionService specifically for Hibernate 3 Sessions.
It also implements the necessary services to directly inject Session into the application services.
The HibernateTransactionService can work with more than one SessionFactory at the same time.

Session

The HibernateTransactionService creates Hibernate3 Sessions from a standard Hibernate SessionFactory that it builds according to configuration passed at construction time of the Session service.
You need to configure one such service (possibly more if you need). This can be done as the example below shows:

        <service-point id="MySession" interface="org.hibernate.Session">
                <invoke-factory      service-id="hivetranse.hibernate3.SessionFactory" model="singleton">
                        <config file="hibernate-config.xml">
                                <property name="hibernate.connection.url" value="jdbc:mysql://localhost/test"/>
                                <property name="hibernate.connection.username" value="root"/>
                                <property name="hibernate.connection.password" value="xxx"/>
                        </config>
                </invoke-factory>
        </service-point>

Please note that, although it may sound strange at first sight, this service must use the singleton service model.
In the previous example, the file hibernate-config.xml contains all Hibernate configuration settings including the references to all mapping files. It is possible, as shown above, to set values for individual Hibernate properties. Any hibernate property is supported. This is useful, in particular, when it is used in conjonction with HiveMind symbol substitution capabilities (through SymbolSources), in order to avoid hard-code, in the Hibernate configuration file, properties that may change on different environments , for instance, the url to the database used (it will differ between integration, acceptance and production environments), along with the password of the user to access it, as shown in the above example.
It is advised to eager-load the Session service through HiveMind EagerLoad configuration point, so that the actual pool of Connections is initialized at startup time, not on first request from services (which may mean on first request of the first user). This can be done with the following declaration in hivemodule.xml:

        <contribution configuration-id="hivemind.EagerLoad">
                <load service-id="MySession"/>
        </contribution>

Such a Session service can then be injected in your services that need it. Those services just need to use the injected Session in a usual way, as if it had been obtained directly from a Hibernate SessionFactory that you had built by yourself, with the exception that the code of your service should never call methods that deal with transactions (this is taken care of by the TransactionService) or close the Session.
It is also possible to define the Hibernate configuration without any xml config file. This is possible to create a configuration point that uses the hivetranse.hibernate3.HibernateSettingsSchema schema, and contribute mappings and properties to this configuration point, as the following example shows:

        <configuration-point id="MyHibernateSettings" occurs="1..n" schema-id="hivetranse.hibernate3.HibernateSettingsSchema"/>
        <contribution configuration-id="MyHibernateSettings">
                <mapping class="example.domain.Address"/>
                <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>
                <property name="hibernate.connection.driver_class" value="com.mysql.jdbc.Driver"/>
                ...
        </contribution>

        <service-point id="MySession" interface="org.hibernate.Session">
                <invoke-factory service-id="hivetranse.hibernate3.SessionFactory" model="singleton">
                        <config configuration-id="MyHibernateSettings">
                                <property name="hibernate.connection.url" value="${db.test.url}"/>
                                <property name="hibernate.connection.username" value="${db.test.user}"/>
                                <property name="hibernate.connection.password" value="${db.test.password}"/>
                        </config>
                </invoke-factory>
        </service-point>

As you can see, it is still possible to define Hibernate properties in two locations: in contributions to the configuration point and also directly in the parameters passed to hivetranse.hibernate3.SessionFactory. In case a same parameter is defined in both locations, then the value for the configuration point is used.
Finally, it is possible to mix all these possibilities, i.e. have an hibernate xml configuration file, provide a configuration point with both properties and mappings, and define properties directly in parameters for hivetranse.hibernate3.SessionFactory.

SessionFactoryBuilder

This service is used internally by HibernateTransactionService to build Hibernate SessionFactorys.
Although the service-point for that service is part of hivetranse.hibernate3 module, the implementation is not. The implementation must be declared in your own application module. The declaration must always be exactly the same as follows:

        <implementation service-id="hivetranse.hibernate3.SessionFactoryBuilder">
                <invoke-factory      model="primitive">
                        <construct class="net.sourceforge.hivetranse.transaction.hibernate3.SessionFactoryBuilderImpl">
                                <log/>
                        </construct>
                </invoke-factory>
        </implementation>

Why is this implementation not directly declared in hivetranse.hibernate3 module configuration file? This is for technical reasons: implementation had to be parted from the module declaration in order to perform better unit testing of the hivetranse.hibernate3 module.
This inconvenience may be removed some day when a better way to handle this "testing" issue is found.

Multiple SessionFactories

Although the HibernateTransactionService is not based on JTA, it is still possible to define more than one SessionFactory, hence more than one Session service (each built from a different Sessionfactory, ie pointing to a different database).
However, since the resulting transactions are not enroled in a JTA transaction, such a usage is not considered safe in the sense that it is possible that one Session has its transaction committed while another one has its transaction rolled back.
In more detail, the HibernateTransactionService will try to commit (or rollback) all the Sessions transactions at the same time, but if one commit (or rollback) fails after the previous one has succeeded, then the resulting state of all databases will probably be inconsistent.
If your application can live with that, then you can feel free to use multiple SessionFactories with HibernateTransactionService.