HHH-15170 - Dedicated chapter for "Build Tool Support"
HHH-15171 - Add discussion of the Ant Plugin
This commit is contained in:
Steve Ebersole
parent
17bb4aa066
commit
84cf4524ea
|
|
@ -1,63 +0,0 @@
|
||||||
[[jpa-bootstrap-guide]]
|
|
||||||
= Bootstrapping Hibernate Jakarta Persistence
|
|
||||||
:toc:
|
|
||||||
|
|
||||||
Bootstrapping Hibernate as a Jakarta Persistence provider can be done in a Jakarta Persistence-spec compliant manner or using a proprietary
|
|
||||||
bootstrapping approach. The standardized approach has some limitations in certain environments. But aside from
|
|
||||||
those limitations, it is *highly* recommended that you use Jakarta Persistence-standardized bootstrapping.
|
|
||||||
|
|
||||||
NOTE: Under the covers, all of Hibernate's Jakarta Persistence bootstrapping makes use of its native bootstrapping. Be sure to see
|
|
||||||
the _Native Bootstrapping_ guide as well.
|
|
||||||
|
|
||||||
== Jakarta Persistence compliant bootstrapping
|
|
||||||
|
|
||||||
In Jakarta Persistence we are ultimately interested in bootstrapping an `jakarta.persistence.EntityManagerFactory` instance. The
|
|
||||||
Jakarta Persistence specification defines 2 primary standardized bootstrap approaches depending on how the application intends to
|
|
||||||
access the `jakarta.persistence.EntityManager` instances from an `EntityManagerFactory`. It uses the terms "EE" and
|
|
||||||
"SE" for these 2 approaches, but those terms are very misleading in this context. What the Jakarta Persistence spec calls EE
|
|
||||||
bootstrapping is cases where a container (EE, OSGi, etc) will manage and inject the persistence context on behalf
|
|
||||||
of the application. What it calls SE bootstrapping is everything else. We will use the terms
|
|
||||||
container-bootstrapping and application-bootstrapping in this guide.
|
|
||||||
|
|
||||||
NOTE: If you would like additional details on accessing and using `EntityManager` instances, sections 7.6
|
|
||||||
and 7.7 of the Jakarta Persistence specification cover container-managed and application-managed EntityManagers,
|
|
||||||
respectively.
|
|
||||||
|
|
||||||
|
|
||||||
=== Container-bootstrapping
|
|
||||||
|
|
||||||
The container will build an `EntityManagerFactory` for each persistent-unit defined in the deployment's
|
|
||||||
`META-INF/persistence.xml` and make that available to the application for injection via the
|
|
||||||
`jakarta.persistence.PersistenceUnit` annotation or via JNDI lookup.
|
|
||||||
|
|
||||||
[[container-bootstrap-injection-example]]
|
|
||||||
.Injecting a EntityManagerFactory
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
@PersistenceUnit
|
|
||||||
EntityManagerFactory emf;
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
|
|
||||||
=== Application-bootstrapping
|
|
||||||
|
|
||||||
Rather than something a container building the `EntityManagerFactory` for the application, the application
|
|
||||||
can build the `EntityManagerFactory` using the `jakarta.persistence.Persistence` bootstrap class. The application
|
|
||||||
creates an entity manager factory by calling the createEntityManagerFactory method:
|
|
||||||
|
|
||||||
[[application-bootstrap-example]]
|
|
||||||
.Application bootstrapped EntityManagerFactory
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
// Create an EMF for our CRM persistence-unit.
|
|
||||||
EntityManagerFactory emf = Persistence.createEntityManagerFactory("CRM");
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
|
|
||||||
== Proprietary 2-phase bootstrapping
|
|
||||||
|
|
||||||
todo: document EntityManagerFactoryBuilder...
|
|
||||||
|
|
@ -1,127 +0,0 @@
|
||||||
[[legacy-boostrap-guide]]
|
|
||||||
= Legacy Bootstrapping
|
|
||||||
:toc:
|
|
||||||
|
|
||||||
The legacy way to bootstrap a `SessionFactory` is via the `org.hibernate.cfg.Configuration` object.
|
|
||||||
`Configuration` represents, essentially, a single point for specifying all aspects of building
|
|
||||||
the `SessionFactory`: everything from settings, to mappings, to strategies, etc. I like to think of
|
|
||||||
`Configuration` as a big pot to which we add a bunch of stuff (mappings, settings, etc) and from which
|
|
||||||
we eventually get a `SessionFactory`.
|
|
||||||
|
|
||||||
NOTE: There are some significant draw backs to this approach which led to its deprecation and the development
|
|
||||||
of the new approach, which is discussed in the _Native Bootstrapping_ guide. `Configuration` is deprecated but
|
|
||||||
still available for use, in a limited form that eliminates these draw backs. "Under the covers", Configuration
|
|
||||||
uses the new bootstrapping code, so the things available there as also available here in terms of
|
|
||||||
auto-discovery.
|
|
||||||
|
|
||||||
|
|
||||||
== Usage
|
|
||||||
|
|
||||||
You can obtain the `Configuration` by instantiating it directly. You then specify mapping metadata (XML
|
|
||||||
mapping documents, annotated classes) that describe your applications object model and its mapping to a
|
|
||||||
SQL database.
|
|
||||||
|
|
||||||
If XML mapping files are in the classpath, use addResource(). For example:
|
|
||||||
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
Configuration cfg = new Configuration()
|
|
||||||
// addResource does a classpath resource lookup
|
|
||||||
.addResource("Item.hbm.xml")
|
|
||||||
.addResource("Bid.hbm.xml")
|
|
||||||
|
|
||||||
// calls addResource using "/org/hibernate/auction/User.hbm.xml"
|
|
||||||
.addClass(`org.hibernate.auction.User.class`)
|
|
||||||
|
|
||||||
// parses Address class for mapping annotations
|
|
||||||
.addAnnotatedClass( Address.class )
|
|
||||||
|
|
||||||
// reads package-level (package-info.class) annotations in the named package
|
|
||||||
.addPackage( "org.hibernate.auction" )
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
`Configuration` also allows you to specify configuration properties. For example:
|
|
||||||
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
Configuration cfg = new Configuration()
|
|
||||||
.setProperty("hibernate.dialect", "org.hibernate.dialect.H2Dialect")
|
|
||||||
.setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
|
|
||||||
.setProperty("hibernate.order_updates", "true");
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
There are other ways to specify configuration properties, including:
|
|
||||||
|
|
||||||
* Place a file named hibernate.properties in a root directory of the classpath.
|
|
||||||
* Place a file named hibernate.properties in a root directory of the classpath.
|
|
||||||
* Pass an instance of java.util.Properties to `Configuration#setProperties`.
|
|
||||||
* Set System properties using Java `-Dproperty=value`.
|
|
||||||
* Include `<property/>` elements in `hibernate.cfg.xml`
|
|
||||||
|
|
||||||
|
|
||||||
== Migration
|
|
||||||
|
|
||||||
Mapping Configuration methods to the corresponding methods in the new API..
|
|
||||||
|
|
||||||
=== Mapping metadata
|
|
||||||
|
|
||||||
`Configuration#addFile`::
|
|
||||||
`MetadataSources#addFile`
|
|
||||||
`Configuration#add(XmlDocument)`::
|
|
||||||
No replacement.
|
|
||||||
`Configuration#addXML`::
|
|
||||||
No replacement.
|
|
||||||
`Configuration#addCacheableFile`::
|
|
||||||
`MetadataSources#addCacheableFile`
|
|
||||||
`Configuration#addURL`::
|
|
||||||
`MetadataSources#addURL`
|
|
||||||
`Configuration#addInputStream`::
|
|
||||||
`MetadataSources#addInputStream`
|
|
||||||
`Configuration#addResource`::
|
|
||||||
`MetadataSources#addResource`
|
|
||||||
`Configuration#addClass`::
|
|
||||||
`MetadataSources#addClass`
|
|
||||||
`Configuration#addAnnotatedClass`::
|
|
||||||
`MetadataSources#addAnnotatedClass`
|
|
||||||
`Configuration#addPackage`::
|
|
||||||
`MetadataSources#addPackage`
|
|
||||||
`Configuration#addJar`::
|
|
||||||
`MetadataSources#addJar`
|
|
||||||
`Configuration#addDirectory`::
|
|
||||||
`MetadataSources#addDirectory`
|
|
||||||
|
|
||||||
`Configuration#registerTypeContributor`::
|
|
||||||
`MetadataBuilder#applyTypes`
|
|
||||||
`Configuration#registerTypeOverride`::
|
|
||||||
`MetadataBuilder#applyBasicType`
|
|
||||||
|
|
||||||
=== Settings
|
|
||||||
|
|
||||||
`Configuration#setProperty`::
|
|
||||||
`StandardServiceRegistryBuilder#applySetting`
|
|
||||||
`Configuration#setProperties`::
|
|
||||||
No replacement.
|
|
||||||
`Configuration#addProperties`::
|
|
||||||
`StandardServiceRegistryBuilder#applySettings`
|
|
||||||
`Configuration#setNamingStrategy`::
|
|
||||||
No replacement. NamingStrategy split into implicit/physical strategies
|
|
||||||
`Configuration#setImplicitNamingStrategy`::
|
|
||||||
`MetadataBuilder#setImplicitNamingStrategy`
|
|
||||||
`Configuration#setPhysicalNamingStrategy`::
|
|
||||||
`MetadataBuilder#setPhysicalNamingStrategy`
|
|
||||||
`Configuration#configure`::
|
|
||||||
`StandardServiceRegistryBuilder#configure`
|
|
||||||
|
|
||||||
`Configuration#setInterceptor`::
|
|
||||||
`SessionFactoryBuilder#applyInterceptor`
|
|
||||||
`Configuration#setEntityNotFoundDelegate`::
|
|
||||||
`SessionFactoryBuilder#applyEntityNotFoundDelegate`
|
|
||||||
`Configuration#setSessionFactoryObserver`::
|
|
||||||
`SessionFactoryBuilder#addSessionFactoryObservers`
|
|
||||||
`Configuration#setCurrentTenantIdentifierResolver`::
|
|
||||||
`SessionFactoryBuilder#applyCurrentTenantIdentifierResolver`
|
|
||||||
|
|
||||||
|
|
@ -1,274 +0,0 @@
|
||||||
[[native-bootstrap]]
|
|
||||||
= Native Bootstrapping
|
|
||||||
:toc:
|
|
||||||
|
|
||||||
This guide discusses the process of bootstrapping a Hibernate `org.hibernate.SessionFactory`. It also
|
|
||||||
discusses the ways in which applications and integrators can hook-in to and affect that process. This
|
|
||||||
bootstrapping process is defined in 2 distinct steps. The first step is the building of a ServiceRegistry
|
|
||||||
holding the services Hibernate will need at bootstrap- and runtime. The second step is the building of
|
|
||||||
a Metadata object representing the mapping information for the application's model and its mapping to
|
|
||||||
the database.
|
|
||||||
|
|
||||||
NOTE: Prior to version 5.0 applications bootstrapped a `SessionFactory` is via the
|
|
||||||
`org.hibernate.cfg.Configuration` object. That approach is still supported in a slightly limited manner.
|
|
||||||
See the _Legacy Bootstrapping_ guide for details.
|
|
||||||
|
|
||||||
|
|
||||||
== Building the ServiceRegistry
|
|
||||||
|
|
||||||
Actually we are concerned with building 2 different ServiceRegistries:
|
|
||||||
|
|
||||||
* `org.hibernate.boot.registry.BootstrapServiceRegistry`
|
|
||||||
* `org.hibernate.boot.registry.StandardServiceRegistry`
|
|
||||||
|
|
||||||
Each of these is built from a builder, `org.hibernate.boot.registry.BootstrapServiceRegistryBuilder`
|
|
||||||
and `org.hibernate.boot.registry.StandardServiceRegistryBuilder` respectively.
|
|
||||||
|
|
||||||
|
|
||||||
NOTE: For more information on ServiceRegistries in general, see the _Services and Registries_ guide.
|
|
||||||
|
|
||||||
=== BootstrapServiceRegistry
|
|
||||||
|
|
||||||
The `BootstrapServiceRegistry` is intended to hold services that Hibernate needs at both bootstrap and run time.
|
|
||||||
This boils down to 3 services:
|
|
||||||
|
|
||||||
* `ClassLoaderService` - which controls how Hibernate interacts with ClassLoaders
|
|
||||||
* `IntegratorService` - which controls the management ands discovery of `org.hibernate.integrator.spi.Integrator` instances.
|
|
||||||
* `StrategySelector` - which control how Hibernate resolves implementations of various strategy
|
|
||||||
contracts. This is a very powerful service, but a full discussion of it is beyond the scope
|
|
||||||
of this guide.
|
|
||||||
|
|
||||||
If you are ok with the default behavior of Hibernate in regards to these BootstrapServiceRegistry services
|
|
||||||
(which is quite often the case, especially in SE environments) building the BootstrapServiceRegistry can be skipped.
|
|
||||||
If you wish to alter how the `BootstrapServiceRegistry` is built, you would use the `BootstrapServiceRegistryBuilder`:
|
|
||||||
|
|
||||||
[[bootstrap-registry-builder-example]]
|
|
||||||
.Building a BootstrapServiceRegistry
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
BootstrapServiceRegistryBuilder bootstrapRegistryBuilder
|
|
||||||
= new BootstrapServiceRegistryBuilder();
|
|
||||||
// add a special ClassLoader
|
|
||||||
bootstrapRegistryBuilder.applyClassLoader( mySpecialClassLoader );
|
|
||||||
// manually add an Integrator
|
|
||||||
bootstrapRegistryBuilder.applyIntegrator( mySpecialIntegrator );
|
|
||||||
...
|
|
||||||
|
|
||||||
BootstrapServiceRegistry bootstrapRegistry = bootstrapRegistryBuilder.build();
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
The services of the `BootstrapServiceRegistry` cannot be extended (added to) nor overridden (replaced).
|
|
||||||
|
|
||||||
|
|
||||||
=== StandardServiceRegistry
|
|
||||||
|
|
||||||
The services of the `StandardServiceRegistry` may be extended and overridden.
|
|
||||||
|
|
||||||
A `StandardServiceRegistry` is built through the `StandardServiceRegistryBuilder` which can be constructed in
|
|
||||||
one of 2 ways:
|
|
||||||
|
|
||||||
[[standard-registry-builder-example1]]
|
|
||||||
.Building a StandardServiceRegistryBuilder with a supplied BootstrapServiceRegistry
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
BootstrapServiceRegistry bootstrapRegistry = ...;
|
|
||||||
StandardServiceRegistryBuilder standardRegistryBuilder
|
|
||||||
= new StandardServiceRegistryBuilder( bootstrapRegistry );
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
[[standard-registry-builder-example2]]
|
|
||||||
.Building a StandardServiceRegistryBuilder without a supplied BootstrapServiceRegistry
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
StandardServiceRegistryBuilder standardRegistryBuilder
|
|
||||||
= new StandardServiceRegistryBuilder();
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
The second form will create a `BootstrapServiceRegistry` on the fly with default behavior.
|
|
||||||
|
|
||||||
A `StandardServiceRegistry` is also highly configurable via the `StandardServiceRegistryBuilder` API. See the
|
|
||||||
`StandardServiceRegistryBuilder` javadocs for full details. Some specific methods of interest:
|
|
||||||
|
|
||||||
[[standard-registry-builder-example3]]
|
|
||||||
.Configuring StandardServiceRegistryBuilder
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
StandardServiceRegistryBuilder standardRegistryBuilder = ...;
|
|
||||||
// load some properties via resource lookup
|
|
||||||
standardRegistryBuilder.loadProperties( "org/hibernate/example/MyProperties.properties" );
|
|
||||||
// configure the registry from a resource lookup for a cfg.xml config file
|
|
||||||
standardRegistryBuilder.configure( "org/hibernate/example/MyCfg.xml" );
|
|
||||||
// apply a random setting
|
|
||||||
standardRegistryBuilder.applySetting( "myProp", "some value" );
|
|
||||||
// apply a service initiator
|
|
||||||
standardRegistryBuilder.addInitiator( new CustomServiceInitiator() );
|
|
||||||
// apply a service impl
|
|
||||||
standardRegistryBuilder.addService( SomeCustomService.class, new SomeCustomServiceImpl() );
|
|
||||||
|
|
||||||
// and finally build the StandardServiceRegistry
|
|
||||||
StandardServiceRegistry standardRegistry = standardRegistryBuilder.build();
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
|
|
||||||
== Building the Metadata
|
|
||||||
|
|
||||||
The `org.hibernate.boot.Metadata` object contains the parsed representations of an application's
|
|
||||||
domain model and its mapping to a database. The first thing we obviously need to build a parsed
|
|
||||||
representation is the source information to be parsed (annotated classes, `hbm.xml` files, `orm.xml` files). This is
|
|
||||||
the purpose of `org.hibernate.boot.MetadataSources`.
|
|
||||||
|
|
||||||
|
|
||||||
[[MetadataSources-example]]
|
|
||||||
.Configuring a MetadataSources
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
MetadataSources sources = new MetadataSources( standardRegistry );
|
|
||||||
// alternatively, we can build the MetadataSources without passing
|
|
||||||
// a service registry, in which case it will build a default
|
|
||||||
// BootstrapServiceRegistry to use
|
|
||||||
// MetadataSources sources = new MetadataSources();
|
|
||||||
|
|
||||||
// add a class using annotations for mapping
|
|
||||||
sources.addAnnotatedClass( MyEntity.class );
|
|
||||||
|
|
||||||
// add the name of a class using annotations for mapping.
|
|
||||||
// differs from above in that accessing the Class is deferred which is
|
|
||||||
// important if using runtime bytecode-enhancement
|
|
||||||
sources.addAnnotatedClassName( "org.hibernate.example.Customer" );
|
|
||||||
|
|
||||||
// Adds the named hbm.xml resource as a source: which performs the
|
|
||||||
// classpath lookup and parses the XML
|
|
||||||
sources.addResource( "org/hibernate/example/Order.hbm.xml" );
|
|
||||||
|
|
||||||
// Adds the named orm.xml resource as a source: which performs the
|
|
||||||
// classpath lookup and parses the XML
|
|
||||||
sources.addResource( "org/hibernate/example/Product.orm.xml" );
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
`MetadataSources` has many other methods as well; explore its API and javadocs for more information. Also,
|
|
||||||
all methods on `MetadataSources` allow for chaining should you prefer that style.
|
|
||||||
|
|
||||||
[[MetadataSources-chaining-example]]
|
|
||||||
.Configuring a MetadataSources with method chaining
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
MetadataSources sources = new MetadataSources( standardRegistry )
|
|
||||||
.addAnnotatedClass( MyEntity.class )
|
|
||||||
.addAnnotatedClassName( "org.hibernate.example.Customer" )
|
|
||||||
.addResource( "org/hibernate/example/Order.hbm.xml" )
|
|
||||||
.addResource( "org/hibernate/example/Product.orm.xml" );
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
Once we have the sources of mapping information defined, we need to build the `Metadata` object. If you are
|
|
||||||
ok with the default behavior in building the `Metadata` (or if relying on a `MetadataBuilderInitializer` - see below)
|
|
||||||
then you can simply call `MetadataSources#buildMetadata`.
|
|
||||||
|
|
||||||
NOTE : Notice that a ServiceRegistry can be passed at a number of points in this bootstrapping process. The suggested
|
|
||||||
approach is to build a `StandardServiceRegistry` yourself and pass that along to the `MetadataSources` constructor.
|
|
||||||
From there, `MetadataBuilder`, `Metadata`, `SessionFactoryBuilder` and `SessionFactory` will all pick up that
|
|
||||||
same `StandardServiceRegistry`.
|
|
||||||
|
|
||||||
However, if you wish to adjust the process of building `Metadata` from `MetadataSources` you will need to use
|
|
||||||
the `MetadataBuilder` as obtained via `MetadataSources#getMetadataBuilder`. `MetadataBuilder` allows a lot of control
|
|
||||||
over the `Metadata` building process. See its javadocs for full details.
|
|
||||||
|
|
||||||
[[MetadataBuilder-example]]
|
|
||||||
.Building Metadata via MetadataBuilder
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
MetadataBuilder metadataBuilder = sources.getMetadataBuilder();
|
|
||||||
|
|
||||||
// Use the Jakarta Persistence-compliant implicit naming strategy
|
|
||||||
metadataBuilder.applyImplicitNamingStrategy( ImplicitNamingStrategyJpaCompliantImpl.INSTANCE );
|
|
||||||
|
|
||||||
// specify the schema name to use for tables, etc when none is explicitly specified
|
|
||||||
metadataBuilder.applyImplicitSchemaName( "my_default_schema" );
|
|
||||||
|
|
||||||
Metadata metadata = metadataBuilder.build();
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
== Building the SessionFactory
|
|
||||||
|
|
||||||
Much like we've discussed above, if you are ok with the default behavior of building a `SessionFactory`
|
|
||||||
from a `Metadata` reference, you can simply call `Metadata#buildSessionFactory`. However, if you would like to
|
|
||||||
adjust that building process you will need to use `SessionFactoryBuilder` as obtained via
|
|
||||||
`Metadata#getSessionFactoryBuilder`. See the `SessionFactoryBuilder` javadocs for details of the control it allows
|
|
||||||
over the `SessionFactory` building process.
|
|
||||||
|
|
||||||
[[SessionFactoryBuilder-example]]
|
|
||||||
.Building SessionFactory via SessionFactoryBuilder
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
SessionFactoryBuilder sessionFactoryBuilder = metadata.getSessionFactoryBuilder();
|
|
||||||
|
|
||||||
// Supply a SessionFactory-level Interceptor
|
|
||||||
sessionFactoryBuilder.applyInterceptor( new MySessionFactoryInterceptor() );
|
|
||||||
|
|
||||||
// Add a custom observer
|
|
||||||
sessionFactoryBuilder.addSessionFactoryObservers( new MySessionFactoryObserver() );
|
|
||||||
|
|
||||||
// Apply a CDI BeanManager (for Jakarta Persistence event listeners)
|
|
||||||
sessionFactoryBuilder.applyBeanManager( getBeanManagerFromSomewhere() );
|
|
||||||
|
|
||||||
SessionFactory sessionFactory = sessionFactoryBuilder.build();
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
== Putting It All Together
|
|
||||||
|
|
||||||
The bootstrapping API is quite flexible, but in most cases it makes the most sense to think of
|
|
||||||
it as a 3 step process:
|
|
||||||
|
|
||||||
1. Build the `StandardServiceRegistry`
|
|
||||||
2. Build the `Metadata`
|
|
||||||
3. Use those 2 things to build the `SessionFactory`
|
|
||||||
|
|
||||||
[[Putting-It-All-Together-ex1]]
|
|
||||||
.Building SessionFactory via SessionFactoryBuilder
|
|
||||||
====
|
|
||||||
[source, JAVA]
|
|
||||||
----
|
|
||||||
StandardServiceRegistry standardRegistry = new StandardServiceRegistryBuilder()
|
|
||||||
.configure( "org/hibernate/example/MyCfg.xml" )
|
|
||||||
.build();
|
|
||||||
|
|
||||||
Metadata metadata = new MetadataSources( standardRegistry )
|
|
||||||
.addAnnotatedClass( MyEntity.class )
|
|
||||||
.addAnnotatedClassName( "org.hibernate.example.Customer" )
|
|
||||||
.addResource( "org/hibernate/example/Order.hbm.xml" )
|
|
||||||
.addResource( "org/hibernate/example/Product.orm.xml" )
|
|
||||||
.getMetadataBuilder()
|
|
||||||
.applyImplicitNamingStrategy( ImplicitNamingStrategyJpaCompliantImpl.INSTANCE )
|
|
||||||
.build();
|
|
||||||
|
|
||||||
SessionFactory sessionFactory = metadata.getSessionFactoryBuilder()
|
|
||||||
.applyBeanManager( getBeanManagerFromSomewhere() )
|
|
||||||
.build();
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
|
|
||||||
== Integration Points
|
|
||||||
|
|
||||||
=== Integrator
|
|
||||||
=== ServiceContributor
|
|
||||||
=== TypeContributor
|
|
||||||
=== MetadataSourcesContributor
|
|
||||||
=== MetadataBuilderInitializer
|
|
||||||
=== SessionFactoryBuilderInitializer (todo)
|
|
||||||
=== SessionFactoryObserver
|
|
||||||
|
|
@ -1,162 +0,0 @@
|
||||||
[[bytecode-enhancement-guide]]
|
|
||||||
= Bytecode Enhancement
|
|
||||||
:toc:
|
|
||||||
|
|
||||||
This guide covers Hibernate's ability to enhance an applications domain model, the ways to perform that
|
|
||||||
enhancement and the capabilities introduced into the domain model by the enhancement.
|
|
||||||
|
|
||||||
== The capabilities
|
|
||||||
|
|
||||||
Hibernate will enhance the classes in an application's domain model in order to add one or more of the
|
|
||||||
following capabilities:
|
|
||||||
|
|
||||||
. Lazy state initialization
|
|
||||||
. Dirtiness tracking
|
|
||||||
. Automatic bi-directional association management
|
|
||||||
. Performance optimizations
|
|
||||||
|
|
||||||
todo : explain each in detail
|
|
||||||
|
|
||||||
|
|
||||||
== Performing enhancement
|
|
||||||
|
|
||||||
Ultimately all enhancement is handled by the `org.hibernate.bytecode.enhance.spi.Enhancer` class. Custom means to
|
|
||||||
enhancement can certainly be crafted on top of Enhancer, but that is beyond the scope of this guide. Here we
|
|
||||||
will focus on the means Hibernate already exposes for performing these enhancements.
|
|
||||||
|
|
||||||
=== Runtime enhancement
|
|
||||||
|
|
||||||
Currently runtime enhancement of the domain model is only supported in managed Jakarta Persistence environments following the Jakarta Persistence defined SPI for performing class transformations.
|
|
||||||
|
|
||||||
Even then, this support is disabled by default. To enable runtime enhancement, specify one of the following configuration properties:
|
|
||||||
|
|
||||||
`*hibernate.enhancer.enableDirtyTracking*` (e.g. `true` or `false` (default value))::
|
|
||||||
Enable dirty tracking feature in runtime bytecode enhancement.
|
|
||||||
|
|
||||||
`*hibernate.enhancer.enableLazyInitialization*` (e.g. `true` or `false` (default value))::
|
|
||||||
Enable lazy loading feature in runtime bytecode enhancement. This way, even basic types (e.g. `@Basic(fetch = FetchType.LAZY`)) can be fetched lazily.
|
|
||||||
|
|
||||||
`*hibernate.enhancer.enableAssociationManagement*` (e.g. `true` or `false` (default value))::
|
|
||||||
Enable association management feature in runtime bytecode enhancement which automatically synchronizes a bidirectional association when only one side is changed.
|
|
||||||
|
|
||||||
|
|
||||||
=== Build-time enhancement
|
|
||||||
|
|
||||||
Hibernate also offers the ability to integrate the enhancement of the domain model as part of the
|
|
||||||
normal build cycle of that domain model. Gradle, Ant and Maven are all supported. One possible benefit
|
|
||||||
of this approach is that the enhanced classes are what gets added to the jar and can then be used on both
|
|
||||||
sides of serialization.
|
|
||||||
|
|
||||||
=== Gradle Plugin
|
|
||||||
|
|
||||||
Hibernate provides a Gradle plugin that is capable of providing build-time enhancement of the domain model as they are
|
|
||||||
compiled as part of a Gradle build. To use the plugin a project would first need to apply it:
|
|
||||||
|
|
||||||
[[gradle-plugin-apply-example]]
|
|
||||||
.Apply the plugin
|
|
||||||
====
|
|
||||||
[source, GROOVY]
|
|
||||||
----
|
|
||||||
buildscript {
|
|
||||||
repositories {
|
|
||||||
mavenLocal()
|
|
||||||
mavenCentral()
|
|
||||||
}
|
|
||||||
dependencies {
|
|
||||||
classpath "org.hibernate:hibernate-gradle-plugin:5.1.0.Final"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
apply plugin: 'org.hibernate.orm'
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
At the moment there is not much to configure with regard to the Enhancer, but what is configurable is exposed through a DSL extension registered.
|
|
||||||
By default, enhancement will not be done (in preparation for when this Gradle plugin offers additional capabilities).
|
|
||||||
To enable it you must configure the following DSL extension:
|
|
||||||
|
|
||||||
[[gradle-plugin-apply-example]]
|
|
||||||
.Apply the plugin
|
|
||||||
====
|
|
||||||
[source, GROOVY]
|
|
||||||
----
|
|
||||||
hibernate {
|
|
||||||
enhance {
|
|
||||||
enableLazyInitialization= true
|
|
||||||
enableDirtyTracking = true
|
|
||||||
enableAssociationManagement = true
|
|
||||||
enableExtendedEnhancement = false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
Currently the "enhance" extension supports 4 properties:
|
|
||||||
|
|
||||||
* `enableLazyInitialization`
|
|
||||||
* `enableDirtyTracking`
|
|
||||||
* `enableAssociationManagement`
|
|
||||||
* `enableExtendedEnhancement`
|
|
||||||
|
|
||||||
Once enhancement overall is enabled, the default for the first 3 properties is `true`. Field access is not enhanced by
|
|
||||||
default, as it can potentially trigger enhancement of code outside the entities, and also because it assumes that all
|
|
||||||
the target entities are enhanced, which may not always be the case.
|
|
||||||
|
|
||||||
=== Maven Plugin
|
|
||||||
|
|
||||||
The Hibernate Maven plugin provides a convenient way to enhance the domain model at build-time when using Maven as the
|
|
||||||
build environment. Much like the Gradle plugin, the current bytecode enhancement capabilities that can be configured
|
|
||||||
on the plugin are:
|
|
||||||
|
|
||||||
* `enableLazyInitialization`
|
|
||||||
* `enableDirtyTracking`
|
|
||||||
* `enableAssociationManagement`
|
|
||||||
* `enableExtendedEnhancement`
|
|
||||||
|
|
||||||
Field access is not enhanced by default, because it can potentially trigger enhancement of code outside the entities.
|
|
||||||
Other capabilities are enabled by default. Even if the plugin is enabled, the bytecode enhancement can be bypassed by
|
|
||||||
disabling all the capabilities.
|
|
||||||
|
|
||||||
There is also a parameter `failOnError` that controls what happens in case of error. Default behavior is to fail the
|
|
||||||
build, but it can be set so that only a warning is issued.
|
|
||||||
|
|
||||||
To use the Hibernate Maven plugin on a build it must added to the model (pom.xml) along with other plugins that may be
|
|
||||||
already in use. The XML snippet below is an example of how to declare and configure the plugin.
|
|
||||||
|
|
||||||
[[maven-plugin-apply-example]]
|
|
||||||
.Apply the plugin
|
|
||||||
====
|
|
||||||
[source, XML]
|
|
||||||
----
|
|
||||||
<build>
|
|
||||||
<plugins>
|
|
||||||
[...]
|
|
||||||
<plugin>
|
|
||||||
<groupId>org.hibernate.orm.tooling</groupId>
|
|
||||||
<artifactId>hibernate-enhance-maven-plugin</artifactId>
|
|
||||||
<version>$currentHibernateVersion</version>
|
|
||||||
<executions>
|
|
||||||
<execution>
|
|
||||||
<configuration>
|
|
||||||
<failOnError>true</failOnError>
|
|
||||||
<enableLazyInitialization>true</enableLazyInitialization>
|
|
||||||
<enableDirtyTracking>true</enableDirtyTracking>
|
|
||||||
<enableAssociationManagement>true</enableAssociationManagement>
|
|
||||||
<enableExtendedEnhancement>false</enableExtendedEnhancement>
|
|
||||||
</configuration>
|
|
||||||
<goals>
|
|
||||||
<goal>enhance</goal>
|
|
||||||
</goals>
|
|
||||||
</execution>
|
|
||||||
</executions>
|
|
||||||
</plugin>
|
|
||||||
[...]
|
|
||||||
</plugins>
|
|
||||||
</build>
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
=== Ant Task
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -1,95 +0,0 @@
|
||||||
[[logging-guide]]]]
|
|
||||||
= Logging Guide
|
|
||||||
:toc:
|
|
||||||
|
|
||||||
Since version 4.0, Hibernate has used the JBoss Logging library for its logging needs. Like SLF4J and
|
|
||||||
Jakarta's commons-logging, JBoss Logging is a "logging bridge" providing integration with numerous logging
|
|
||||||
frameworks. JBoss Logging was chosen because of its i18n support and its support for "message ids". This is largely
|
|
||||||
the seminal documentation of JBoss Logging since JBoss Logging currently provides no documentation of its own.
|
|
||||||
|
|
||||||
|
|
||||||
== Supported Back-ends
|
|
||||||
|
|
||||||
JBoss Logging understands the following back-ends as first-class citizens:
|
|
||||||
|
|
||||||
. JBoss LogManager (mainly used only inside the WildFly app server)
|
|
||||||
. Log4j 2
|
|
||||||
. Log4j 1
|
|
||||||
. Slf4j
|
|
||||||
. JDK logging
|
|
||||||
|
|
||||||
Note the order above, it is important. By default JBoss Logging will search the ClassLoader for the availability of
|
|
||||||
classes that indicate one of the above "providers" being available. It does this in the order defined above. So,
|
|
||||||
for example, if you have both JBoss LogManager and Slf4j available your classpath then JBoss LogManager will be used
|
|
||||||
as it has the "higher precedence".
|
|
||||||
|
|
||||||
NOTE: Slf4j will only be auto-selected if Logback is in use.
|
|
||||||
|
|
||||||
This can sometimes lead to an unwanted logging set up to be used. In such cases, JBoss Logging provides for you to
|
|
||||||
tell it specifically which provider to use and circumvent the discovery process just described. It allows 2 different
|
|
||||||
mechanisms for this:
|
|
||||||
|
|
||||||
. First, JBoss Logging will look for a *System* setting with the key `org.jboss.logging.provider`, which can be set to
|
|
||||||
one of the following values:
|
|
||||||
|
|
||||||
* jboss
|
|
||||||
* jdk
|
|
||||||
* log4j2
|
|
||||||
* log4j
|
|
||||||
* slf4j
|
|
||||||
|
|
||||||
. Next, JBoss Logging will look for a JDK service (see javadocs for +java.util.ServiceLoader+ for details) for its
|
|
||||||
"provider" contract (+org.jboss.logging.Provider+). If multiple are available, it will use the first one returned by
|
|
||||||
the ClassLoader.
|
|
||||||
|
|
||||||
|
|
||||||
== Usage
|
|
||||||
|
|
||||||
Most of the time, the discovery process JustWorks. The discovery process relies on the jars available on the classpath.
|
|
||||||
The jboss-logging jar is a required dependency of Hibernate and therefore will always need to be on the classpath.
|
|
||||||
|
|
||||||
* To use JBoss Logging with Log4j, the log4j jar would also need to be available on the classpath.
|
|
||||||
* To use JBoss Logging with Log4j2, the log4j2 jar would also need to be available on the classpath.
|
|
||||||
* To use JBoss Logging with Slf4j, the slf4j-api jar would also need to be available on the classpath *plus* any needed
|
|
||||||
slf4j backend.
|
|
||||||
|
|
||||||
JDK Logging would be used if none of the other framework jars are available.
|
|
||||||
|
|
||||||
|
|
||||||
== Log Categories of Interest
|
|
||||||
|
|
||||||
It is recommended that you familiarize yourself with the log messages sent from Hibernate. A lot of work has been put
|
|
||||||
into making the Hibernate logging as detailed as possible, without making it unreadable. It is an essential
|
|
||||||
troubleshooting device. Some log categories of particular interest include:
|
|
||||||
|
|
||||||
.Hibernate Log Categories of Interest
|
|
||||||
|===
|
|
||||||
|Category|Description
|
|
||||||
|
|
||||||
|org.hibernate.SQL
|
|
||||||
|Log all SQL statements as they are executed with through JDBC
|
|
||||||
|
|
||||||
|org.hibernate.type.descriptor.jdbc
|
|
||||||
|Log all values as they are bound to JDBC parameters and extracted from JDBC results
|
|
||||||
|
|
||||||
|org.hibernate.tool.hbm2ddl
|
|
||||||
|Log all SQL DDL statements as they are executed during execution of any of the schema migration tools
|
|
||||||
|
|
||||||
|org.hibernate.pretty
|
|
||||||
|Log the state of all entities (max 20 entities) associated with the session at flush time
|
|
||||||
|
|
||||||
|org.hibernate.cache
|
|
||||||
|Log all second-level cache activity
|
|
||||||
|
|
||||||
|org.hibernate.hql.internal.ast.AST
|
|
||||||
|Log HQL and SQL ASTs during query parsing
|
|
||||||
|
|
||||||
|org.hibernate
|
|
||||||
|Log everything. This is a lot of information but it is useful for troubleshooting
|
|
||||||
|===
|
|
||||||
|
|
||||||
|
|
||||||
== Message Id Index
|
|
||||||
|
|
||||||
Coming soon.
|
|
||||||
|
|
||||||
Loading…
Reference in New Issue