v 1.004 TLGen Ejb3 Code-Generator Authors: Titus Livius Rosu (tituslivius.rosu@stardata.eu) Titus Rosu (titus.rosu@stardata.eu) Table of Contents 1. Allgemeine Information 4 1.1 Ziele ............................................................................................................................4 1.2 Inhalt vom Download ..................................................................................................5 2. Generierte Code-Struktur 6 2.1 Package(Ordner)-Struktur vom generiertem Code........................................................7 3. Code Generierung 8 3.1 Was wird generiert? ....................................................................................................8 3.2 Regeln der Daten-Beschreibung...................................................................................8 3.2.1 Platzhalter für die Namen 8 3.2.2 Generierte Namen der Tabellen 8 3.3 Beschreibung der Konfigurationsdatei zur Steuerung der Generierung .........................8 3.3.1 9 3.3.2 9 3.3.3 10 3.3.3.1 10 3.3.3.2 10 3.3.3.3 11 3.3.3.3.1 11 3.3.3.4 12 3.3.3.4.1 12 3.3.3.4.2 13 3.3.3.4.2.1 13 3.3.3.4.3 13 3.3.3.4.3.1 14 3.3.3.4.4 14 3.3.3.5 14 3.3.3.5.1 15 3.3.3.5.2 15 3.3.3.5.2.1 15 3.3.3.5.2.2 16 3.3.3.5.2.2.1 16 3.3.3.5.3 16 3.3.3.6 17 3.3.3.6.1 17 3.3.3.6.2 17 3.3.3.7 18 3.3.3.8 18 3.3.3.8.1 19 3.3.3.8.2 , 19 3.3.3.9 19 3.3.3.10 19 3.4 Beschreibung der Build-Datei für TLGen ..................................................................... 20 TLGen 2 StarData GmbH Table of Contents 4. Installation von TLGen 22 4.1 Verwendete Tools und externe Programme ............................................................... 22 4.2 Beispiel...................................................................................................................... 22 4.3 Installation ................................................................................................................ 22 4.3.1 Datenbank einrichten 23 4.3.2 JBoss Application Server einrichten 23 4.3.3 Programm in Eclipse laden 23 4.3.4 TLGen Testen 24 5. Pläne für die nachfolgenden Versionen 26 6. Anhang: Literaturhinweise 27 TLGen 3 StarData GmbH v 1.004 1. Allgemeine Information TLGen ist ein Java Code Generator auf Basis von EJB3, um den gesamten Backend einer Applikation vollständig zu generieren In Kapitel zwei wird die generierte Code-Struktur beschrieben, welche die Projektarchitektur gestaltet. Dieser Aufbau der Ordner-Struktur ist möglich über die Konfigurationsdatei. In Kapitel drei wird die Verwendung der Konfigurationsdatei anhand von Beispielen möglicher Code-Generierungsvarianten erläutert. Im letzten Kapitel (vier) wird die Installation und Verwendung von TLGen in Projekten beschrieben. Dort wird auch im Detail das mitgelieferte Beispiel erläutert. 1.1 Ziele TLGen ist ein Java Code Generator auf Basis von EJB3. Ziel unserer Arbeit war es, Kosten für die Backend-Softwareentwicklung zu sparen. Für die komplette Code-Generierung mit Hilfe von TLGen ist nur eine Datenbank und eine Konfigurations-Datei (in XML) notwendig. Letztere übernimmt die Steuerung der Code-Generierung. Das Datenbankmodell sollte, wenn möglich, mind. in der 3. Normalform vorliegen. (s. auch http://de.wikipedia.org/wiki/Normalisierung_%28Datenbank%29) Die Normalisierung ist ein wichtiges Hilfsmittel, um die Konsistenz der Daten zu gewährleisten. Das erleichtert die Wartung und Upgrade-Möglichkeiten für zukünftige Anforderungen der Applikation, ohne die Datensätze zu verändern. Des weiteren wird dadurch erst die Generierung des Backend’s möglich, da jede Zeile aus einer Tabelle der Datenbank als Java Bean-Objekt im generierten Code abgebildet wird, ob als Join/Mapping mehrerer Tabellen oder einer Zeile aus einer Tabelle, spielt dabei keine Rolle. Der generierte Backend-Code entspricht dem Software-Architekturkonzept, welches in Abb. 1 anschaulich erklärt wird. TLGen 4 StarData GmbH v 1.004 Abb 1.: Architektur-Konzept 1.2 Inhalt vom Download Die Datei „tlrgen3_v1001.zip“ beinhaltet Ordner mit folgenden Dateien: -project-TLGen3: Eclipse-Projektdateien -build: Apache Ant Dateien -doc: Dokumentation, License Dateien und im Ordner db die sql-Dateien für den Testdatenbank. -source: Source Dateien -generator TLGen jar -resource -config TLGen 5 StarData GmbH v 1.004 2. Generierte Code-Struktur TLGen generiert den gesamten Code von Business(Daten)-Objekten, Session-und Entity- Beans bis zu den Testklassen (für JUnit). (Note :Alle Referenzen für Klassen-Namen oder Package-Namen werden bei den Beispieldaten verwendet.) Abb 2. TLGen 6 StarData GmbH v 1.004 2.1 Package(Ordner)-Struktur von generiertem Code Die Package-Struktur kann in drei Gruppen aufgeteilt werden (Siehe Abb. 2): -Client-Package: notwendige Klassen für EJB3-Zugriff auf den Server (im Bsp. core genannt) und die Testklassen (test). -Daten-Package: (Value-)Objekte mit 3 Unterpackages doc, doclist und form. -Server-Package: auch doc, doclist und form genant. TLGen 7 StarData GmbH v 1.004 3. Code-Generierung Der EJB3 kompatible Java-Code wird nur mit Hilfe einer in XML geschriebener Konfigurationsdatei gesteuert (im Bsp. Kap. 4 unter Project-TLGen3\config\config_gen_db3i. xml zu finden) 3.1 Was wird generiert? Die folgenden Java Dateien werden generiert: -Die Server-Zugriffsklassen des Clients mit den dazugehörigen Testklassen -Datenklassen und deren Interfaces -Session-, Entity-Beans und Managerklassen (welche die Zugriffe von den Entity- Beans auf die Session-Beans steuern). Teile der Serverklassen mit jeweils deren Interfaces (für Session-Beans und Managerklassen) und die Steuerungsdatei persistence.xml. 3.2 Regeln der Datenbeschreibung Die Konfigurationsdatei steuert die komplette Generierung des Backends. Sie ist individuell auf die eigenen Bedürfnisse einstellbar, z.B. was welche Manager-Klassen machen dürfen/ können bzw. welche Methoden für die z.B. SQL-Zugriffe generiert werden sollen. In den folgenden Kapiteln werden alle Möglichkeiten und Tags erklärt. 3.2.1 Platzhalter für die Namen Innerhalb der Konfigurationsdatei gibt es Platzhalter für die Namen der generisch erzeugten Klassen (z.B. im den String „eu.stardata.core.form.data.Co%classname%Value“), damit diese richtig vom Generator dynamisch gesetzt werden können. Auf dieser Basis können mehrere Klassen erstellt werden: -“eu.stardata.core.form.data.CoFormularValue” -“eu.stardata.core.form.data.CoDocumentValue”, etc 3.2.2 Generierte Namen der Tabellen Aus den Datenbanktabellen kann nach folgender Regel der Generische Name erzeugt werden : Aus Tabellenname „CORE_FORMULAR“ wird „Formular“ generiert und aus „CORE_DOCUMENT“ wird „Document“ generiert. 3.3 Beschreibung der Konfigurationsdatei zur Steuerung der Generierung TLGen 8 StarData GmbH v 1.004 Für die Configdatei werden mehrere Tags verwendet. Der Main Tag ist , innerhalb von können mehrere Tags und in können mehrere Tags vorhanden sein. Jeder dieser Tags mit seinen Untertags ist im Folgenden beschrieben. 3.3.1 Element : Generator Parameter : name, datasource, reference Content Model : (Command ?) Das ist der Main-Tag, der nur einmal in einer Konfigurationsdatei verwendet werden darf. Er dient nur für die Verwaltung von Informationen. Seine Parameter sind: -name = Projektname -datasource = „java:/tlgenPool“ ist der Datenbank-Pool im Application-Server. Ein Name der im generierten Code verwendet wird. -reference = false oder true. Für diese Version von TLGen sollte es immer false sein. True wird für nachfolgende Versionen von Bedeutung sein. Damit wird dem Generator mitgeteilt, dass schon mal vom Generator generierter Code, der nachträglich per Hand erweitert oder geändert wurde, beim wiederholten Generieren mit berücksichtigt werden muss (s. Kap. 5). 3.3.2 Element : Command Parameter : name, type, initialcontext, initialcontextfactory, initialcontextpkgprefix, methods, sequencegen, earname Content Model : (Design ?) Command Tag wird verwendet, um den Generierungstyp zu definieren und die Zugriffsparameter für den Application-Server (Gilt nur für die Test-Klassen) zu setzen: -name = Name des generierten Codes -initialcontext = „[Host]:[Port]“ -Application-Server Initial Context (nur für test) -initialcontextfactory = “org.jnp.interface.NamingContextFactory” (nur für test) -initialcontextpkgprefix = “org.jboss.naming:org.jnp.interfaces” (nur für test) -type = “gdb” (derzeit nur dieser Typ möglich) für die Code Generierung auf Basis einer existierenden Datenbank und einer Konfigurations-datei. -methods = „public“ -sequencegen = „SEQ_STORE“ wird verwendet in Verbindung mit den seqstrategy -earname = „efp_test“ ist den ear Name, falls mit Hilfe von ANT die Klassen generiert werden. (Siehe kap. 4.) TLGen 9 StarData GmbH v 1.004 3.3.3 Element : Generator Parameter : name, methodtype, reference Content Model : (Commentar ?, Class?, Entity?, Manager?, Session?, Test?, Dbtable?) Dieser Tag wird verwendet um einen Session-Bean mit seinen Managern und Entity-Beans zu definieren. Normalerweise definieren die Session-Beans den Remote-Zugriff auf den Server. Gleichzeitig mit dem Session-Bean werden, mit Hilfe von diesem Tag, auch die Zugriffsklassen für den Client auf diesen generiert. Mit dieser sogenannten BCI(Business Common Interface)-Schicht, kann der Client auf den Session-Bean zugreifen. -name = Generischer Name für diese Session Bean -methodtype = „public“ -reference = false oder true. Überschreibt die Einstellung vom Generator-Tag (Kap. 3.3.1). Für diese Version von TLGen sollte es immer false gesetzt sein, true wird für Folgeversionen eine Bedeutung haben. Damit wird dem Generator mitgeteilt, dass schon mal vom Generator generierter Code, der nachträglich per Hand erweitert oder geändert wurde, beim wiederholten Generieren mit berücksichtigt werden muss (s. Kap. 5). 3.3.3.1 Element : Commentar Parameter :name Content Model : keine -name = Kommentar 3.3.3.2 Element : Class Parameter : name, type, extends, extendsif, constant Content Model :keine Dieser Tag wird für die Generierung von Business-Klassen und Interfaces verwendet. Für jede Datenbanktabelle wird eine Datenklasse und ein Interface generiert. Erläuterung der Parameter: -name = „eu.stardata.core.form.data.Co%classname%Value | eu.stardata.core.form.data.Co%classname%ValueIf“ wird für die Datenklassen und Interface Namensgenerierung verwendet. Der Plazhalter „%classname%“ wird durch den richtigen, eigenen Namen ersetzt (Siehe auch Kap. 3.2.1 und Kap. 3.2.2). -type = „public“, d.h. die Klassen und Interfaces sollen public sein. TLGen 10 StarData GmbH v 1.004 -extends = wird verwendet für die Klassenvererbungen extends (z.B.“de.stardata.base.business.data.BaseData“) -extendsif = wird verwendet für die Interface-Vererbungen extends (z.B. “de.stardata.base.business.data.BaseDataIf“) -tostring = Name für die String Methode zur Generierung der Business Klassen. Können mehrere Namen sein, getrennt durch ein Komma. 3.3.3.3 Element : Entity Parameter : name, type, seqstrategy, implements Content Model : (Annotation ?) Entity-Tag wird zur Generierung der Entity-Klassen verwendet. Erläuterung der Parameter: -name = „eu.stardata.server.core.formular.entity.%classname%Entity” verwendet zur Generierung der Entity-Namen. Der Platzhalter %classname% wird ersetzt durch den richtigen Manager-Namen, nämlich dem Namen der Tabellen. -type = z.B. „public“ -seqstartegy = „SEQUENCE“, „TABLE“, „IDENTITY“ oder „AUTO“, sind die Generierungsmöglichkeiten für den Primary Key. Dies gilt für alle Entity Beans, welche sich im Tag befinden, können aber für eine einzige Entity im Tag geändert werden. -implements = „java.io.Serializable“ sind die „implements“ Interfaces für den Entity- Bean. Die Entity-Bean Generierung wird im Tag beschrieben. Dort wird auch die Generierung von Relationen beschrieben. Wenn der Primary Key mehrere Spalten beinhaltet, wird auch eine PK Klasse generiert. 3.3.3.3.1 Element : Annotation Parameter : name Content Model : keine Definiert die Annotationen für die Entity-Beans, es können auch mehrere sein. Erläuterung der Parameter, z.B.: -name = „javax.persistence.Entity“, oder / und -name = „javax.persistence.Table“, der Tabname wird in der Generierung von ten Datenbank geholt TLGen 11 StarData GmbH v 1.004 oder / und -name = „javax.persistence.SequenceGenerator“, wird in der Generierungszeit von den Dantenbank mit name, sequenceName, initialValue und allocationSize vervollständigt 3.3.3.4 Element : Manager Parameter : name, type, entends, implements Content Model : (Annotation ?, Variables?, Variablespri?, Method?) Mit Hilfe vom Manager-Tag und dessen Parametern werden die Manager-Klassen generiert. Durch diese Klassen werden die Zugriffe der Entity-Beans im sog. „Local“-Modus gesteuert. Diese Klassen werden auch als Klassen zwischen Session-Bean und Entity-Bean verwendet. In dieser Version von TLGen wird zu jedem Entity-Bean auch eine Manager-Klasse generiert. Des Weiteren werden auch eventuelle SQL-Zugriffe für jeden Entity-Bean generiert. Gleichzeitig mit den Manager-Klassen werden auch die Interface-Klassen für den Zugriff auf die Manager-Klassen generiert. Erläuterung der Parameter: -name = „eu.stardata.server.core.formular.manager.%classname%Manager” wird verwendet, um den Manager-Namen zu generieren. Der Platzhalter %classname% wird durch den richtigen Manager-Namen des Tabellennamens ersetzt. -type = z.B. „public“ -extends = “de.stardata.server.common.ejb.manager.BaseManager“ -implements = “de.stardata.server.core.formular.bci.%classname%BciIf“, mit diesem Parameter wird die Interface-Klasse für den Manager generiert. 3.3.3.4.1 Element : Annotation Parameter : name Content Model : keine Definiert die Annotationen für die Manager-Klassen. Es können beliebig viele sein. Erläuterung der Parameter, z.B.: -name = „javax.ejb.Stateless(name = de.stardata.server.core.formular.bci.%classname%BciIf.%membervariable4%)“, der Platzhalter %classname% wird ersetzt mit dem richtigen Klassen-Namen und %membervariable4% mit dem Variablennamen z.B. JNDI_NAME, welcher im Manager-Interface definiert ist. oder / und -name = „javax.ejb.Local(name = de.stardata.server.core.formular.bci.%classname%BciIf.class)“, der Platzhalter %classname% wird ersetzt durch den richtigen Klassen-Namen. TLGen 12 StarData GmbH v 1.004 3.3.3.4.2 Element : Variables Parameter : name Content Model : (Variable?) Dieser Tag definiert die Gruppen von Variablen, die in der Manager-Interface-Klasse generiert werden. 3.3.3.4.2.1 Element : Variable Parameter : name, type, content, manager Content Model : keine Definiert die Variablen, welche in einem Interface oder einer Klasse generiert werden. -name = „%membervariable4%” wird verwendet, um den Variablennamen zu definieren. In dieser Version von TLGen sind für die Manager-und seinen Interface- Klassen folgende Variablennamen fest definiert: public static String VARIABLE1 = "m_Manager"; public static String VARIABLE2 = "SQL_FIND_ALL"; public static String VARIABLE3 = "EAR_NAME"; public static String VARIABLE4 = "JNDI_NAME"; public static String VARIABLE5 = "MANAGER_NAME"; public static String VARIABLE6 = "SQL_FIND_BYNAME"; public static String VARIABLE7 = "PARAM_NAME"; -type = „public static final java.lang.String“ -content = %earname% wird ersetzt mit den EAR-Namen, z.B. für die Parameter für eine SQL-Query: -name = „%membervariable6%” wird ersetzt mit dem Inhalt „SQL_FIND_BYNAME“ -type = „public static final java.lang.String“ -content = „select o from %classname%Entity o where o.formular = :formular“. -manager = “Formular” bedeutet, dass diese SQL-Query’s nur in den Manager-Klassen „Formular“ generiert werden. 3.3.3.4.3 Element : Variablespri Parameter : name, type, content Content Model : (Variable?) TLGen 13 StarData GmbH v 1.004 Dieser Tag definiert die Gruppen von Variablen, die in den Manager-Klassen generiert werden. 3.3.3.4.3.1 Element : Variablespri Parameter : name, type, content Content Model : (Variable?) Siehe auch Kap. 3.3.3.4.2.1 3.3.3.4.4 Element : Method Parameter : name, type, parameter, return, exception, manager ,parameterSqlList,parameterSqlSingel,parameterType Content Model : keine Dieser Tag generiert die Manager-Methoden. Wenn der Parameter manager fehlt, werden die Methoden in allen Manager-Klassen generiert. Ist dieser vorhanden, wird er nur in dieser Manager-Klasse generiert. Durch die Verwendung von den Parametern „parameterSqlSingel”, “parameterSqlList” und „parameterType“ können eigene SQL-Befehle für die Code Generierung verwendet werden. -name = „find ByPrimaryKey“ -type = „public“ -parameter = „long“ -return = „%classdataif%“ Platzhalter %classdataif% wird ersetzt mit den Daten- Interface-Klassen. -exception = „eu.stardata.server.common.exception.PersistenceException“ -parameterSqlList = "SELECT u FROM User u WHERE u.username=:name AND u.pwd=:pass" ist ein SQL-Befehl, welche eine Liste von Daten-Objekten zurückgibt. -parameterSqlSingel = "SELECT u FROM User u WHERE u.username=:name AND u.pwd=:pass" " ist ein SQL-Befehl, welches ein einziges Daten-Objekt zurückgibt. -parameterType = “java.lang.String, java.lang.Integer”. In diesem Beispiel sind zwei Parametertypen, einer ein String Objekt, der andere ein Integer Objekt. 3.3.3.5 Element : Session Parameter : name, type, managername, extends, transactiontype Content Model : (Annotation ?, Method?, Factory?) Der Session-Tag wird für die Generierung eines Session-Beans verwendet. -name = “de.stardata.server.core.formular.FormularSessionBean” -type = “public” TLGen 14 StarData GmbH v 1.004 -managerName = “manager Formular” dieser Name wird laut EJB3 auch in der Datei „persistence.xml“ unter den Tag Parameter name verwendet. -extends = “eu.stardata.server.common.ejb.session.BaseSessionBean” -transactiontype = “JTA” Bemerkung: Für den Session-Bean sind (für die aktuelle Version von TLGen) die folgenden Variablen definiert: public static String VARIABLE1 = "MANAGER_NAME"; public static String VARIABLE2 = "EAR_NAME"; public static String VARIABLE3 = "JNDI_NAME"; 3.3.3.5.1 Element : Annotation Parameter : name Content Model : keine Definiert die Annotationen für die Session-Bean-Klasse. Es können beliebig viele sein, z.B. -name = „javax.ejb.Stateless(name = „%factoryname%.%membervariable3%)“, der Platzhalter %factoryname% wird ersetzt durch den richtigen Klassennamen und %membervariable3% mit dem Variablennamen, z.B. JNDI_NAME, die in den Manager-Interface-Klassen definiert sind. oder / und -name = „javax.ejb.Remote(name = %factoryname%.class)“, der Platzhalter %factoryname% wird ersetzt mit dem richtigen Factory-Klassennamen. 3.3.3.5.2 Element : Factory Parameter : name, extends, type Content Model : (Annotation?, Variables?) Der Factory-Tag generiert zwei Klassen, die für den Zugriff vom Client auf den Server notwendig sind, jeweils eine Zugriffsklasse und eine Factory-Klasse. Ein Beispiel einer Zugriffsklasse des Clients ist: eu.stardata.client.core.formular.bci.FormularBci factoryBci = eu.stardata.client.core.formular.bci.FormularBciFactory.getFormularBci(); eu.stardata.core.form.dataif.CoFormularValueIf var1 = factoryBci.findByPrimaryKeyFormular(1); -name = “de.stardata.server.core.formular.bci.FormularBci” -extends = “de.stardata.server.common.bci.BciFactory” -type = z.B. “public” 3.3.3.5.2.1 TLGen 15 StarData GmbH v 1.004 Element : Annotation Parameter : name Content Model : keine Ist die Annotation für die Factory-Klasse -name = “javax.ejb.Remote” 3.3.3.5.2.2 Element : Variables Parameter : name Content Model : (Variable?) Gruppiert die Variablen für die Zugriffsklassen 3.3.3.5.2.2.1 Element : Variable Parameter : name, type, content Content Model : keine Definiert die Variable für eine Factory-Klasse. -name = „%membervariabe1%“ -type = „public static final java.lang.String“ -content = %earname% wird ersetzt durch den EAR-Namen. 3.3.3.5.3 Element : Method Parameter : name, type, parameter, return, exception, manager, parameterSqlSingel, parameterSqlList, parameterType Content Model : keine Dieser Tag wird verwendet, um die Session-Bean-Methoden zu generieren mit folgenden Attributen: -name = „find ByPrimaryKey“ -type = „public“ -parameter = „long“ -return = „%classdataif%“ Platzhalter %classdataif% wird ersetzt durch die Daten Interface-Klasse. TLGen 16 StarData GmbH v 1.004 -exception = „eu.stardata.server.common.exception.PersistenceException“ -manager = z.B. “Formular” generiert diese Methode in den Formular-Manager- Klassen. -parameterSqlSingel = "SELECT u FROM User u WHERE u.username=:name AND u.pwd=:pass" ist ein SQL-Befehl, der ein einziges Daten-Objekt zurückgibt. -parameterSqlList = "SELECT u FROM User u WHERE u.username=:name AND u.pwd=:pass" ist ein SQL-Befehl, der eine Liste von Daten-Objekten zurückgibt. -parameterType = “java.lang.String, java.lang.Integer”. In diesem Beispiel sind zwei Parametertypen, einer ein String Objekt, der andere ein Integer Objekt. 3.3.3.6 Element : Test Parameter : name, type, extends Content Model : (Import?, Method?) Dieser Tag definiert die Daten, die Notwendig sind für die Generierung der Testklassen. Ziel dieser generierten Klassen ist es, die Zugriffe auf die Session-Beans zu erläutern, und eine Vereinfachung vom Testbetrieb zu erreichen. Diese Klassen können per Hand weiterentwickelt werden. -name = „eu.stardata.client.test.core.formular.Formular3RwlTest“, Test-Klassenname -type = z.B. „public“ -extends = „junit.framework.TestCase“ 3.3.3.6.1 Element : Import Parameter : name Content Model : keine Kann verwendet werden für eventuelle Import-Klassen. -name = „de.stardata.base.common.Trace“ 3.3.3.6.2 Element : Method Parameter : name, type, parameter, return, exception, manager, readwritedel Content Model : keine Dieser Tag wird zur Generierung der Testmethoden verwendet. -name = „create“, Methoden-Name TLGen 17 StarData GmbH v 1.004 -type = z.B. „public“ -parameter = „Formular“, Parameterliste für diese Methode -return = „Formular%“. -exception = „eu.stardata.server.common.exception.PersistenceException“ -manager = “Formular”. -Readwritedel = „0“, „1“, „2“, oder „3“ -„0“ = create type, „1“ = find type, „2“ = für update und „3“ = Object löschen. 3.3.3.7 Element : Dbtable Parameter : name, type Content Model : (Relation? Dbfreemethod?) Die Engine-Steuerung für die Code-Generierung läuft über die Datenbanktabellen. Für jede Tabelle (in dieser Version von TLGen) wird eine Datenklasse und seine Interface-Klasse generiert sowie ein Entity-Bean und eine Manager-Klasse mit seinem Interface. Aus diesem Grund ist den -Tag ein wichtiger Bestandteil für die Code-Generierung in TLGen. -name = „CORE_FORMULAR“, das ist im Bsp.-Skript der Tabellen-Name. Aus diesem Namen wird ein Name generiert, der für alle anderen Klassen verwendet wird. In diesem Fall ist der generische Name „Formular“. In der nächsten Version von TLGen wird ein Namensgenerator eingebaut. Mit Hilfe des Tabellennamens werden von der Datenbank alle notwendigen Informationen gelesen, die für die Generierung notwendig sind: -Aus den Tabellenspalten(Columns), die für die Methodengenerierung in den oben genannten Klassen verwendet werden, wird z.B. aus „FORMULAR_ID“ der Name „Formular_id“ generiert. Gleichzeitig wird auch der Datentyp ermittelt, der ebenfalls für die Generierung benutzt wird. -Informationen über den Primary-Key -Sequences -type = z.B. „public“ 3.3.3.8 Element : Relation Parameter : type, table, cascade, fetchType, optional, direction, mappedBy Content Model : (JoinColumn?, JoinTable?) Mit diesem Tag werden Informationen für die Relationen zwischen den Tabellen in den Entity-Beans generiert. -table = „CORE_PAGE“ ist der Ziel(target)-Entity-Bean(Tabelle)-Name, welcher mit dem aktuellen Entity-Bean(Tabelle) eine Relation hat. TLGen 18 StarData GmbH v 1.004 -type = Folgende Relationen sind Implementiert: „OneToOne“, „OneToMany“, „ManyToOne“ und “ManyToMany”. -fetchType = „LAZY“ oder „EAGER“ (siehe EJB3-Dokumentation). -cascade = Folgende „cascade“-Typen sind erlaubt: „ALL“, „PERSIST“, „MERGE“, „REMOVE“, „REFRESH“. -optional = „true“ oder „false“. Gilt nicht für type „ManyToMany“ -direction = „true“ oder „false“, gilt nur für Type „ManyToMany“ -mappedBy = „formular“ (wird für den Entity-Bean verwendet, wo direction = false), bezeichnet die Attribute, über die die eigentliche Beziehung definiert wurde. 3.3.3.8.1 Element : JoinTable Parameter : name, catalog, schema Content Model : (JoinColumns?) Dieser Tag (Annotation) wird immer nur dann benötigt, wenn die Beziehungen zwischen zwei Entity-Beans über eine zusätzliche Tabelle und nicht über die eigenen Spalten abgebildet werden müssen. Diese Tag wird meistens für die „ManyToMany“ Beziehungen verwendet. -name = „DOCUMENT_FORMULAR“ ist der Name der Join-Table, über die die Beziehung(Relation) funktioniert. -catalog = ist der Tabellenkatalog (optional) -schema = ist das Tabellenschema (optional). 3.3.3.8.2 , Element : JoinColumn Parameter : name, referencedColumnName, insertable, nullable, updatable, unique Content Model : keine Über diesen Tag (Annotation) wird der Name der Datenbankspalte definiert, die in einer Beziehung als Fremdschlüssel (Foreign-Key) dient. -name = „FORMULAR_ID“ ist der Spaltenname für die Beziehung -referencedColumnName = “DOCUMENT_LIST_ID” ist der andere Spaltenname für die Beziehung -inserable = boolean -nullable = boolean -updatable = boolean -unique = boolean TLGen 19 StarData GmbH v 1.004 3.3.3.9 Mit Hilfe dieses Tags werden die Methoden von Business Klassen beschrieben, die keine Äquivalente in den Datenbanken besitzen, d.h. für die Methoden gibt es keine Spalten in den betroffenen Tabellen. 3.3.3.10 Die Daten dieses Tags sind in der Annotation @Tablegenerator verwendet. Element: Strategy Parameter: name, table, column, value Content Model: keine -name = nimmt den Strategy type („SEQUENCE“, „TABLE“, „IDENTITY“ oder „AUTO“) -table = Table Name für die Strategie „Table“, in Annotation ist es der Parameter table -column = Column Name für die Strategy „Table“ für Parameter pkColumnName -value = Wert von Index für Parameter valueColumnName 3.4 Beschreibung der Build-Datei für TLGen Für die Code-Generierung wird die Datei „build_generator.xml“ verwendet. Diese wird angerufen von einer Apache-ANT-Datei (z.B. build.xml) mit den folgenden Tags: Der Tag in der „build_generator.xml“ für z.B. eine Oracle-DB sieht folgendermaßen aus: mit folgendem Content-Model , Parameter: TLGen 20 StarData GmbH v 1.004 -databaseConnect = den Pfad, wo die Konfigurations-Datei zu finden ist -databaseDriver = Datenbank JDBC-Treiber -userPwd = Datenbank User und sein Password -database = „Oracle“ Datenbankname (für diese Version ist nur die Oracle-DB möglich) Bemerkung :Der generierte Code ist Datenbank-und Applikation-Server-unabhängig! -pathToGenerate, akzeptiert als Content-Model für den Pfad, wo der generierte Code gespeichert werden soll. TLGen 21 StarData GmbH v 1.004 4. Installation von TLGen TLGen ist mit den Application-Servern JBoss (Version 4.2+ GA) und BEA WebLogic 10 getestet. Die mitgelieferte Beispielinstallation und Testgenerierung sind für JBoss und Oracle eingerichtet. Die Datei „tlgen3_v1001.zip“ sollte in irgendeinem Ordner entpackt werden. 4.1 Verwendete Tools und Externe Programme Im Ordner lib sollten folgende jars sein (die Ordner sind für die Datei Project-TLGen3 \build\build_generator.xml wichtig; können jederzeit erweitert oder geändert werden, s. Kap. 4.3): -lib/: junit.jar (JUnit) -lib/apache/: ant.jar ( Apache Ant Vers. 1.7+) -lib/jboss/: JBoss Version 4.2+ GA: o ejb3-persistence.jar o hibernate-annotations.jar o jbossall-client.jar o jboss-ejb3x.jar o mail.jar -lib/oracle/: o nls_charset12.jar o ojdbc14.jar 4.2 Beispiel Die zip enthält ein vollständiges Beispiel (s. Kap. 4.3). Die Bsp. Config-Generierungsdatei ist unter Project-TLGen3\config\config_gen_db3i.xml zu finden. Die Bsp.-SQL-Skripte sind unter Project-TLGen3\doc\db\sql zu finden 4.3 Installation Im Folgenden wird eine Beispielinstallation und Code-Generierung erklärt. In der mitgelieferten Konfiguration Datei -Project-TLGen3\config\config_gen_db3i.xml muss die Server-URL angepasst werden: initialcontext = "jnp://[IP/HOST]:[PORT]" TLGen 22 StarData GmbH v 1.004 Mit der richtigen Adresse und dem Application-Server Port (z.B. jnp://127.0.0.1/1099)in der config_gen_db3i.xml muss im Tag Generator der richtige datasource (siehe Kap. 3.3.1) z.B. "java:/tlgenPool" eingerichtet werden. Für die Kompilierung mit Apache-ANT müssen folgende Variablen in den jeweiligen Dateien geändert werden. In -Project-TLGen3\build\build_generator.xml muss ganz unten die Datenbank-Connection richtig eingerichtet werden (s. Kap. 3.4) und in der -Project-TLGen3\build\build.properties müssen die Variablen für die -Project-TLGen3\build\build.xml geändert werden. Z.B. ANT_HOME=[Pfad]\ant-1.7.0, JBOSS_HOME=C:/jboss-4.2.2.GA, PROJECT_PATH=C:/Project-TLGen, CONNECT_POOL=tlgenPool 4.3.1 Datenbank einrichten Nach der Installation sollte eine Test Datenbank von Oracle eingerichtet werden. Die SQL- Skripte sind im folgendem Ordner zu finden: Project-TLGen3\doc\db\sql Alle wichtigen SQL-Skripte müssen über CreateCore3DB.sql aufgerufen werden, wobei man noch den richtigen absoluten Pfad in der Datei angeben muss. Des Weiteren muss man entweder den Tablespace CODATA, COINDEX in der Datei CreateTLGenOraTest.sql in Ihrer DB einrichten oder die Datei für andere Tablespaces abändern. Das Test-Datenbankmodell ist in Abb. 3 abgebildet. (http://www.oracle.com/technology/ software/products/database/index.html ) 4.3.2 JBoss Application-Server einrichten In JBoss sollte ein neuer Server mit den Namen „TLGen“ aufgesetzt werden, indem man den Ordner jboss/server/all/ kopiert und in „TLGen“ umbenennt. Kopieren Sie dann die beiden Library-Dateien ojdbc14.jar, nls_charset12.jar von Oracle in den Ordner lib des TLGen- Servers, danach kopieren Sie die Datei jboss-4.2.2.GA\docs\examples\jca\oracle-ds.xml in den Ordner deploy vom TLGen-Server und passen diese für Ihre Oracle-DB an. Überprüfen Sie ob ihr Systempfad JAVA_HOME richtig gesetzt wurde. Dann den Server mit \bin\run.bat -c TLGen oder \bin\run_debug.bat -c TLGen starten. (Siehe auch JBoss-Dokumentation http://www.jboss.org/docs/index). 4.3.3 Programm in Eclipse importieren Das Projekt kann einfach im Editor Eclipse (http://www.eclipse.org/) importiert werden. Die Eclipse-Konfigurationsdateien sind im Wurzelverzeichnis der Ordnerstruktur zu finden. Auch in anderen Editoren ist es möglich das Projekt zu importieren, beachten Sie bitte die TLGen 23 StarData GmbH v 1.004 Dokumentation des jeweiligen Herstellers. Mit Hilfe von Apache-Ant (http://ant.apache.org/, Überprüfen Sie ob ihr Systempfad ANT_HOME richtig gesetzt wurde) kann der Code generiert werden, wobei im Ordner build die build.xml für ANT zu finden ist. Verwenden Sie dazu einfach die Kommandozeileneingabeaufforderung (cmd.exe) und tippen sie im build-Ordner einfach ant. Durch die Generierung werden auch die ear-und jar-Dateien in den neuen Server (s. Kap. 4.3, 4.3.2 ) kopiert. Gegeben falls müssen Sie den JBoss-Server neu starten. 4.3.4 TLGen Testen Über eine Entwicklungsumgebung z.B. Eclipse die generierten Testklassen „Formular3RwlTest.java“ und „ManyToMany3RwlTest.java“ einfach mit JUnit (http://www.junit.org/) aufrufen und den generierten Code testen. Viel Spaß! (Siehe auch für jUnit) TLGen 24 StarData GmbH v 1.004 Abb. 3 TLGen 25 StarData GmbH v 1.004 5. Pläne für die nachfolgenden Versionen In TLGen v1 sind die wichtigen Features von EJB3 implementiert. In dieser Version ist es nicht möglich, dass der Generator generierten Code, welcher nachträglich „per Hand“ erweitert wurde, erkennt und beim erneuten generieren nicht überschreibt. Das wird in eine spätere Version implementiert. Im Moment ist es ratsam, die per Hand gemachten Änderungen im generierten Code vor einer neuen Code-Generierung zu retten. Für die Nachfolgenden Versionen sind folgender neue Features vorgesehen: -Unterstützung mehrerer Datenbanken (MySql, SqlServer, DB2) -Mehrere Möglichkeiten, die Generierung dynamischer zu gestalten -Die Möglichkeit Interfaces für andere Applikationen zu Generieren -Die Aktuelle Generierung mit Code Generierung von UML zu verbinden. -Den per Hand geänderten bzw. erweiterten Code bei einer neuen Generierung einzubeziehen. TLGen 26 StarData GmbH v 1.004 6. Anhang: Literaturhinweise 1. Ejb3 Spezifikation Core “ejb-3_0-fr-spec-ejbcore.pdf”, http://java.sun.com/products/ejb/docs.html 2. Ejb3 Spezifikation für Persistence “ejb-3_0-fr-spec-persistence.pdf” http://java.sun.com/products/ejb/docs.html TLGen 27 StarData GmbH