20. OSGi

20.1. OSGi Specification and Environment

Hibernate targets the OSGi 4.3 spec or later. It was necessary to start with 4.3, over 4.2, due to our dependency on OSGi’s BundleWiring for entity/mapping scanning.

Hibernate supports three types of configurations within OSGi.

  1. Container-Managed JPA Container-Managed JPA

  2. Unmanaged JPA Unmanaged JPA

  3. Unmanaged Native Unmanaged Native

20.2. hibernate-osgi

Rather than embedding OSGi capabilities into hibernate-core, and sub-modules, hibernate-osgi was created. It’s purposefully separated, isolating all OSGi dependencies. It provides an OSGi-specific ClassLoader (aggregates the container’s ClassLoader with core and EntityManager ClassLoaders), JPA persistence provider, SessionFactory/EntityManagerFactory bootstrapping, entities/mappings scanner, and service management.

20.3. features.xml

Apache Karaf environments tend to make heavy use of its “features” concept, where a feature is a set of order-specific bundles focused on a concise capability. These features are typically defined in a features.xml file. Hibernate produces and releases its own features.xml that defines a core hibernate-orm, as well as additional features for optional functionality (caching, Envers, etc.). This is included in the binary distribution, as well as deployed to the JBoss Nexus repository (using the org.hibernate groupId and hibernate-osgi artifactId with the karaf.xml classifier).

Note that our features are versioned using the same ORM artifact versions they wrap. Also, note that the features are heavily tested against Karaf 3.0.3 as a part of our PaxExam-based integration tests. However, they’ll likely work on other versions as well.

hibernate-osgi, theoretically, supports a variety of OSGi containers, such as Equinox. In that case, please use features.xm as a reference for necessary bundles to activate and their correct ordering. However, note that Karaf starts a number of bundles automatically, several of which would need to be installed manually on alternatives.

20.4. QuickStarts/Demos

All three configurations have a QuickStart/Demo available in the hibernate-demos project:

20.5. Container-Managed JPA

The Enterprise OSGi specification includes container-managed JPA. The container is responsible for discovering persistence units in bundles and automatically creating the EntityManagerFactory (one EntityManagerFactory per PersistenceUnit). It uses the JPA provider (hibernate-osgi) that has registered itself with the OSGi PersistenceProvider service.

20.6. Enterprise OSGi JPA Container

In order to utilize container-managed JPA, an Enterprise OSGi JPA container must be active in the runtime. In Karaf, this means Aries JPA, which is included out-of-the-box (simply activate the jpa and transaction features). Originally, we intended to include those dependencies within our own features.xml. However, after guidance from the Karaf and Aries teams, it was pulled out. This allows Hibernate OSGi to be portable and not be directly tied to Aries versions, instead of having the user choose which to use.

That being said, the QuickStart/Demo projects include a sample features.xml showing which features need to be activated in Karaf in order to support this environment. As mentioned, use this purely as a reference!

20.7. persistence.xml

Similar to any other JPA setup, your bundle must include a persistence.xml file. This is typically located in META-INF.

20.8. DataSource

Typical Enterprise OSGi JPA usage includes a DataSource installed in the container. Your bundle’s persistence.xml calls out the DataSource through JNDI. For example, you could install the following H2 DataSource. You can deploy the DataSource manually (Karaf has a deploy dir), or through a “blueprint bundle” (blueprint:file:/[PATH]/datasource-h2.xml).

Example 646. datasource-h2.xml

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3. First install the H2 driver using:
  4. > install -s mvn:com.h2database/h2/1.3.163
  6. Then copy this file to the deploy folder
  7. -->
  8. <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  10.     <bean id="dataSource" class="org.h2.jdbcx.JdbcDataSource">
  11.         <property name="URL" value="jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE"/>
  12.         <property name="user" value="sa"/>
  13.         <property name="password" value=""/>
  14.     </bean>
  16.     <service interface="javax.sql.DataSource" ref="dataSource">
  17.         <service-properties>
  18.             <entry key="osgi.jndi.service.name" value="jdbc/h2ds"/>
  19.         </service-properties>
  20.     </service>
  21. </blueprint>

That DataSource is then used by your persistence.xml persistence-unit. The following works in Karaf, but the names may need tweaked in alternative containers.

Example 647. META-INF/persistence.xml

  1. <jta-data-source>osgi:service/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/h2ds)</jta-data-source>

20.9. Bundle Package Imports

Your bundle’s manifest will need to import, at a minimum:

  • javax.persistence

  • org.hibernate.proxy and javassist.util.proxy, due to Hibernate’s ability to return proxies for lazy initialization (Javassist enhancement occurs on the entity’s ClassLoader during runtime).

20.10. Obtaining an EntityManger

The easiest, and most supported, method of obtaining an EntityManager utilizes OSGi’s OSGI-INF/blueprint/blueprint.xml in your bundle. The container takes the name of your persistence unit, then automatically injects an EntityManager instance into your given bean attribute.

Example 648. OSGI-INF/blueprint/blueprint.xml

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <blueprint xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"
  3.            xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"
  4.            default-activation="eager"
  5.            xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  7.     <!-- This gets the container-managed EntityManager and injects it into the DataPointServiceImpl bean.
  8.     Assumes DataPointServiceImpl has an "entityManager" field with a getter and setter. -->
  9.     <bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl">
  10.         <jpa:context unitname="managed-jpa" property="entityManager"/>
  11.         <tx:transaction method="*" value="Required"/>
  12.     </bean>
  14.     <service ref="dpService" interface="org.hibernate.osgitest.DataPointService"/>
  16. </blueprint>

20.11. Unmanaged JPA

Hibernate also supports the use of JPA, unmanaged by the OSGi container. The client bundle is responsible for managing the EntityManagerFactory and `EntityManager`s.

20.12. persistence.xml

Similar to any other JPA setup, your bundle must include a persistence.xml file. This is typically located in META-INF.

20.13. Bundle Package Imports

Your bundle’s manifest will need to import, at a minimum:

  • javax.persistence

  • org.hibernate.proxy and javassist.util.proxy, due to Hibernate’s ability to return proxies for lazy initialization (Javassist enhancement occurs on the entity’s ClassLoader during runtime)

  • JDBC driver package (example: org.h2)

  • org.osgi.framework, necessary to discover the EntityManagerFactory (described below)

20.14. Obtaining an EntityMangerFactory

hibernate-osgi registers an OSGi service, using the JPA PersistenceProvider interface name, that bootstraps and creates an EntityManagerFactory specific for OSGi environments.

It is VITAL that your EntityManagerFactory be obtained through the service, rather than creating it manually. The service handles the OSGi ClassLoader, discovered extension points, scanning, etc. Manually creating an EntityManagerFactory is guaranteed to NOT work during runtime!

Example 649. Discover/Use EntityManagerFactory

  1. public class HibernateUtil {
  3.     private EntityManagerFactory emf;
  5.     public EntityManager getEntityManager() {
  6.         return getEntityManagerFactory().createEntityManager();
  7.     }
  9.     private EntityManagerFactory getEntityManagerFactory() {
  10.         if ( emf == null ) {
  11.             Bundle thisBundle = FrameworkUtil.getBundle(
  12.                 HibernateUtil.class
  13.             );
  14.             BundleContext context = thisBundle.getBundleContext();
  16.             ServiceReference serviceReference = context.getServiceReference(
  17.                 PersistenceProvider.class.getName()
  18.             );
  19.             PersistenceProvider persistenceProvider = ( PersistenceProvider ) context
  20.             .getService(
  21.                 serviceReference
  22.             );
  24.             emf = persistenceProvider.createEntityManagerFactory(
  25.                 "YourPersistenceUnitName",
  26.                 null
  27.             );
  28.         }
  29.         return emf;
  30.     }
  31. }

20.15. Unmanaged Native

Native Hibernate use is also supported. The client bundle is responsible for managing the SessionFactory and Sessions.

20.16. Bundle Package Imports

Your bundle’s manifest will need to import, at a minimum:

  • javax.persistence

  • org.hibernate.proxy and javassist.util.proxy, due to Hibernate’s ability to return proxies for lazy initialization (Javassist enhancement occurs on the entity’s ClassLoader during runtime)

  • JDBC driver package (example: org.h2)

  • org.osgi.framework, necessary to discover the SessionFactory (described below)

  • org.hibernate.* packages, as necessary (ex: cfg, criterion, service, etc.)

20.17. Obtaining a SessionFactory

hibernate-osgi registers an OSGi service, using the SessionFactory interface name, that bootstraps and creates a SessionFactory specific for OSGi environments.

It is VITAL that your SessionFactory be obtained through the service, rather than creating it manually. The service handles the OSGi ClassLoader, discovered extension points, scanning, etc. Manually creating a SessionFactory is guaranteed to NOT work during runtime!

Example 650. Discover/Use SessionFactory

  1. public class HibernateUtil {
  3.     private SessionFactory sf;
  5.     public Session getSession() {
  6.         return getSessionFactory().openSession();
  7.     }
  9.     private SessionFactory getSessionFactory() {
  10.         if ( sf == null ) {
  11.             Bundle thisBundle = FrameworkUtil.getBundle(
  12.                 HibernateUtil.class
  13.             );
  14.             BundleContext context = thisBundle.getBundleContext();
  16.             ServiceReference sr = context.getServiceReference(
  17.                 SessionFactory.class.getName()
  18.             );
  19.             sf = ( SessionFactory ) context.getService( sr );
  20.         }
  21.         return sf;
  22.     }
  23. }

20.18. Optional Modules

The unmanaged-native demo project displays the use of optional Hibernate modules. Each module adds additional dependency bundles that must first be activated, either manually or through an additional feature. As of ORM 4.2, Envers is fully supported. Support for C3P0, Proxool, EhCache, and Infinispan were added in 4.3. However, none of their 3rd party libraries currently work in OSGi (lots of ClassLoader problems, etc.). We’re tracking the issues in JIRA.

20.19. Extension Points

Multiple contracts exist to allow applications to integrate with and extend Hibernate capabilities. Most apps utilize JDK services to provide their implementations. hibernate-osgi supports the same extensions through OSGi services. Implement and register them in any of the three configurations. hibernate-osgi will discover and integrate them during EntityManagerFactory/SessionFactory bootstrapping. Supported extension points are as follows. The specified interface should be used during service registration.

org.hibernate.integrator.spi.Integrator

(as of 4.2)

org.hibernate.boot.registry.selector.StrategyRegistrationProvider

(as of 4.3)

org.hibernate.boot.model.TypeContributor

(as of 4.3)

JTA’s

javax.transaction.TransactionManager and javax.transaction.UserTransaction (as of 4.2). However, these are typically provided by the OSGi container.

The easiest way to register extension point implementations is through a blueprint.xml file. Add OSGI-INF/blueprint/blueprint.xml to your classpath. Envers’ blueprint is a great example:

Example 651. Example extension point registrations in blueprint.xml

  1. <!--
  2.   ~ Hibernate, Relational Persistence for Idiomatic Java
  3.   ~
  4.   ~ License: GNU Lesser General Public License (LGPL), version 2.1 or later.
  5.   ~ See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  6.   -->
  7. <blueprint default-activation="eager"
  8.            xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  10.     <bean id="integrator" class="org.hibernate.envers.boot.internal.EnversIntegrator"/>
  11.     <service ref="integrator" interface="org.hibernate.integrator.spi.Integrator"/>
  13.     <bean id="typeContributor"
  14.           class="org.hibernate.envers.boot.internal.TypeContributorImpl"/>
  15.     <service ref="typeContributor" interface="org.hibernate.boot.model.TypeContributor"/>
  17. </blueprint>

Extension points can also be registered programmatically with BundleContext#registerService, typically within your BundleActivator#start.

20.20. Caveats

  • Technically, multiple persistence units are supported by Enterprise OSGi JPA and unmanaged Hibernate JPA use. However, we cannot currently support this in OSGi. In Hibernate 4, only one instance of the OSGi-specific ClassLoader is used per Hibernate bundle, mainly due to heavy use of static TCCL utilities. We hope to support one OSGi ClassLoader per persistence unit in Hibernate 5.

  • Scanning is supported to find non-explicitly listed entities and mappings. However, they MUST be in the same bundle as your persistence unit (fairly typical anyway). Our OSGi ClassLoader only considers the “requesting bundle” (hence the requirement on using services to create EntityManagerFactory/SessionFactory), rather than attempting to scan all available bundles. This is primarily for versioning considerations, collision protection, etc.

  • Some containers (ex: Aries) always return true for PersistenceUnitInfo#excludeUnlistedClasses, even if your persistence.xml explicitly has exclude-unlisted-classes set to false. They claim it’s to protect JPA providers from having to implement scanning (“we handle it for you”), even though we still want to support it in many cases. The workaround is to set hibernate.archive.autodetection to, for example, hbm,class. This tells hibernate to ignore the excludeUnlistedClasses value and scan for *.hbm.xml and entities regardless.

  • Scanning does not currently support annotated packages on package-info.java.

  • Currently, Hibernate OSGi is primarily tested using Apache Karaf and Apache Aries JPA. Additional testing is needed with Equinox, Gemini, and other container providers.

  • Hibernate ORM has many dependencies that do not currently provide OSGi manifests. The QuickStart tutorials make heavy use of 3rd party bundles (SpringSource, ServiceMix) or the wrap:…​ operator.