HHH-8112 quickstart tutorial chapter

This commit is contained in:
Brett Meyer 2013-05-22 16:28:15 -04:00
parent ab11440331
commit adcd61f0e1
6 changed files with 138 additions and 5 deletions

View File

@ -31,6 +31,12 @@
<surname>Warski</surname> <surname>Warski</surname>
</personname> </personname>
</author> </author>
<author>
<personname>
<firstname>Brett</firstname>
<surname>Meyer</surname>
</personname>
</author>
<othercredit> <othercredit>
<personname> <personname>

View File

@ -43,5 +43,6 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_annotations.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_annotations.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_jpa.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_jpa.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_envers.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_envers.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_osgi.xml" />
</book> </book>

View File

@ -0,0 +1,104 @@
<?xml version='1.0' encoding='UTF-8' ?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>OSGi Tutorial</title>
<para>
Hibernate targets the OSGi 4.3 spec or later and supports three types
of configurations.
<orderedlist>
<listitem>
<link xl:href="https://github.com/hibernate/hibernate-orm/tree/master/documentation/src/main/docbook/quickstart/tutorials/osgi/managed-jpa">Container-Managed JPA</link>
</listitem>
<listitem>
<link xl:href="https://github.com/hibernate/hibernate-orm/tree/master/documentation/src/main/docbook/quickstart/tutorials/osgi/unmanaged-jpa">Unmanaged JPA</link>
</listitem>
<listitem>
<link xl:href="https://github.com/hibernate/hibernate-orm/tree/master/documentation/src/main/docbook/quickstart/tutorials/osgi/unmanaged-native">Unmanaged Native</link>
</listitem>
</orderedlist>
</para>
<para>
For more details about OSGi, the three configurations, hibernate-osgi, extensions points, and caveats, please
see the OSGi chapter of the Developer's Guide!
</para>
<section>
<title>
Project Overview
</title>
<para>
Each configuration has a QuickStart project located within the download bundle (under <filename>osgi</filename>).
The bundles can be used as-is within Apache Karaf. Feel free to use them as literal
"quick start" bundle templates.
</para>
</section>
<section>
<title>
Project Structure
</title>
<itemizedlist>
<listitem>
<filename>osgi/datasource-h2.xml</filename>: Enterprise OSGi JPA usage can include a DataSource installed in the container.
The client bundle's <literal>persistence.xml</literal> references the DataSource through JNDI. For an
example, see how managed-jpa's <literal>persistence.xml</literal> calls out the
<literal>jta-data-source</literal>.
</listitem>
<listitem>
<filename>osgi/[project]/features.xml</filename>: This is arguably the most important "quick start" material. It defines
a single Karaf feature ("hibernate-test") that demonstrates the necessary 3rd party libraries and
bundle activation ordering.
</listitem>
<listitem>
<filename>osgi/[project]/pom.xml</filename>: The POM includes typical compile-time dependencies (JPA, OSGi Core,
OSGi Enterprise), as well as OSGi manifest data.
</listitem>
<listitem>
<filename>osgi/[project]/src/main/resources/OSGI-INF/blueprint/blueprint.xml</filename>:
The Blueprint includes container-managed EntityManager
injection (for managed-jpa), as well as demonstrations showing how to register
your custom implementations of Hibernate extension points.
</listitem>
<listitem>
<filename>osgi/[project]/src/main/resources/META-INF/persistence.xml</filename> or
<filename>osgi/[project]/src/main/resources/hibernate.cfg.xml</filename>: Note that the configurations
are no different than typical uses of Hibernate!
</listitem>
<listitem>
<filename>osgi/[project]/src/main/java/org/hibernate/osgitest/HibernateUtil.java</filename>: Demonstrates how to create an
EntityManagerFactory (JPA) or SessionFactory (Native) using hibernate-osgi's services. Note that in
managed-jpa, this is replaced by <literal>DataPointServiceImpl#entityManager</literal>, injected by
<filename>blueprint.xml</filename> (described above).
</listitem>
</itemizedlist>
</section>
<section xml:id="hibernate-gsg-tutorial-envers-config">
<title>
TODOs
</title>
<itemizedlist>
<listitem>
If using managed-jpa, <filename>features.xml</filename> will need the path to
<filename>datasource-h2.xml</filename> updated.
</listitem>
</itemizedlist>
</section>
<section xml:id="hibernate-gsg-tutorial-envers-config">
<title>
Karaf Commands
</title>
<para>
All three bundles include Karaf Commands that can be used directly on the Karaf command line to test
basic persistence operations ("dp:add [name]", "dp:getall", "dp:deleteall", etc.). I leave them in the
QuickStarts as a useful sanity check.
</para>
</section>
</chapter>

View File

@ -23,13 +23,21 @@
xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0" xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"
xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"> xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0">
<!-- This gets the container-managed EntityManager and injects it into the DataPointServiceImpl bean. -->
<bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl"> <bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl">
<jpa:context unitname="managed-jpa" property="entityManager"/> <jpa:context unitname="managed-jpa" property="entityManager"/>
<tx:transaction method="*" value="Required"/> <tx:transaction method="*" value="Required"/>
</bean> </bean>
<service ref="dpService" interface="org.hibernate.osgitest.DataPointService" /> <service ref="dpService" interface="org.hibernate.osgitest.DataPointService" />
<!-- This demonstrates how to register your custom implementations of Hibernate extension points, such as
Integrator and TypeContributor. -->
<!-- <bean id="integrator" class="your.package.IntegratorImpl"/>
<service ref="integrator" interface="org.hibernate.integrator.spi.Integrator"/>
<bean id="typeContributor" class="your.package.TypeContributorImpl"/>
<service ref="typeContributor" interface="org.hibernate.metamodel.spi.TypeContributor"/> -->
<!-- This bundle makes use of Karaf commands to demonstrate core persistence operations. Feel free to remove it. -->
<command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0"> <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
<command name="dp/add"> <command name="dp/add">
<action class="org.hibernate.osgitest.command.AddCommand"> <action class="org.hibernate.osgitest.command.AddCommand">

View File

@ -22,9 +22,16 @@
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl"/> <bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl"/>
<service ref="dpService" interface="org.hibernate.osgitest.DataPointService" /> <service ref="dpService" interface="org.hibernate.osgitest.DataPointService" />
<!-- This demonstrates how to register your custom implementations of Hibernate extension points, such as
Integrator and TypeContributor. -->
<!-- <bean id="integrator" class="your.package.IntegratorImpl"/>
<service ref="integrator" interface="org.hibernate.integrator.spi.Integrator"/>
<bean id="typeContributor" class="your.package.TypeContributorImpl"/>
<service ref="typeContributor" interface="org.hibernate.metamodel.spi.TypeContributor"/> -->
<!-- This bundle makes use of Karaf commands to demonstrate core persistence operations. Feel free to remove it. -->
<command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0"> <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
<command name="dp:add"> <command name="dp:add">
<action class="org.hibernate.osgitest.command.AddCommand"> <action class="org.hibernate.osgitest.command.AddCommand">

View File

@ -22,9 +22,16 @@
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl"/> <bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl"/>
<service ref="dpService" interface="org.hibernate.osgitest.DataPointService" /> <service ref="dpService" interface="org.hibernate.osgitest.DataPointService" />
<!-- This demonstrates how to register your custom implementations of Hibernate extension points, such as
Integrator and TypeContributor. -->
<!-- <bean id="integrator" class="your.package.IntegratorImpl"/>
<service ref="integrator" interface="org.hibernate.integrator.spi.Integrator"/>
<bean id="typeContributor" class="your.package.TypeContributorImpl"/>
<service ref="typeContributor" interface="org.hibernate.metamodel.spi.TypeContributor"/> -->
<!-- This bundle makes use of Karaf commands to demonstrate core persistence operations. Feel free to remove it. -->
<command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0"> <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
<command name="dp:add"> <command name="dp:add">
<action class="org.hibernate.osgitest.command.AddCommand"> <action class="org.hibernate.osgitest.command.AddCommand">