So könnte z.B. die Entity Bean “User” wie folgt aussehen:

@Entity
public class User {

  @Id
  private Long id;

  @Length(min = 5, max = 50)
  @Pattern(regex="[a-zA-Z0-9]+")
  @NotNull
  private String name;

  @Email
  @NotNull
  private String email;

  @Past
  private Date birthday;

  // Getter & Setter
}

Der Hibernate Validator arbeitet auf zwei Ebenen mit den Constraints. Zum einen die für Anwendungen sehr hilfreiche Funktion des “In-Memory-Checks” für Instanzen. In diesem Fall wird noch vor der eigentlichen Datenbank Operation gegen die konfigurierten Constraints geprüft. Zum anderen können ein paar Hibernate Constraints direkt in das Datenbankschema übernommen und somit noch einmal von der Datenbank selbst geprüft werden.

Im folgenden noch die Tabelle aller vordefinierten Hibernate Validation Annotationen:

Mit diesem Set an Hibernate Annotationen dürfte man die normalen und häufigsten Anforderungen an die Validierung erfüllt werden. Das mächtigste Constraint dürfte die @Pattern(regex="") sein, die man mit regulären Ausdrücken befüllen kann.

Als letzte Information in diesem Artikel noch der Hinweis, dass für jede Hibernate Annotation ein Standardfehlertext existiert, der aber angepasst werden kann. So kann jede gesetzte Annotation mit einer eigenen Fehlermeldung versehen werden. Dafür dient das Attribut message und wird in der Exception oder dem InvalidValue Objekt bei einer Constraint Verletzung gesetzt. Hier noch ein Beispiel für das Verwenden von Nachrichten:

  @Length(min = 5, max = 50, message="Username muss zwischen 5 und 50 Zeichen lang sein")
  private String name;

  @Past(message="Der Geburtstag muss in der Vergangenheit liegen")
  private Date birthday;

Natürlich kann auch internationalisiert werden. Dazu einfach eine ValidatorMessages.properties bzw. ValidatorMessages_de.properties erstellen und im Classpath ablegen und die entsprechenden keys anpassen oder eigene erstellen:

Und in der Klassen dann die Keys mit geschweiften Klammern verwenden:

  @Length(min = 5, max = 50, message="{usernameLength}")
  private String name;

  @Past(message="{bdayPast}")
  private Date birthday;

Selbst wenn man die Validierung noch nicht im Frontend eingebaut oder in der Anwendung verwendet lohnt es sich diese in der Entity Bean zu konfigurieren. Neben den direkt im Datenbankschema eingebauten Constraints dient es bei der Entwicklung und Verwendung der Entity Beans absolut der Übersicht und zentralisiert die Vorgaben der Validierung.

Entity Bean mit JPA Annotationen	Dazugehöriges SQL Schema für diese Entity Bean

Meistens bringen die verschiedenen JPA Implementierungen eigene Tools mit. Verwendet man z.B. Hibernate kann man zum Beispiel die von Konsole Tools in Form eines ANT Tasks verwenden. Arbeitet man mit der Eclipse Ganymede IDE hat man mit dem Web Tools Subprojekt “Dali” (Dali JPA Tools) die Möglichkeit sich das DB Schema mit Hilfe eines Eclipse Dialogs generieren zu lassen. Ich habe schon mal bei der Vorstellung der JBoss Tools 3 Alpha Version darauf hingewiesen, dass das WTP Dali Projekt ab Version 3 unterstützt wird.

Nachdem ich diesen Artikel in der ausführlichen Version erstellt hatte kam mir dieser mehr doch sehr lang vor obwohl das Konfigurieren an sich relativ schnell geht. Dahier hier die wenigen Schritte in absoluter Kurzform:

• Projekt Facet “JPA Persistence” dem EJB Projekt hinzufügen (Projekt Properties)
• JPA Plattform und DB Verbindung konfigurieren (Projekt Properties)
• Im Cotextmenü auf dem EJB-Projekt “JPA-Tools->Generate DDL…” wählen
• Im DDL Generation Dialog das Zielverzeichnis, die Ausgabedatei und Hibernate Console- (konfigurierbar über die Hibernate Perspektive) oder DB-Konfiguration angeben. Dialog mit “Finish” beenden -> DDL Datei wird erstellt.

Im Folgenden wird anhand meines kleinen Java Schnipsel Projektes gezeigt wie das Datenbankschema, genauer gesagt die DDL (Data Definition Language) Datei, mit Eclipse generiert werden kann. Dieses Projekt verwendet Hibernate und somit werden aus den JBoss Tools Plugins das Hibernate Tools Eclipse Plugin benötigt. Nun sind die JBoss Tools 3.0.0 endlich offiziell Stable erschienen und da ist es an der Zeit dieses Feature mal auszuprobieren.

Im ersten Schritt sollte überprüft werden ob die Hibernate Tools installiert sind. Aus den JBoss Tools Eclipse Plugins wird für das Generieren der DDL Datei die Hibernate Tools benötigt. Für eine Installationsanleitung der JBoss Tools siehe hier.

Mein Beispielprojekt ist in der für Eclipse normalen JEE Projektstruktur erstellt worden (mit dem Seam Web Project Wizzard):

Hat man eine solche Projektstruktur muss man nun das JPA Project Facet hinzufügen. Dazu auf dem EJB Projekt aus dem Context Menü (recht Maustaste) “Properties” aufrufen. Im Properties Dialog “Project Facets” selektieren und dort das Facet “Java Persistence” auswählen:

Wenn das Facet “Java Persistence” selektiert wurde erscheint unten im gelben Hintergrund der Hinweis, dass weitere Konfigurationsmöglichkeiten bestehen (“Further configuration available”). Am einfachsten ist es diese Konfiguration direkt auszuwählen. Hat man die Einstellung mit “Apply” bestätigt einfach das Facet noch einmal deslektieren, Apply drücken und das Facet wieder selektieren.
In dem Dialog “Modify Facet Project -> JPA Facet” muss nun die verwendete JPA Platform und die DB Verbindung konfiguriert werden. Ich verwende Hibernate und habe meine MySQL Verbindung konfiguriert. Man kann direkt von diesem Dialog aus eine neue DB Verbindung konfigurieren, sofern man das noch nicht getan hat.

Die zwei weiteren dort möglichen Einstellungen habe ich bei mir auf “Use implementation provided by server Runtime” (Die Server Runtime kann in den Properties unter dem Punkt “Targeted Runtimes” konfiguriert werden – verwendet man keinen Server wie den JBoss kann man die JPA Jars auch direkt angeben) und “Discover annotated classes automatically” gesetzt. Anschließend den JPA Facet Dialog und anschließend den Properties Dialog mit “Ok” beenden.

Hat man allerdings den Properties Dialog schon vor den zusätzlichen JPA Einstellungen mit “Ok” beendet muss man noch einmal die Properties für das EJB Projekt aufrufen und kann dann aber den Menüpunkt “JPA” direkt selektieren und somit konfigurieren:

Nachdem die Java Persistence Project Facets dem JEE Projekt hinzugefügt wurden ist im Context Menü, sofern man dieses auf dem EJB Projekt aufruft, der Eintrag “JPA Tools” zu finden. Darin findet sich der Menüpunkt “Generate DDL”.

Erhält man nach dem Auswählen dieses Menüpunktes den Fehler “DDL Generation is not supported by the Generic Platform” hat man vergessen seinen JPA Platform (Hibernate, Toplink, ..) zu konfigurieren. Dazu einfach wieder in die EJB Projekt Properties und den Menüpunkt “JPA” selektieren und konfigurieren. Mehr Informantionen zu dieser Fehlermeldung auch hier.
Ist alles soweit korrekt konfiguriert öffnet sich der DDL Generation Dialog. Darin gibt man zuerst das Zielverzeichnis sowie den Namen der DDL Datei an. Die zweite wichtige Konfiguration ist der Hibernate Dialekt der verwendet werden soll. Dazu kann man entweder eine bereits durch die Hibernate Perspektive erstellte Hibernate Console Konfiguration verwenden und diese mit der Checkbox “Use Console Konfiguration” verwenden oder wie in meinem Fall die bereits konfigurierte Datenbankverbindung. Der Dialekt kann dabei automatisch erkannt werden (ich berichtete darüber) oder direkt angeben:

Ist alles korrekt konfiguriert wird durch den Button “Finish” das Generieren der DDL in der gewünschten Zieldatei gestartet. Das kann einen kleinen Moment dauern und anschließend ist diese Schemadatei auch unter der gewünschten Position (bei mir im EJB-Projekt im Ordner ejbModule) zu finden:

Gerade für die erste Entwicklungszeit und dem Erstellen der Entitäten ist diese einfach DDL Generierung sehr nützlich. Sieht man doch direkt was für Datenbanktypen aus den Java Attributen erstellt werden.

Alternativ kann man mit den Hibernate Tools über die Hibernate Perspektive das Schema auch direkt in der DB erstellen. Vor gut einem Jahr habe ich dazu einen kleinen Artikel erstellt.

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
  version="1.0">

  <persistence-unit name="MyEJBApp">
    <provider>org.hibernate.ejb.HibernatePersistence</provider>
    <jta-data-source>java:/MyEJBAppDatasource</jta-data-source>
    <properties>
      <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>
      <property name="hibernate.hbm2ddl.auto" value="validate"/>
      <property name="hibernate.show_sql" value="true"/>
      <property name="hibernate.format_sql" value="true"/>
    </properties>
  </persistence-unit>
</persistence>

Der interessante Punkt ist die Angabe des Hibernate Dialekts. Dieser wird mit dem Schlüsselwort hibernate.dialect konfiguriert:

<property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>

Es werden von Hibernate relativ viele Dialekte angeboten, so dass eine breite Unterstützung für die verschiedenen Datenbanken besteht. Unter den Angebotenen sind die üblichen Verdächtigen wie z.B.

• DB2 (org.hibernate.dialect.DB2Dialect)
• PostgreSQL (org.hibernate.dialect.PostgreSQLDialect)
• MySQL (org.hibernate.dialect.MySQLDialect)
• Oracle (org.hibernate.dialect.OracleDialect)
• Sybase (org.hibernate.dialect.SybaseDialect)
• MS SQL Server (org.hibernate.dialect.SQLServerDialect)
• HSQLDB/HypersonicSQL (org.hibernate.dialect.HSQLDialect)
• Derby (org.hibernate.dialect.DerbyDialect)

und noch einige andere.

Was ich bisher nicht wusste ist, dass die Angabe des Dialektes optional ist. Lässt man die Angabe weg versucht Hibernate die korrekte Implementierung von org.hibernate.dialect.Dialect anhand der JDBC Metadaten herauszufinden die vom JDBC Treiber zurückgegeben/geliefert werden.
Für die gängigsten Datenbanken sollte es somit kein Problem sein den Dialekt einfach wegzulassen. Der große Vorteil an dieser Stelle wäre, dass man tatsächlich ein EAR relativ unabhängig von der Datenbank ausliefern könnte. Entscheidet man sich für das weglassen sollte man zumindest den Hibernate Konfigurationsparamater auf validate setzen um eine DB Schemavalidierung beim Starten der Anwendung zu haben.

<property name="hibernate.hbm2ddl.auto" value="validate"/>

Stimmt etwas mit dem für den dynamisch gefundenen Datenbankdialekt das Schema nicht würde zumindest eine Exception geworfen werden.

Nachlesen kann man das in der offiziellen Hibernate Dokumenation im Kapitel 3.4 unter “Optional configuration properties”. Gleich der erste beschriebene Parameter ist der hibernate.dialect.
In Kapitel 3.4.1, weiter unten auf dieser Seite, sind zudem alle implementierten Dialekte aufgelistet.

21:10:03,406 INFO  [STDOUT] Hibernate:
    insert
    into
        REGISTERED_USER
        (version, NAME, USER_TYPE, CONF_FK, id)
    values
        (?, ?, ?, ?, ?)

Das für den Entwickler eigentlich interessante, nämlich die Parameter in der values Zeile, wird wegen der Verwendung von Prepared Statements nur durch Fragezeichen ausgegeben.

Die allgemein gültige Lösung dafür ist das Log Level für Hibernate Kategorie org.hibernate.type auf TRACE zu setzen. In einer log4j.properties Datei reichen die folgenden beiden Angaben um die SQL Statements sowie deren Paramter im Log auszugeben:

Arbeitet man mit der log4j.xml Konfigurationsdatei muss man die Kategorie wie folgt konfigurieren:

<category name="org.hibernate.type">
  <priority value="TRACE"/>
  <appender-ref ref="CONSOLE"/>
</category>

Die Kategorie org.hibernate.SQL muss man nicht unbedingt konfigurieren wenn man in der Hibernate Konfiguration, die bei der Nutzung von JPA in der Datei persistence.xml zu finden ist, den Parameter hibernate.show_sql auf true setzt:

<property name="hibernate.show_sql" value="true"/>

Überschreibt man die in der log4j Konfiguration die Kategorie org.hibernate.SQL hat diese Einstellung in der persistence.xml keine Wirkung.

Arbeitet man mit JBoss Seam unter dem JBoss AS verhält es sich grundsätzlich genauso wie oben beschrieben:

• Konfiguration des show_sql Flags auf den Wert true in der persistence.xml
• Die Log4J Konfiguration für Hibernate erweitern: Im JBoss AS Installationsordner unter <JBossAs>\server\default\conf die Datei jboss-log4j.xml editieren und die Hibernate Kategorie org.hibernate.type wie oben beschrieben hinzufügen

Da hier das Log Level auf TRACE gesetzt wird muss man das Level für den Appender auch auf TRACE setzen um den entsprechenden Effekt zu erhalten. Es ist nicht unbedingt ratsam den Default Appender, hier CONSOLE auf TRACE zu setzen weil sonst alle für diesen Appender konfigurierten Kategorien viel und laut sprechen.
Es bietet sich stattdessen an einen eigenen Hibernate Appender zu erstellen und nur diesen auf TRACE zu setzen. Bei mir sieht die jboss-log4j.xml für Hibernate wie folgt aus. Zuerst der Hibernate Appender:

<appender name="HIBERNATE" class="org.apache.log4j.ConsoleAppender">
  <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
  <param name="Target" value="System.out"/>
  <param name="Threshold" value="TRACE"/>

  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/>
  </layout>
</appender>

Die Hibernate org.hibernate.type Kategorie Konfiguration:

<category name="org.hibernate.type">
  <priority value="TRACE"/>
  <appender-ref ref="HIBERNATE"/>
</category>

Eigentlich ziemlich simpel.

Führt man nun das am Anfang beschriebene SQL Statement nochmal aus ist auf der Konsole folgendes zu sehen:

21:30:11,756 INFO  [STDOUT] Hibernate:
    insert
    into
        REGISTERED_USER
        (version, NAME, USER_TYPE, CONF_FK, id)
    values
        (?, ?, ?, ?, ?)
21:30:11,756 TRACE [IntegerType] binding '0' to parameter: 1
21:30:11,756 TRACE [StringType] binding 'Markus' to parameter: 2
21:30:11,756 DEBUG [EnumType] Binding 'ADMIN' to parameter: 3
21:30:11,756 TRACE [LongType] binding '41' to parameter: 4
21:30:11,756 TRACE [LongType] binding '41' to parameter: 5

Und kaum hat man diese wenigen Konfigurationselemente hinzugefügt spricht Hibernate schon eine viel deutlichere und schönere Sprache für uns.

Die Hibernate Tools sind eine Menge von Tools für Hibernate 3 und können in Eclipse als Plugins oder als Ant Tasks verwendet werden. Dabei sind die Hibernate Tools eine Hauptkomponente der JBoos Tools und somit werden sie auch von JBoss angeboten.

Dieser Artikel behandelt nur die Hibernate Tools als Eclipse Plugin und ist in die folgenden Abschnitten unterteilt:

• Installation des Hibernate Tools Eclipse Plugin
• Erstellen einer Hibernate Konfiguration
• Datenbankschema erstellen/aktualisieren
• Java Persistence Query Statements ausführen und testen
• Fazit

Die einfachste Möglichkeit die Hibernate Tools als Eclipse Plugin zu installieren ist über den Eclipse Update Manager (Help->Software Updates->Find and Install->Search for new features to install). Dort die JBoss Tools Update Seite (http://download.jboss.org/jbosstools/updates/stable/) hinzufügen.

Feature “Hibernate Tools” selektieren und Installation starten. Dazu einfach den Anweisungen folgen.

Die JBoss Tools können natürlich auch manuell heruntergeladen werden.

Nach der Installation steht die Hibernate Tools Perspektive zur Verfügung. In dieser Perspektive wird eine Hibernate Konfiguration erstellt. Diese Hibernate Konfiguration benötigt eine Hibernate Konfigurations Datei um die Container spezifischen Konfigurationen aus der persistence.xml zu überschreiben.

Diese Hibernate Konfigurations Datei, bei mir heißt sie “hibernate-tools.properties“, kann irgendwo im Projekt angelegt werden und muss muss folgenden Inhalt habe:

hibernate.connection.username=deinMySQLUser
hibernate.connection.password=deinMySQLPw
hibernate.connection.driver_class=com.mysql.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MySQLInnoDBDialect
hibernate.connection.url=jdbc:mysql://localhost/openwishes

hibernate.connection.provider_class=org.hibernate.connection.DriverManagerConnectionProvider

Natürlich sollten noch passende und gültige Daten angegeben werden. Dieses Beispiel bezieht sich auf meine lokale OpenWishes MySQL Datenbank.

Als zweites wird noch eine persistence.xml im Classpath benötigt. Und zwar muss diese Datei, die genau diesen Namen haben muss, im Ordner /META-INF liegen. Auch wenn diese Datei keine wirklichen Konfigurationen enthält, so verlangen die Hibernate Tools für die Erstellung einer Hibernate Konfiguration eben eine /META-INF/persistence.xml im Classpath. Am besten erstellt man sich den /META-INF Ordner im Source Verzeichnis.

Sind diese beiden Dateien vorhanden muss in die Hibernate Perspektive gewechselt und eine neue Hibernate Konfiguration erstellt werden. Dazu mit der rechten Maustaste auf den Hintergrund im Reiter “Hibernate Configurations” und “Add Configuration…” wählen.

Bei der Konfiguration muss als Typ “JPA” gewählt sowie das Projekt und die vorher erstellte Hibernate Konfigurationsdatei selektiert werden. Der Name kann frei bestimmt werden.

Das ganze mit OK abschließen und die Konfiguration ist erstellt. Bei Fehlern in der Konfiguration erscheinen die Meldungen der aufgetretenen Exception(s) in dem Error Log Panel. Leider wird man aus diesen oft nicht wirklich schlau daher lieber noch einmal die Erreichbarkeit der Datenbank, die angegeben Daten auf Korrektheit und die Verfügbarkeit des Treibers im Classpath prüfen um das schon einmal auszuschließen.

Wenn aber alles in Ordnung ist kann nun die neu angelegte Konfiguration aufgeklappt und zwischen den drei Auswahlmöglichkeiten “Configuration”, “Session Factory” und “Database” gewählt werden. Für einen ersten Test kann z.B. der “Configuration” Zweig aufgeklappt werden und man müsste alle im Projekt konfigurierten Entitäten aufgelistet sehen. Mit einem Doppelklick auf die Entität gelangt man in die entsprechende Java Klasse.

Ist man noch in der Entwicklung des Domain Modells und muss häufig das Datenbank Schema aktualisieren so ist das mit den Hibernate Tools eine Sache von Sekunden.
Nach der Änderung einer Entität (Klassen mit der @Entity Annotation) muss die Hibernate Konfiguration aktualisiert werden. Das erreicht man aus dem Kontextmenü (rechte Maustaste) auf den “Configuration Zweig” der eingerichteten Konfiguration und der Anweisung “Refresh”. Anschließend im Kontextmenü der Hibernate Konfiguration den Menüpunkt “Run ShemaExport” aufrufen und nach einer erneuten Bestätigung wird das Datenbankschema erneut erstellt.

An dieser Stelle sollte man natürlich vorsichtig sein, denn bereits in der Datenbank vorhandene Datensätze sind natürlich anschließend nicht mehr vorhanden.

Passend dazu ist ein weiteres sehr schönes Feature die grafische Darstellung des Mappings zwischen einer Entität und der Datenbanktabelle. So kann man das eben erstellte Schema ansehen und man könnte diese Darstellung auch ohne weiteres in eine Dokumentation übernehmen.
Diese Darstellung kann auch aus dem “Configuration” Zweig heraus aus geöffnet werden. Einfach mit der rechten Maustaste auf eine Entität klicken und “Open Mapping Diagram” selektieren.

Das meiner Meinung nach nützlichste Feature (neben der schnellen Aktualisierung des DB Schemas) ist das Austesten und schnelle Ausführen von Java Persistence Query (JPQ) Statements; bei Hibernate auch Hibernate Query Language (HQL) genannt und bei JEE unter dem Stichwort Enterprise Java Beans Query Language (EJB-QL) zu finden.
Den HQL Editor öffnet man aus dem Kontextemü heraus aus. In dem HQL Editor muss man noch die gewünscht Hibernate Konfiguration selektieren und kann noch die Treffermene reduzieren.
Nach dem Eingeben der Hibnerate Query und dem Ausführen, gestartet durch den grünen Pfeil oben links, erscheint in dem “Hibernate Query Result” Panel das erzielte Ergebnis. In dem dazugehörigen Properties Panel erscheinen die geladenen Daten einer einzelnen selektierten Entität. In dem Screenshot kann man sehen, dass selbst Objekte die als Referenz in der selektierten Entität bestehen mit geladen werden. In diesem Fall ist es die Entität “Item”.

Kleiner Hinweis: das Ergebnispanel öffnet sich nicht automatisch bei einer Änderung des Inhalts und es muss somit manuel selektiert werden, wenn man sich gerade in einem anderen Panel, wie zum Beispiel dem “Error Log” Panel befindet.

Bei einem HQL Fehler wird man natürlich auch wie bei einem SQL Statement darauf hingewiesen.

Ein weiteres sehr schönes Feature ist zu sehen was aus seinem HQL Statement in SQL gemacht wird, denn das größte Problem der bequemen Datenbankabfragen mit Hilfe der JPQ Statements ist die Performance. Oft werden so viele JOINS und Subselects gemacht, dass es sich aufgrund der Performance nicht lohnt ein solches Statement abzusetzen. Aber dazu sollte man natürlich wissen was Hibernate aus den HQL Statements für SQL Statements erstellt. Und genau diese Antwort liefert das “Hibernate Dynamic SQL Preview” Panel.

Die Hibernate Tools sind für die Entwicklung mit JPA eine wirklich wertvolle Unterstützung. Es ist möglich bei der Entwicklung des Domain Modells das Datenbank Schema schnell und unkompliziert zu erstellen bzw. anzupassen und das Mapping zwischen den Entitäten sowie den Tabellen mit grafischer Unterstützung zu untersuchen.
Für HQL bzw. EJB-QL Statements bietet der HQL Editor eine sehr praktische und schnelle Möglichkeit das Statement auf Korrektheit und gewünschtes Ergebnis zu überprüfen.

Auch wenn man nicht mit JPA sondern noch mit den Hibernate XML Files arbeitet bieten das Hibernate Tools Plugin eine wertvolle Erweiterung wie z.b. das Autocomplete im hbm.xml Editor.

Insgesamt kann ich das Plugin absolut empfehlen weil es die Arbeit doch sehr erleichtert, wie wir bei der Entwicklung von OpenWishes oft feststellen konnten.

Für Anmerkungen steht natürlich die Kommentarfunktion zur Verfügung.