How to bootstrap Hibernate without the persistence.xml file

(Last Updated On: January 29, 2018)


JPA relies heavily on the persistence.xml configuration file, and the standard API to bootstrap a JPA provider programmatically requires too much boilerplate code. While in a typical enterprise application, providing a persistence.xml file is not really an issue, this requirement doesn’t get along with unit testing, especially when tests are completely isolated and they need to validate different aspects of JPA or Hibernate.

That was an issue that I bumped into when writing test cases for the High-Performance Java Persistence book. All my tests need to be isolated, and not all of them share the same settings or entities.

In my case, using a single persistence.xml file was definitely out of the question because any change would have a rippling effect throughout the whole test suite.

Hibernate to the rescue

Hibernate is awesome. It allows you do build an EntityManagerFactory completely programmatically and with few lines of code:

protected EntityManagerFactory newEntityManagerFactory() {
    PersistenceUnitInfo persistenceUnitInfo = 
    Map<String, Object> configuration = new HashMap<>();

    return new EntityManagerFactoryBuilderImpl(
            new PersistenceUnitInfoDescriptor(
                persistenceUnitInfo), configuration

protected PersistenceUnitInfoImpl persistenceUnitInfo(
    String name) {
    return new PersistenceUnitInfoImpl(
        name, entityClassNames(), properties()

Each test starts with some reasonable default properties, and entities must be provided on a per-test basis.

protected Properties properties() {
    Properties properties = new Properties();
    DataSource dataSource = newDataSource();
    if (dataSource != null) {
    return properties;

protected List entityClassNames() {
    return Arrays.asList(entities())

protected abstract Class[] entities();

A test can define its own settings and entities, and, this way, we can encapsulate the entire environment.

protected Class<?>[] entities() {
    return new Class<?>[] {

@Entity(name = "Patch")
public class Patch {

    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    @OrderColumn(name = "index_id")
    private List<Change> changes = new ArrayList<>();

    public List<Change> getChanges() {
        return changes;

public class Change {

    @Column(name = "path", nullable = false)
    private String path;

    @Column(name = "diff", nullable = false)
    private String diff;

    public Change() {

    public Change(String path, String diff) {
        this.path = path;
        this.diff = diff;

    public String getPath() {
        return path;

    public String getDiff() {
        return diff;

If you enjoyed this article, I bet you are going to love my Book and Video Courses as well.


This technique is not something new. The Spring framework LocalContainerEntityManagerFactoryBean can also be configured without an actual peristence.xml file.

Subscribe to our Newsletter

* indicates required
10 000 readers have found this blog worth following!

If you subscribe to my newsletter, you'll get:
  • A free sample of my Video Course about running Integration tests at warp-speed using Docker and tmpfs
  • 3 chapters from my book, High-Performance Java Persistence, 
  • a 10% discount coupon for my book. 
Get the most out of your persistence layer!


12 thoughts on “How to bootstrap Hibernate without the persistence.xml file

  1. Hi Vlad. This post is very interesting.

    I’m developing a Java EE 7 application that have to access to multiple datasources that share the same object structure (tables, sequences, stored procedures) and I think that the better way to add new datasources without the need of touch the persistence.xml file is through the method described here. In the shared code there a concrete class named PersistenceUnitInfoImpl that implements the PersistenceUnitInfo interface, ¿Do you have a code example with that implementation or can you refer me some Internet resource?


      1. Thank’s vlad,

        I will review your class to give you the corresponding feedback.

        Very very thanks!!

      2. Hi Vlad.

        Sorry for the late answer. I implemented the corresponding components to the proposed model and my technical problem was fixed with success, I am thankful for your kind and valuety help.

  2. That has really been some of the biggest pain points for me with JPA (and other Java EE stuff). Why can’t I just set up my environment programmatically with only a couple of lines of code?

    Great share, thanks!

  3. As you might know, since you are using implementations of that interface, there is an SPI( for bootstrapping JPA without a persistence.xml. It’s intended for containers, thus the name of the create method(,%20java.util.Map%29), but if you need to bootstrap that with custom settings, I would dare to say that counts as being container-like.
    This works for all JPA providers as that is the main integration point for all Java EE containers so it’s not really special to hibernate 😉

      1. Well it does work. I’ve done it a few times and Spring does it too. I don’t see how the hibernate API gives you “better control” although I agree it’s much more convenient to just use that instead of having to understand and implement the big PersistenceUnitInfo interface yourself.

Leave a Reply

Your email address will not be published. Required fields are marked *