HHH-6641 - Document services

documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml

@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding='utf-8' ?>
+<?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 <!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_Development_Guide.ent">
 %BOOK_ENTITIES;
@@ -12,6 +12,7 @@
   <xi:include href="Batch_Processing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Locking.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Caching.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="Services.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Data_Categorizations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Mapping_Entities.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Mapping_Association.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

documentation/src/main/docbook/devguide/en-US/Services.xml

@@ -60,24 +60,32 @@
             Services are allowed to declare dependencies on other services using either of 2 approaches.
         </para>
         <section>
-            <title>@InjectService</title>
+            <title>@<interfacename>org.hibernate.service.spi.InjectService</interfacename></title>
             <para>
                 Any method on the service implementation class accepting a single parameter and annotated with
-                @<interfacename>org.hibernate.service.spi.InjectService</interfacename> is considered requesting
+                @<interfacename>InjectService</interfacename> is considered requesting injection of another service.
-                injection of another service.
             </para>
             <para>
                 By default the type of the method parameter is expected to be the service role to be injected.  If the
                 parameter type is different than the service role, the <methodname>serviceRole</methodname> attribute
-                of the <interfacename>org.hibernate.service.spi.InjectService</interfacename> should be used to
+                of the <interfacename>InjectService</interfacename> should be used to explicitly name the role.
-                explicitly name the role.
             </para>
             <para>
                 By default injected services are considered required, that is the start up will fail if a named
                 dependent service is missing.  If the service to be injected is optional, the
-                <methodname>required</methodname> attribute of the
+                <methodname>required</methodname> attribute of the <interfacename>InjectService</interfacename>
-                <interfacename>org.hibernate.service.spi.InjectService</interfacename> should be declared as
+                should be declared as <literal>false</literal> (default is <literal>true</literal>).
-                <literal>false</literal> (default is <literal>true</literal>).
+            </para>
+        </section>
+        <section>
+            <title><interfacename>org.hibernate.service.spi.ServiceRegistryAwareService</interfacename></title>
+            <para>
+                The second approach is a pull approach where the service implements the optional service interface
+                <interfacename>org.hibernate.service.spi.ServiceRegistryAwareService</interfacename> which declares
+                a single <methodname>injectServices</methodname> method.  During startup, Hibernate will inject the
+                <interfacename>org.hibernate.service.ServiceRegistry</interfacename> itself into services which
+                implement this interface.  The service can then use the <interfacename>ServiceRegistry</interfacename>
+                reference to locate any additional services it needs.
             </para>
         </section>
     </section>