Hibernate.orgCommunity Documentation

Chapter 17. OSGi

Table of Contents

17.1. OSGi Specification and Environment
17.2. hibernate-osgi
17.3. Container-Managed JPA
17.3.1. Client bundle imports
17.3.2. JPA 2.1
17.3.3. DataSource
17.3.4. Bundle Ordering
17.3.5. Obtaining an EntityManger
17.4. Unmanaged JPA
17.4.1. Client bundle imports
17.4.2. Bundle Ordering
17.4.3. Obtaining an EntityMangerFactory
17.5. Unmanaged Native
17.5.1. Client bundle imports
17.5.2. Bundle Ordering
17.5.3. Obtaining an SessionFactory
17.6. Optional Modules
17.7. Extension Points
17.8. Caveats

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.

Rather than embed OSGi capabilities into hibernate-core, hibernate-entitymanager, 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 CL with core and entitymanager CLs), JPA persistence provider, SF/EMF bootstrapping, entities/mappings scanner, and service management.

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

Quickstart tutorial project, demonstrating a container-managed JPA client bundle: managed-jpa

Hibernate also supports the use of JPA through hibernate-entitymanager, unmanaged by the OSGi container. The client bundle is responsible for managing the EntityManagerFactory and EntityManagers.

Quickstart tutorial project, demonstrating an unmanaged JPA client bundle: unmanaged-jpa

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

Quickstart tutorial project, demonstrating an unmanaged native client bundle: unmanaged-native

The unmanaged-native QuickStart project demonstrates the use of optional Hibernate modules. Each module adds additional dependency bundles that must first be activated (see features.xml). 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.

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 EMF/SF 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.metamodel.spi.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:

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