Skip to content

Commit 76a06db

Browse files
brmeyerbrmeyer
committed
HHH-8112 quickstart tutorial chapter
1 parent 2f83a23 commit 76a06db

File tree

6 files changed

+138
-5
lines changed

6 files changed

+138
-5
lines changed

‎documentation/src/main/docbook/quickstart/en-US/Author_Group.xml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@
3131
<surname>Warski</surname>
3232
</personname>
3333
</author>
34+
<author>
35+
<personname>
36+
<firstname>Brett</firstname>
37+
<surname>Meyer</surname>
38+
</personname>
39+
</author>
3440

3541
<othercredit>
3642
<personname>
@@ -52,4 +58,4 @@
5258
</affiliation>
5359
</othercredit>
5460

55-
</authorgroup>
61+
</authorgroup>

‎documentation/src/main/docbook/quickstart/en-US/Hibernate_Getting_Started_Guide.xml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,5 +43,6 @@
4343
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_annotations.xml" />
4444
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_jpa.xml" />
4545
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_envers.xml" />
46+
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_osgi.xml" />
4647

47-
</book>
48+
</book>

‎documentation/src/main/docbook/quickstart/en-US/content/tutorial_osgi.xml

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<?xml version='1.0' encoding='UTF-8' ?>
2+
3+
<chapter xmlns="http://docbook.org/ns/docbook"
4+
xmlns:xl="http://www.w3.org/1999/xlink"
5+
xmlns:xi="http://www.w3.org/2001/XInclude">
6+
<title>OSGi Tutorial</title>
7+
8+
<para>
9+
Hibernate targets the OSGi 4.3 spec or later and supports three types
10+
of configurations.
11+
12+
<orderedlist>
13+
<listitem>
14+
<link xl:href="https://github.com/hibernate/hibernate-orm/tree/master/documentation/src/main/docbook/quickstart/tutorials/osgi/managed-jpa">Container-Managed JPA</link>
15+
</listitem>
16+
<listitem>
17+
<link xl:href="https://github.com/hibernate/hibernate-orm/tree/master/documentation/src/main/docbook/quickstart/tutorials/osgi/unmanaged-jpa">Unmanaged JPA</link>
18+
</listitem>
19+
<listitem>
20+
<link xl:href="https://github.com/hibernate/hibernate-orm/tree/master/documentation/src/main/docbook/quickstart/tutorials/osgi/unmanaged-native">Unmanaged Native</link>
21+
</listitem>
22+
</orderedlist>
23+
</para>
24+
25+
<para>
26+
For more details about OSGi, the three configurations, hibernate-osgi, extensions points, and caveats, please
27+
see the OSGi chapter of the Developer's Guide!
28+
</para>
29+
30+
<section>
31+
<title>
32+
Project Overview
33+
</title>
34+
<para>
35+
Each configuration has a QuickStart project located within the download bundle (under <filename>osgi</filename>).
36+
The bundles can be used as-is within Apache Karaf. Feel free to use them as literal
37+
"quick start" bundle templates.
38+
</para>
39+
</section>
40+
41+
<section>
42+
<title>
43+
Project Structure
44+
</title>
45+
<itemizedlist>
46+
<listitem>
47+
<filename>osgi/datasource-h2.xml</filename>: Enterprise OSGi JPA usage can include a DataSource installed in the container.
48+
The client bundle's <literal>persistence.xml</literal> references the DataSource through JNDI. For an
49+
example, see how managed-jpa's <literal>persistence.xml</literal> calls out the
50+
<literal>jta-data-source</literal>.
51+
</listitem>
52+
<listitem>
53+
<filename>osgi/[project]/features.xml</filename>: This is arguably the most important "quick start" material. It defines
54+
a single Karaf feature ("hibernate-test") that demonstrates the necessary 3rd party libraries and
55+
bundle activation ordering.
56+
</listitem>
57+
<listitem>
58+
<filename>osgi/[project]/pom.xml</filename>: The POM includes typical compile-time dependencies (JPA, OSGi Core,
59+
OSGi Enterprise), as well as OSGi manifest data.
60+
</listitem>
61+
<listitem>
62+
<filename>osgi/[project]/src/main/resources/OSGI-INF/blueprint/blueprint.xml</filename>:
63+
The Blueprint includes container-managed EntityManager
64+
injection (for managed-jpa), as well as demonstrations showing how to register
65+
your custom implementations of Hibernate extension points.
66+
</listitem>
67+
<listitem>
68+
<filename>osgi/[project]/src/main/resources/META-INF/persistence.xml</filename> or
69+
<filename>osgi/[project]/src/main/resources/hibernate.cfg.xml</filename>: Note that the configurations
70+
are no different than typical uses of Hibernate!
71+
</listitem>
72+
<listitem>
73+
<filename>osgi/[project]/src/main/java/org/hibernate/osgitest/HibernateUtil.java</filename>: Demonstrates how to create an
74+
EntityManagerFactory (JPA) or SessionFactory (Native) using hibernate-osgi's services. Note that in
75+
managed-jpa, this is replaced by <literal>DataPointServiceImpl#entityManager</literal>, injected by
76+
<filename>blueprint.xml</filename> (described above).
77+
</listitem>
78+
</itemizedlist>
79+
</section>
80+
81+
<section xml:id="hibernate-gsg-tutorial-envers-config">
82+
<title>
83+
TODOs
84+
</title>
85+
<itemizedlist>
86+
<listitem>
87+
If using managed-jpa, <filename>features.xml</filename> will need the path to
88+
<filename>datasource-h2.xml</filename> updated.
89+
</listitem>
90+
</itemizedlist>
91+
</section>
92+
93+
<section xml:id="hibernate-gsg-tutorial-envers-config">
94+
<title>
95+
Karaf Commands
96+
</title>
97+
<para>
98+
All three bundles include Karaf Commands that can be used directly on the Karaf command line to test
99+
basic persistence operations ("dp:add [name]", "dp:getall", "dp:deleteall", etc.). I leave them in the
100+
QuickStarts as a useful sanity check.
101+
</para>
102+
</section>
103+
104+
</chapter>

‎documentation/src/main/docbook/quickstart/tutorials/osgi/managed-jpa/src/main/resources/OSGI-INF/blueprint/blueprint.xml

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,21 @@
2323
xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"
2424
xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0">
2525

26+
<!-- This gets the container-managed EntityManager and injects it into the DataPointServiceImpl bean. -->
2627
<bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl">
2728
<jpa:context unitname="managed-jpa" property="entityManager"/>
2829
<tx:transaction method="*" value="Required"/>
2930
</bean>
30-
3131
<service ref="dpService" interface="org.hibernate.osgitest.DataPointService" />
3232

33+
<!-- This demonstrates how to register your custom implementations of Hibernate extension points, such as
34+
Integrator and TypeContributor. -->
35+
<!-- <bean id="integrator" class="your.package.IntegratorImpl"/>
36+
<service ref="integrator" interface="org.hibernate.integrator.spi.Integrator"/>
37+
<bean id="typeContributor" class="your.package.TypeContributorImpl"/>
38+
<service ref="typeContributor" interface="org.hibernate.metamodel.spi.TypeContributor"/> -->
39+
40+
<!-- This bundle makes use of Karaf commands to demonstrate core persistence operations. Feel free to remove it. -->
3341
<command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
3442
<command name="dp/add">
3543
<action class="org.hibernate.osgitest.command.AddCommand">

‎documentation/src/main/docbook/quickstart/tutorials/osgi/unmanaged-jpa/src/main/resources/OSGI-INF/blueprint/blueprint.xml

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,16 @@
2222
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2323

2424
<bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl"/>
25-
2625
<service ref="dpService" interface="org.hibernate.osgitest.DataPointService" />
2726

27+
<!-- This demonstrates how to register your custom implementations of Hibernate extension points, such as
28+
Integrator and TypeContributor. -->
29+
<!-- <bean id="integrator" class="your.package.IntegratorImpl"/>
30+
<service ref="integrator" interface="org.hibernate.integrator.spi.Integrator"/>
31+
<bean id="typeContributor" class="your.package.TypeContributorImpl"/>
32+
<service ref="typeContributor" interface="org.hibernate.metamodel.spi.TypeContributor"/> -->
33+
34+
<!-- This bundle makes use of Karaf commands to demonstrate core persistence operations. Feel free to remove it. -->
2835
<command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
2936
<command name="dp:add">
3037
<action class="org.hibernate.osgitest.command.AddCommand">

‎documentation/src/main/docbook/quickstart/tutorials/osgi/unmanaged-native/src/main/resources/OSGI-INF/blueprint/blueprint.xml

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,16 @@
2222
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2323

2424
<bean id="dpService" class="org.hibernate.osgitest.DataPointServiceImpl"/>
25-
2625
<service ref="dpService" interface="org.hibernate.osgitest.DataPointService" />
2726

27+
<!-- This demonstrates how to register your custom implementations of Hibernate extension points, such as
28+
Integrator and TypeContributor. -->
29+
<!-- <bean id="integrator" class="your.package.IntegratorImpl"/>
30+
<service ref="integrator" interface="org.hibernate.integrator.spi.Integrator"/>
31+
<bean id="typeContributor" class="your.package.TypeContributorImpl"/>
32+
<service ref="typeContributor" interface="org.hibernate.metamodel.spi.TypeContributor"/> -->
33+
34+
<!-- This bundle makes use of Karaf commands to demonstrate core persistence operations. Feel free to remove it. -->
2835
<command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
2936
<command name="dp:add">
3037
<action class="org.hibernate.osgitest.command.AddCommand">

0 commit comments

Comments
 (0)