Hibernate.orgCommunity Documentation

Chapter 18. OSGi

Table of Contents

18.1. OSGi Specification and Environment
18.2. hibernate-osgi
18.3. features.xml
18.4. QuickStarts/Demos
18.5. Container-Managed JPA
18.5.1. Enterprise OSGi JPA Container
18.5.2. persistence.xml
18.5.3. DataSource
18.5.4. Bundle Package Imports
18.5.5. Obtaining an EntityManger
18.6. Unmanaged JPA
18.6.1. persistence.xml
18.6.2. Bundle Package Imports
18.6.3. Obtaining an EntityMangerFactory
18.7. Unmanaged Native
18.7.1. Bundle Package Imports
18.7.2. Obtaining an SessionFactory
18.8. Optional Modules
18.9. Extension Points
18.10. 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.

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 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.xml 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.

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

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

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.

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

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.

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.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:

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

  • 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 EMF/SF), rather than attempting to scan all available bundles. This is primarily for versioning considerations, collision protections, 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 work around 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.