What you should know:

• Metadata for scaffoling your GUI (described here).

What you need to compile/run the examples:

• java1.5 or newer
• opensource framework: agimatec-validation : download agimatec-validation.jar
• optional: javax.servlet.jar (servlet-api)
• optional: opensource frameworks/tools: agimatec-tools : download annomark-dist.zip and annogen.jar

1. Create model classes

We start with a plain java class, our model, used to transport attributes from the server to the GUI. (You can use DWR for marshaling object instances between Java and JavaScript/JDOM).

Example class “Business”:

import javax.persistence.*;

public class Business {
@Id
@Column(name=”business_id”, nullable=false, unique=true)
Long businessId;
@Column(name=”name”, nullable=false, unique=true, length=200)
String name;
@Column(name=”active”, nullable=false)
boolean active;
// getters, setters follow…
}

2. Write or generate xml meta data

You can write the xml meta data manually, or – if your classes have javax.persistence.* annotations – you can generate them using agimatec-tools/annomark.jar (described here):

<bean id=”com.agimatec.Business” impl=”com.agimatec.Business”>
<feature key=”mainKey”>
<value class=”string”>businessId</value>
</feature>
<property name=”businessId”>
<feature key=”uniqueKey”>
<value class=”boolean”>true</value>
</feature>
</property>
<property name=”name” mandatory=”true” maxLength=”200″>
<feature key=”uniqueKey”>
<value class=”boolean”>true</value>
</feature>
</property>
<property name=”active” mandatory=”true”/>
</bean>

Store the file as “beaninfos-default.xml” in the classpath.

2. Access the MetaBean

This requires agimatec-validation.jar to compile:

import com.agimatec.validation.MetaBeanManagerFactory;
import com.agimatec.validation.model.MetaBean;

MetaBeanManagerFactory.getRegistry().
addResourceLoader(“beaninfos-default.xml”);

MetaBean metabean = MetaBeanManagerFactory.getFinder().findForClass(Business.class);

3. Generate JSon for metabean(s)

We want to use the meta data in the AJAX layer, to have information about the properties, their types and additional features (mandatory, max-length, …) as a JSON formatted string. agimatec-validation offers a JSONGenerator, based on a freemarker template:

import com.agimatec.validation.json.JSONGenerator;

JSONGenerator generator = new JSONGenerator();
String json = generator.toJSON(metabean);
System.out.println(json);

This prints this JSON string:

agimatec.namespace(“agimatec.metadata”);

(function(){

var metaBean0 = {
“id” : “com.agimatec.Business”,
“beanClass” : “com.agimatec.Business”,
“name” : “Business”,
“features” :{   “mainKey” : “businessId”},
“properties” :{
“active”:{
“name” : “active”,
“type” : “boolean”,
“features” : {       “mandatory” : true       }},
“businessId”:{
“name” : “businessId”,
“type” : “long”,
“features” : {       “uniqueKey” : true       }},
“name”:{
“name” : “name”,
“type” : “java.lang.String”,
“features” : {       “maxLen” : 200,       “mandatory” : true,       “uniqueKey” : true       }},
“version”:{
“name” : “version”,
“type” : “int”,
“features” : {       }}}};

agimatec.metadata.metaBeans = {“com.agimatec.Business” : metaBean0};})();

4. Write a servlet to deliver JSON for the AJAX GUI

The java code for the servlet should not be a surprise, for it consists of what we have seen so far:

public void init() throws ServletException {
super.init();
MetaBeanManagerFactory.getRegistry().addResourceLoader(“beaninfos-default.xml”);
}

public void service(HttpServletRequest servletRequest, HttpServletResponse res)
throws ServletException, IOException {
Map<String, MetaBean> metaBeans = MetaBeanManagerFactory.getFinder().findAll();
// output JSON:
res.setContentType(“text/javascript”);
PrintWriter writer = res.getWriter();
String json = new JSONGenerator().toJSON(metaBeans.values());
writer.write(json);
}

Thats basically all! With this infrastructure your AJAX GUIs have access to meta information about the model classes.

5. Enrich meta data with information for the GUI-layer

You can enrich the xml meta data with additional hints (field sequence, formats, …) – whatever your GUI needs. If hhe additional information cannot be generated automatically, you should keep them in a separate xml-file:

<bean id=”com.agimatec.Business”>
<feature key=”DESCRIPTION”>
<value class=”string”>{name}</value>
</feature>
<feature key=”SORTING”>
<value class=”list”>
<string>name</string>
<string>active</string>
</value>
</feature>
<!–Visualisation as table–>
<feature key=”TABLE_COLUMNS”>
<value class=”list”>
<string>name</string>
<string>active</string>
</value>
</feature>
</bean>

Save this as “beaninfos-gui.xml ” in the classpath and register the file in the init() method of the servlet, too:

MetaBeanManagerFactory.getRegistry().addResourceLoader(“beaninfos-gui.xml”);

You see, that the JSON code will contain the additional information as well, because the MetaBeanManager merges them.

So far, we have the infrastructure to support meta data that allows us to build generic AJAX GUIs. The JSON string can be cached, because it will never change while the application is running.

6. User-specific meta data

We can go one step further: We can also support user-specific meta data! A usual requirement in a web application is, that – depending on the role of a user that is logged in – field-level permissions must be supported:
User A is allowed to change the “active”-state of our “Business” entity, while User B has read-only access to the field and the field is hidden for User C, …

This could also be useful, when a user can customize its GUI (disable fields) by himself or when the application is used by different companies with different settings for their users….

How does it work? – Use additional xml files and merge them in the JSON servlet. (You can also generate the meta beans during runtime programmatically).

beaninfos-role1.xml:

<bean id=”com.agimatec.Business”>
<property name=”active”>
<feature key=”readonly”>
<value class=”boolean”>true</value>
</feature>
</property>
</bean>

Extension of the servlet:

String customInfos = “beaninfos-role1.xml”; // determine this from session or request dynamically!
XMLMetaBeanInfos xmlInfos =
new XMLMetaBeanURLLoader(getClass().getResource(customInfos)).load();
Map<String, MetaBean> metaBeans =
MetaBeanManagerFactory.getEnricher().enrichCopies(xmlInfos);

The statements after “// output JSON” stay the same (see previous code fragment).

More information?

We already got some more posts in German about metadata and code generation, explaining the concepts and giving examples:

• TransferObjects generieren
• agimatec-tools als OpenSource auf google.code released!
• Statt Modellieren: Annotieren und generieren
• Klassen mit Mehrwert: Validierung und Metadaten

The open-source frameworks have a WIKI and additional examples or junit testcases, that help you.

If you have questions, do not hesitate to contact us!

This is the fifth article in our mini-series about developing highly ajaxified portlets. Other articles are:

• Generate Your UI Using Metadata
• Inter Portlet Communication
• Using YUI loader for your own javascript modules
• Portlet namespaces and javascript

Unsere agimatec-tools sind nun als OpenSource Projekt auf google.code veröffentlicht. Wir setzen diese Tools und Frameworks bereits seit über einem Jahr produktiv in unseren Produkten ein.

Drei Tools verbergen sich bisher hinter “agimatec-tools”:

1. Ein Database-Migration Tool zum setup/alter/check von Datenbanken. Projekte, die eine oder mehrere Datenbanken (oder Datenbanken unterschiedlicher Hersteller) pflegen und weiterentwicklen, können mit diesem Werkzeug das Deployment/Upgrade ihrer Datenbanken durchführen und prüfen, ob das Schema vollständig und korrekt ist. (Beispielprojekt anbei)

Das Tool erlaubt auch die Verarbeitung (Parsen, Transformation, Code-Generierung) von SQL-Scripten.

2. Ein Framework zum Datenimport, das es vor allem mit einem Groovy-Script einfach macht, CSV-Dateien, XML-Dateien und andere Textformate zu importieren. (Wir setzen es z.B. gemeinsam mit dem Datenbank-Migration-Tool ein um einen initialen Datenimport aus vom Kunden gelieferten Dateien durchzuführen.)

3. Das Tool “annomark” (annnogen+freemarker) zur Generierung von Code durch Annotationen, wie bereits in einem früheren Beitrag angekündigt: “TransferObjects generieren“. Mit Annomark lassen sich flexible Verarbeitungen, nicht nur die Generierung von TransferObjekten, realisieren. (Ein Beispielprojekt demonstriert weitere Möglichkeiten.)

Die Veröffentlichung beinhaltet nicht nur Source und Binaries, sondern bietet auch Beispielprojekte und -templates, die für eigene Maven-Projekte verwendet werden können und umfassend die Verwendung der APIs demonstrieren. Auf google.code sind die Frameworks jeweils ausführlich im Wiki auf Englisch dokumentiert.

Jetzt sind wir gespannt auf Rückmeldungen und Anregungen und freuen uns, wenn diese Tools dem einen oder anderen weiterhelfen können!

Komisch nur, dass man bei Anwendung dieses Pattern, welches zweifellos wichtig und richtig ist, massiv gegen ein anderes, grundlegendes Softwareentwicklungs-Gebot verstößt: DRY – don’t repeat yourself. Oft wird das persistente Modell quasi verdoppelt als TransferObject-Modell. Die TransferObjekte besitzen allenfalls einige Attribute weniger, bestehen nur aus Getter-Setter-Methoden, implementieren keine Businesslogik und weniger Relationen untereinander.

Wir wollen TransferObjects nutzen ohne DRY zu verletzen, daher bietet es sich an, die TransferObjects durch Codegenerierung zu erzeugen. Wie geht das auf einfache Weise?

- mit dem kleinen agimatec-Framework “annomark”. (siehe auch Annotieren und Generieren)

In der Praxis finden sich natürlich Alternativen, z.B. durch die Verwendung von Codegeneratoren (MDSD).

Nehmen wir jedoch an, es gibt kein UML-Modell der Klassen.

Nehmen wir auch an, wir wollen die TransferObjekte flexibel abwandeln, z.B.

• andere Attributtypen als beim persistenten Objekt
• Umbenennung von Attributen
• Konvertierung zwischen Transfermodell und persistenter Klasse (in beide Richtungen), flexibel konfigurierbar
• Wahlweises Weglassen einzelner Relationen und Attributen
• “Flachklopfen”, d.h. Attribute von Childobjekten in ein flaches Transferobjekt hochziehen
• Splitten von Attributen (d.h. das Gegenteil von “Flachklopfen”)
• unterschiedliche Transferobjekte aus einer Klasse generieren (je nach Use-Case, z.B. Anzeigeobjekt, Bearbeitungsobjekt, …)
• Aus Getter-Methods des persistenten Objekts Attribute im Transferobjekt erzeugen

Dazu einige Beispiele, wie annomark dies ermöglicht. Wer hier eigenen Bedarf sieht, kann sich gerne melden, denn wir würden das Framework, das sich leicht in ant und maven Projekte integrieren läßt, dann als OpenSource Projekt veröffentlichen. Jetzt aber mal ein paar kurze Beispiele:

/** persistent class PostOffice **/
@DTOs({@DTO(usage = "edit"), @DTO(usage = "view")})
public class PostOffice {
    @DTOAttribute(type="Long", property="postOfficeId")
    private long id;
    private int version;
    /** Bezeichnung der Filiale **/
    @DTOAttribute
    private String name;
    @DTOAttribute(usage="edit")
    private String description;
    @DTOAttribute
    private Address address;

    // Getters and Setters ...
}

Wie wird sich das generierte TransferObjekt von class PostOffice unterscheiden?

• der Typ des “id” Attributes wird von primitive “long” auf die Wrapper-Class “Long” geändert (und kann damit null sein)
• der Name des “id” Attributes wird “postOfficeId” sein
• das Attribut “version” wird im TransferObjekt nicht enthalten sein, da es nicht annotiert ist
• das Attribut “description” wird nur im TransferObjekt für Bearbeitung enthalten sein. Zur reinen Anzeige kann eine andere Transferklasse erzeugt werden, in der “description” fehlt.
• die Beziehung zum “Address” Objekt wird in eine Beziehung zum TransferObjekt für Address gewandelt (sofern für Address ein eigenes Transferobjekt erzeugt wird)
• Java-Doc Kommentare werden übernommen und zusätzliche generiert.

Was kommt heraus? (Beispiel: Bearbeitungs-Transferobjekt)

public class TransferPostOffice {
  /**
  * source: id
  **/
  private Long postOfficeId;
  /**
  * source: name
  * Bezeichnung der Filiale
  **/
  private String name;
  /**
  * source: description
  **/
  private String description;
  /**
  * source: address
  **/
  private TransferAddress address;

  // Getters and Setters aus Platzgründen weggelassen...
}

Weitere Möglichkeiten lassen sich am Source der @DTOAttribute-Annotation erahnen:

@Retention(RetentionPolicy.SOURCE)
@Target(value = {ElementType.FIELD, ElementType.METHOD})
public @interface DTOAttribute {
    // reference to DTO.usage (when multiple DTO annotations exist per class)
    String usage() default "";
    // Reflector.path to take the attribute of the pojo FROM
    String path() default "";
    // name of the pojo.property to write the value TO
    String property() default "";
    // for dozer-mapping: name of a Converter class
    String converter() default "";
    // for dozer-mapping: true when call-by-reference
    boolean copyByReference() default false;
    // for dozer-mapping: true when one-way
    boolean oneWay() default false;
    // the type of the property, default is the same type as origin's
    String type() default "";
    // iterate-type setter method
    String addMethod() default "";
}

Alles, was nicht über die Annotation eingestellt wird, kann direkt im freemarker-Template (30 Zeilen groß) geändert werden, welches die eigentliche Codegenerierung durchführt.

Aber, wie sieht der Aufruf aus (z.B. aus Maven2 heraus)?

Anstelle vieler Parameter ruft das Groovyscript “Launcher.groovy” die Generierung auf und gibt dabei weitere Parameter an:

import java.util.*;
import com.agimatec.annotations.jam.*;
import com.agimatec.annotations.*;
def dtoClasses = new HashSet();
dtoClasses.addAll(classes.findAll { it.getAnnotation(DTO.class) != null });
dtoClasses.addAll(classes.findAll { it.getAnnotation(DTOs.class) != null });
generator = new JAMDtoGenerator();
generator.setTemplateDir("annomark/templates");
generator.addInstruction("java-pojo", "target/generated-src", null)
    .setUsageQualifier("edit")
    .setPrefix("Transfer")
    .setSuffix(".java")
    .setDefaultPackage("com.agimatec.model.transfer");

Die Konvertierung zwischen Transferobjekt und Sourceobjekt erledigt Dozer. Die Konfiguration für Dozer generiert ein weiteres Template.

generator.addInstruction("dozer-mapping", "target/generated-resources", "dozerMapping-generated.xml")
    .setUsageQualifier("edit")
    .setPrefix("Transfer")
    .setSuffix(".xml")
    .setDefaultPackage("com.agimatec.model.transfer");

Unsere Metadaten zur Validierung sowie die View-Transferklassen generieren wir mit weiteren Template.

Über Meinungen hierzu freuen wir uns!

OK, alternativ kann eine MDA-Plattform (z.B. openArchitectureWare) genutzt und die Templates den speziellen Bedürfnissen anpasst werden. Da unser Projekt eben kein MDA-Projekt ist und wir auch keinen Schwenk in diese Richtung geplant haben, fiel diese Möglichkeit weg.

Wir generieren dennoch eine Menge (Java, XML, Scripts etc.) und fahren gut damit. Dadurch bleiben große Teile des Systems automatisch konsistent. Anfangs wurde im Projekt wenig generiert, vieles redundant gepflegt. So nach und nach haben wir geeignete Kandidaten erkannt und durch generierte Artefakte ersetzt – schrittweise. Über die Erfahrungen und Tools, die dabei entstanden sind, möchte ich berichten.

Zunächst ein grober Überblick, was wir derzeit generieren:

• Die Datenbank modellieren wir für Postgres mit dem netten kleinen Tool DeZign.
  Leider speichert es das ER-Model nur im proprietären Format (kein XMI) oder generiert SQL-Scripte.
• Wir parsen mit unserem “dbtool” die SQL-Scripte und generieren mit Freemarker-Templates:
  • SQL-Scripte für Oracle (d.h. wir führen eine Transformation der Datentypen etc. durch)
  • SQL-Scripte für Tabellen mit historischen Daten und zugehörige Trigger (unterschiedlich für Oracle und Postgres)
  • Java-Klassen, annotiert als EJB3 Entities für Hibernate. Diese werden jedoch später manuell angepaßt!
• Aus den angepaßten EJB3-Klassen generieren wir:
  • Data-Transfer-Klassen (Value-Objects) zur Bearbeitung der Daten (“CRUD”)
  • Abgespeckte Data-Transfer-Klassen zur reinen Anzeige (“Light”)
  • XML-Dateien mit Metadaten (“mandatory”, “maxLength”, “default value”, “readonly”, “unique”, …)
  • XML-Dateien für den Dozer-Mapper, der zwischen Entities und DTO-Instanzen mappen/kopiert.

Für unsere Clients sind nur die DTO-Klassen sichtbar, nicht die Entities. Zur Generierung verwenden wir nur Freemarker-Templates, da diese bereits vielen Entwicklern verständlich waren. Wenn weitere Artefakte generiert werden sollen, kann dies ohne Änderung der Generator-Frameworks erfolgen.

Zwei “Tricks” sind es, die hierbei die Arbeit erheblich erleichtern und die weitere Blog-Posts wert sind:

1. Um vom ER-Tool unabhängig zu sein, verarbeiten wir die SQL-Scripte von DeZign als Input für die Generierung. Wir brauchen daher etwas Ähnliches wie einen SQL-Parser und ein Modell, um die Struktur der Datenbank abzubilden. Dieses Modell geht in die Freemarker-Templates ein und liefert die Informationen für die Generierung. Also mußte ein Framework dafür her: “dbtool” – auch bald OpenSource, sobald ich dazu komme. (Bei Interesse gerne nachfragen, dann geht es schneller. :-) )
2. Für die EJB3-Klassen haben wir – außer dem Java-Source, den wir um eigene Annotations “aufhübschen” – kein (UML-)Modell. Wir parsen daher die Klassen und nutzen die Annotations, um daraus ein Modell zu erzeugen, was mit Freemarker verarbeitet wird. Dieses Framework – auch als OpenSource geplant (s.o.) – nannten wir “annomark“, da es i.W. (neben Freemarker) auf Gram (Groovy+JAM) und Annogen basiert. Diese Projekte sollte man sich einmal anschauen, obwohl es hier leider schon länger keine neuen Releases gegeben hat.

Diese zusätzliche Semantik der Klassen kann für diverse Verwendungszwecke als Metadaten abgelegt werden, aber wie und wozu?

Die bekannten Ansätze fokussieren meist ausschließlich auf die Validierung von Objekten (z.B. das altgediente commons-validator, das seine Struts-Wurzeln nie leugnen konnte, der Hibernate-Validator, aus dessen Ecke nun die JSR 303 (bean-validation) entsprungen ist und andere Exoten).

Gleich vorweg: mit JSR 303 wird endlich eine Lücke für einen Standard zur Definition von Constraints mit Hilfe von Annotations geschlossen.

Wir, ansonsten fleißige Open Source Nutzer, haben uns vor über einem Jahr entschlossen, ein neues Validation-Framework zu entwicklen, um Metadaten flexibel definieren zu können. Nebenbei implementiert es bereits jetzt als vollständiges bean-validation framework die als Draft vorhandene JSR 303.

Wie hätten Sie Ihre Metadaten denn gerne…

a) als Annotations an den POJO-Klassen?

So standardisiert es JSR 303. Beispiele erübrigen sich hier, ausführliche Erläuterungen gibt es z.B. bei Bloggers/BeanValidationSneakPeekPartIIIGroupsAndPartialValidation

b) als XML-Dateien oder aus der Datenbank?

Das hat den Vorteil, dass an den Klassen nichts geändert werden braucht (z.B. wenn diese generiert werden) und dass die Metadaten einer Klasse aus mehreren XML-Files zusammengesetzt werden (Dekoration). Sie können auch zur Laufzeit geändert werden.

c) dynamisch angefragt von einem Webservice?

Dadurch können die Metadaten im Server gepflegt und benutzerspezifisch zurückgegeben werden, was z.B. zur Folge hat, dass manche Felder nach einem Benutzerwechsel readonly werden, ausgeblendet werden, usw.

d) eine Kombination aus a-c …

… gewürzt mit neuen Ideen?

Jetzt noch schnell ein Crashkurs mit Source-Beispielen:

Wer mehr sehen will, kann sich der Test-Sourcen oder des Wikis bedienen (siehe agimatec-validation).

Wir geben ein paar Metadaten für Klasse “com.sample.Customer” an:

<beanInfos>
<bean id="com.sample.Customer">
<feature key="tooltip"><value class="string">König Kunde</value></feature>
<property name="firstName" maxLength="40"/>
<property name="identification">
<feature key="readonly"><value class="boolean">true</value></feature>
</property>
</bean>
</beanInfos>

Fener besteht die Möglichkeit mit <relationship/> auch ganze Objektnetze zu definieren. Die üblichen Constraints (maxLength, mandatory) sind vordefinierte Attribute. Frei wählbar sind weitere “Features”, die an der Klasse oder einer Property hängen können.

Gerade die Standardconstraints können z.B. schon in den javax.persistence-Annotations (@Column) etc. bei den EJB3-Entites definiert worden sein. Wir schreiben Code ungern doppelt, daher generieren wir die XML der <beanInfos> mit diesen Informationen automatisch (aber zu Codegenerierung ein andermal mehr).

Wie verwendet man Metainformationen?

Initialisierung

Angenommen, die XML-Datei liegt als “beanInfos.xml” im Classpath, dann können die darin enthaltenen Definitionen so registiert werden:

MetaBeanManagerFactory.getRegistry().addResourceLoader("beanInfos.xml");

In der Reihenfolge der Registierung werden die Informationen verarbeitet. Mehrere XML-Dateien können dabei nacheinander das gleiche Bean (gleiche <bean id=”"/>) ergänzen – der Letzte gewinnt.

Verwendung

Nur einige Beispiele…

1. Zugriff auf die Metadaten ohne Validierung

MetaBeanFinder finder = MetaBeanManagerFactory.getFinder();
MetaBean metaBean = finder.findForId("com.sample.Customer");
String tooltip = metaBean.getFeature("tooltip");

2. Überprüfung, ob eine Instanz den Constraints entspricht (klassische Validierung):

Customer object = //... von woher auch immer;
BeanValidator validator = new BeanValidator();

ValidationResults results = validator.validate(object, metaBean);
if(!results.isEmpty()) { // Fehler gefunden }

3. Validierung der Parameter eines Methodenaufrufs bei Aufruf eines Webservice:

Das Interface:

import com.agimatec.utility.validation.integration.Validate;

@javax.jws.WebService
interface MyWebservice {
@Validate void saveCustomer(@Validate Customer customer);
}

Die Validierung:

Method m = // saveCustomer
Object[] params =  // Array Parametern

ValidationResults results = validator.validateCall(m, params);

4. Aus den Metadaten einen JSON String für eine AJAX GUI erzeugen

JSONGenerator jsonGenerator = new JSONGenerator();
String jsonString = jsonGenerator.toJSON(MetaBean metaBean);
String jsonStringAll = jsonGenerator.toJSON(finder.findAll().values());

In einem Servlet kann für einzelne oder alle Beans so die Metainformation ausgegeben werden.

Seitdem wir erst einmal diese Grundlagen im Griff hatten, sind uns noch mehr Einsatzmöglichkeiten für Metainformationen eingefallen, die zur Steigerung unserer Produktivität, besserem Abstraktionsniveau in der Software und Schrumpfung in den Sourcen geführt haben.