schweizerischebundesbahnen / hibernate_hbm2annotation

What is this?

This script helps you to migrate bigger projects from hibernate hbm.xml files to annotations. It is able to migrate most common annotations automatically, but not all, meaning the complicated part will be up to you to do be done manually. It will just do the monkey work for you.

In our repository, we were able to automate about 90% of the work, but you may find that your codebase is different. We still encountered a lot of manual work, but if your code already follows hibernate best practices, it should be easier.

The Imports will be added but possibly not in the order as your IDE expects and a reformatting might be required.

Who did this?

• Heiko Henning @GreenRover
• Marius Schär @Martyschaer
• Christine Müller (no github account)
• Jean-Claude Brantschen @Clean-Coder
• Christoph Gächter @gaechtec
• Reto Weingart @rweingart

While migrating our own SBB codebase form hbm to annotations. The commit history has been squashed to hide sensitive information.

How to use this?

Check out the wiki for a detailed guide and best practices.

Setup

Copy config.dist.php to config.php and put the path to your java project into it.

To run you needs to use php >= 7.2

Important: after a branch switch, rm *.json before running the script. This makes sure the script knows about every file.

Usage

There are two commands analyse.php and migrate.php

migrate.php provides some cmd options. Please view code of this file to see them all.

Examples

$ php migrate.php --printWriteStats --hbmFilter="Betriebspunkt\.hbm"

The --hbmFilter option accepts PHP-Regex syntax and applies it to the .hbm.xml-paths.

When using the --hbmFilter option be sure to run at least two files that are next to eachother in the hierarchy at the same time. The generation of @AttributeOverride-annotations might otherwise not work properly.

$ php migrate.php --printWriteStats --collectUnsupportedAnnoationsFile="C:/devsbb/tmp/annotations_not.txt"

To add @Transient annotations to getters Hibernate should ignore

$ php migrate.php --addTransient

The Script will generate some TODOs where it knows it cannot complete the task automatically. Search for them after running the script by:

$ git diff --name-only | xargs grep -n -A1 "// TODO @HIB" | grep -vP "(:\d*:|--)"

Manual preparatory work

Move getId / setId and field to implementation class

If you hava any get / set in abstract classes, those needs to be moved, if you use a sequence generator.

https://vladmihalcea.com/how-to-combine-the-hibernate-assigned-generator-with-a-sequence-or-an-identity-column/

Also public abstract getId() is not allowed.

Caching

To improve the performce, this script will create two cache files, that can be deleted risk-free.

• hbms.json: A list of all *.hbm files found in your code base.
• class2fileCache.json: Classname to filepath map, even if the same simple class name was used multiple times.

hibernate_hbm2annotation's Issues

Script creates @Transient annotation on annotated methods with multiline @Formula

Describe the bug
A clear and concise description of what the bug is.

To Reproduce

  /**
   * @return someValue
  */
  @Column(name = "SOME_COLUMN")
  @Convert(converter = EntityIdConverter.class)
  @Formula("( SELECT MAX(bpmt.id)" //
      + " FROM bp_children bpmt" //
      + " WHERE bpmt.idt_bp = 30")
  @Transient // this shouldn't be here
  public DunoEntityId getAnzeige() {
    return this.anzeige;
  }

Expected behavior:
The transient is not generated.

Additional context
This is probably due to the script dismissing the >1 lines of the @formula annotation as non-annotations.

Script should generate imports based on what annotations actually say.

Example: a @DiscriminatorColumn annotation causes the following imports:

import javax.persistence.DiscriminatorColumn;
import javax.persistence.DiscriminatorType;

even when no DiscriminatorType is used. This isn't a huge deal, but would be nice to have.

Cannot run command - cannot require files

Describe the bug

When running application I got a require_once error.

To Reproduce

I run the following command on an ubuntu 18.04 system with php 7.2 :

cd /root/git/
git clone https://github.com/SchweizerischeBundesbahnen/hibernate_hbm2annotation
cd hibernate_hbm2annotation
php migrate.php

Then I got the following error :

PHP Warning:  require_once(/root/git/hibernate_hbm2annotation./Hbm/Converter.php): failed to open stream: No such file or directory in /root/git/hibernate_hbm2annotation/migrate.php on line 2

Expected behavior:

The command shall run without error.

By inspecting the code I see that the line 2 is require_once __DIR__ . './Hbm/Converter.php'.

That will lead to be evaluated to '/root/git/hibernate_hbm2annotation' . './Hbm/Converter.php' as described in the error.

As described in the php manual, __DIR__ won't add a slash at the end except when in / root directory.

See http://php.net/manual/en/language.constants.predefined.php.

Do I miss a configuration tip?

`--migrateHbmToClassRegistration` doesn't work in some cases.

Worked fine for one of your activators, but didn't for another.

Script should generate import in activatorFiles automatically.

Describe the solution you'd like
The imports should automatically be generate when the --migrateHbmToClassRegistration is used.

Script should emit warnings when encoutering getters/setters with `final` keyword.

Hibernate won't tolerate the property methods being final. The script should emit a warning.

Nice to have: given an option like --removeFinals the script should automatically remove finals from the property methods.

Improve @AttributeOverride detection.

Improve the detection of inherited attributes to abolish the workaround of generating multiple classes that are next to one-another in the hierarchy.

Example:
Instead of this

php migrate.php --printWriteStats --addTransient --hbmFilter=".*transfer.*(ISSPStreckenGleis|ISSPAufnahmeGebaeude|ISSPHauptGleis)\.hbm"

it should be possible to only run

php migrate.php --printWriteStats --addTransient --hbmFilter=".*transfer.*(ISSPStreckenGleis)\.hbm"

while achieving the same results for the ISSPStreckenGleis-class.

Script doesn't generate all required @AttributeOverrides correctly.

Reproduce:

php migrate.php --printWriteStats --addTransient --hbmFilter=".*transfer.*(ISSPStreckenGleis|HgbpDarstellungseigenschaften)\.hbm"

Issue: ZBV_ID and ZBE_ID aren't in @AttributeOverrides

Script generates import for ch.sbb.aa.... in unrelated classes.

Reproduce:

  php migrate.php --printWriteStats --addTransient --hbmFilter=".*fahrplan.*(FaG|AbschnittsFormation)\.hbm"
  php migrate.php --printWriteStats --addTransient --hbmFilter=.*transfer.*(ZnTelegramm)\.hbm"
  php migrate.php --printWriteStats --addTransient --hbmFilter=".*transfer.*(ZnTelegramm)\.hbm"

Script generates @Access incorrectly

Reproduce:

php.exe migrate.php --addTransient --printWriteStats --hbmFilter=".*transfer.*(WapCodepunkt|AngemeldeteEndgeraeteInfo)\.hbm\.xml" --migrateHbmToClassRegistration

Issue:
Generates @Access(AccessType.FIELD) on property getLsCodepunktId().

Many to one relation translated to one to one relation

Describe the bug
When converting a bean with many to one associations, they are translated to one to one translations. When using Dali tool (from eclipse) from data model, it is understood as many to one.

To Reproduce

myclass1.hbm

<hibernate-mapping package="fr.test">

  <class name="MyClass1" table="my_class1">


    <many-to-one name="myRelation" class="fr.test.MyClass2" cascade="save-update,delete">
        <column name="myRelationColumn" unique="true" not-null="true" />
    </many-to-one>

I'll try to provide a small github to reproduce.

I think it would be nice to unit test it.
I'll keep you in touch.

Expected behavior:
The relational shall be many to one.