From 8c691d5fcd403e606093a2194c42ffd476353d35 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Tue, 27 Sep 2011 11:03:44 -0500 Subject: [PATCH] HHH-6663 - Proof/edit Services.xml in devguide --- .../main/docbook/devguide/en-US/Services.xml | 239 ++++++++++-------- 1 file changed, 132 insertions(+), 107 deletions(-) diff --git a/documentation/src/main/docbook/devguide/en-US/Services.xml b/documentation/src/main/docbook/devguide/en-US/Services.xml index 662baa9b9f..6354f08288 100644 --- a/documentation/src/main/docbook/devguide/en-US/Services.xml +++ b/documentation/src/main/docbook/devguide/en-US/Services.xml @@ -29,28 +29,9 @@ Optionally, the service can also implement the org.hibernate.service.spi.Startable and org.hibernate.service.spi.Stoppable interfaces to receive notifications - of when they are becoming active and becoming deactivated. - - - Another optional service contract is org.hibernate.service.spi.Manageable - which marks the service as manageable in JMX provided the JMX integration is enabled. - - - -
- ServiceRegistry - - The central service API, aside from the services themselves, is the - org.hibernate.service.ServiceRegistry interface, the main purpose of which - is hold, manage and provide access to services. - -
- -
- ServiceRegistryBuilder - - Building a org.hibernate.service.ServiceRegistry is the purpose of the - org.hibernate.service.ServiceRegistryBuilder. + of being started and stopped. Another optional service contract is + org.hibernate.service.spi.Manageable which marks the service as manageable + in JMX provided the JMX integration is enabled.
@@ -90,43 +71,24 @@ -
- Custom services +
+ ServiceRegistry - Once a org.hibernate.service.ServiceRegistry is built it is considered - immutable; the services themselves might accept re-configuration, but immutability here means - adding/replacing services. So another role provided by the - org.hibernate.service.ServiceRegistryBuilder is to allow tweaking of the services - that will be contained in the org.hibernate.service.ServiceRegistry - generated from it. + The central service API, aside from the services themselves, is the + org.hibernate.service.ServiceRegistry interface. The main purpose of + a service registry is to hold, manage and provide access to services. - There are 2 means to tell a org.hibernate.service.ServiceRegistryBuilder about - custom services. + Service registries are hierarchical. Services in one registry can depend on and utilize services in that + same registry as well as any parent registries. - - - - Implement a org.hibernate.service.spi.BasicServiceInitiator class - to control on-demand construction of the service class and add it to the - org.hibernate.service.ServiceRegistryBuilder via its - addInitiator method. - - - - - Just instantiate the service class and add it to the - org.hibernate.service.ServiceRegistryBuilder via its - addService method. - - - - Either approach the adding a service approach or the adding an initiator approach are valid for extending a - registry (adding new service roles) and overriding services (replacing service implementations). + Use org.hibernate.service.ServiceRegistryBuilder to build a + org.hibernate.service.ServiceRegistry instance.
+
Standard services @@ -732,7 +694,7 @@ instances which acts as a specialized org.hibernate.service.ServiceRegistry for org.hibernate.SessionFactory scoped services. See - for more details. + for more details. @@ -862,62 +824,125 @@
-
- SessionFactory services - - - There are also a number of services that are specific to each - org.hibernate.SessionFactory that are maintained as part of - org.hibernate.service.spi.SessionFactoryServiceRegistry - - -
- <interfacename>org.hibernate.event.service.spi.EventListenerRegistry</interfacename> - - - Notes - - - Service for managing event listeners. - - - - - Initiator - - - org.hibernate.event.service.internal.EventListenerServiceInitiator - - - - - Implementations - - - org.hibernate.event.service.internal.EventListenerRegistryImpl - - - - -
- -
- Boot-strap services - -
- <interfacename>org.hibernate.service.classloading.spi.ClassLoaderService</interfacename> - - Coming soon... See - -
- -
- <interfacename>org.hibernate.integrator.spi.IntegratorService</interfacename> - - Coming soon... See - -
+ Custom services + + Once a org.hibernate.service.ServiceRegistry is built it is considered + immutable; the services themselves might accept re-configuration, but immutability here means + adding/replacing services. So another role provided by the + org.hibernate.service.ServiceRegistryBuilder is to allow tweaking of the services + that will be contained in the org.hibernate.service.ServiceRegistry + generated from it. + + + There are 2 means to tell a org.hibernate.service.ServiceRegistryBuilder about + custom services. + + + + + Implement a org.hibernate.service.spi.BasicServiceInitiator class + to control on-demand construction of the service class and add it to the + org.hibernate.service.ServiceRegistryBuilder via its + addInitiator method. + + + + + Just instantiate the service class and add it to the + org.hibernate.service.ServiceRegistryBuilder via its + addService method. + + + + + Either approach the adding a service approach or the adding an initiator approach are valid for extending a + registry (adding new service roles) and overriding services (replacing service implementations). +
+ + +
+ Special service registries + +
+ Boot-strap registry + + The boot-strap registry holds services that absolutely have to be available for most things to work. + The main service here is the which is a perfect example. + Even resolving configuration files needs access to class loading services (resource look ups). This + is the root registry (no parent) in normal use. + + +
+ Boot-strap registry services +
+ <interfacename>org.hibernate.service.classloading.spi.ClassLoaderService</interfacename> + + Coming soon... See + +
+ +
+ <interfacename>org.hibernate.integrator.spi.IntegratorService</interfacename> + + Coming soon... See + +
+
+
+ +
+ SessionFactory registry + + While it is best practice to treat instances of all the registry types as targeting a given + org.hibernate.SessionFactory, the instances of services in this group + explicitly belong to a single org.hibernate.SessionFactory. The + difference is a matter of timing in when they need to be initiated. Generally they need access to the + org.hibernate.SessionFactory to be initiated. This special registry is + org.hibernate.service.spi.SessionFactoryServiceRegistry + + +
+ <interfacename>org.hibernate.event.service.spi.EventListenerRegistry</interfacename> + + + Notes + + + Service for managing event listeners. + + + + + Initiator + + + org.hibernate.event.service.internal.EventListenerServiceInitiator + + + + + Implementations + + + org.hibernate.event.service.internal.EventListenerRegistryImpl + + + + +
+
+ +
+ + +
+ Using services and registries + + Coming soon... + +
+ \ No newline at end of file