Rough outline for Hibernate OSGi developer docs

Hibernate OSGi developer docs outline

- intro/"abstract"
	- why OSGi is necessary
	- unique challenges (especially CL)



- OSGi specification and environment
	- targetting OSGi 4.3+
	- support standard OSGi with unmanaged JPA and native Hibernate
	- support Enterprise OSGi with container-managed JPA



- hibernate-osgi
	- purposefully separate module (OSGi dependency isolation, mainly)
	- provides OSGi-specific CL, persistence provider, bootstrapping, and services



- container-managed JPA
	- intro
		- Enterprise OSGi JPA
		- container creates 1 EMF per PU
		- container handles the EMF/PU on its own
	- client bundle compile dependencies: only the typical JPA and OSGi libs
	- client bundle imports: JPA, javassist, o.h.proxy
	- [link to quickstart features.xml]
	- typically have a datasource installed in the container, then persistence.xml with a JNDI reference to the datasource
	- blueprint.xml
		- easiest way to get a container-managed EM
		- uses a service impl bean and its EM attribute
		- <jpa:context...> automatically pushes EM into the service bean attribute (like CDI)
		- [link to quickstart blueprint.xml]



- unmanaged JPA
	- intro
		- plain OSGi
		- app-managed EMF/EM
	- client bundle compile dependencies: JPA, hibernate-entitymanager, and OSGi libs
	- client bundle imports: JPA, javassist, o.h.proxy, hibernate-entitymanager
	- [link to quickstart features.xml]
	- simply use a typical persistence.xml
	- hibernate-osgi registers a PersistenceProvider as an OSGi service -- discover and use to create the EMF [add code snippet]
	- *do not* manually create the PersistenceProvider/EMF without the OSGi service -- service is necessary for ClassLoader issues and OSGi-specific bootstrapping



- native Hibernate
	- intro
		- plain OSGi
		- app-managed SF/S
	- client bundle compile dependencies: hibernate-core and OSGi libs
	- client bundle imports: javassist, o.h.proxy, hibernate-core
	- [link to quickstart features.xml]
	- simply use a typical hibernate.cfg.xml
	- hibernate-osgi registers a SessionFactory as an OSGi service -- discover and use to create the S [add code snippet]
	- *do not* manually create the SF without the OSGi service -- service is necessary for ClassLoader issues and OSGi-specific bootstrapping



- optional modules
	- (4.2+) envers fully supported
	- (4.3+) c3p0, proxool, ehcache, and infinispan are plugged into ORM using OSGi services, however do not work due to CL issues with the 3rd party libs



- extension points
	- non-OSGi environments typically use JDK services for integrating with ORM extension points
	- replaced by OSGi services ("whiteboard pattern")
	- register and use in any of the 3 environments
	- hibernate-osgi discovers all registered extension points using OSGi services -- integrates during EMF/SF bootstrapping
	- (4.2+) Integrator (explain)
	- (4.3+) StrategyRegistrationProvider (explain)
	- (4.3+) TypeContributor (explain)
	- (4.2+) JTA's TransactionManager and UserTransaction, but typically provided and registered by the OSGi container



- caveats
	- cannot currently support multiple PUs correctly, but it *might* partially work -- 1 OSGi ClassLoader is currently used per instance of Hibernate, due to heavy use of static TCCL utilities
	- multiple PU support (one ClassLoader per PU) will hopefully be available in Hibernate 5
	- Scanner is supported in OSGi to find non-explicitly listed entities and mappings, but they *must* be in your client/persistence bundle
	- more specifically, the ClassLoader only has the OSGi container, hibernate-core, hibernate-entitymanager, hibernate-osgi, and the "requesting bundle" (your client/persistence bundle)
	- mainly integrated and tested with Karaf and Aries -- needs additional testing with Gemini, Equniox, etc.
	- if explicitly giving a PersistenceProvider in persistence.xml, use the original HibernatePersistence -- the OSGi-specific provider is registered using the original name in order to support PU reusability
	- ORM has many 3rd party dependencies that do not currently support OSGi manifests -- heavy use of "wrap:"
	- bundles are fairly order specific:
		1.) 3rd party dependencies
		2.) hibernate-core
		3.) hibernate-entitymanager (if JPA)
		4.) optional modules (envers, etc.)
		5.) hibernate-osgi
		6.) client/persistence bundle
	- the environment should be considered mostly static -- the ability to dynamically add/remove modules and client bundles is not yet supported