24 Feb 2013

Behavior Driven Development mit JBehave

von | Veröffentlicht in: Java, test-driven development | 0

Behavior Driven Development (BDD) – ist eine Kombination aus Test-Driven-Development (TDD) und Domain-Driven-Design (DDD). TDD wird in der agilen Softwareentwicklung eingesetzt und ist ein Prozess, bei dem zuerst Testfälle konzeptioniert und erst im Anschluss die Funktionalität umgesetzt wird. Nähere Informationen hierzu, finden sich auch in meinem früheren Artikel http://martinzimmermann1979.wordpress.com/2011/12/09/testgetriebene-entwicklung-mit-junit-easymock-und-spring. Auch DDD orientiert sich an der agilen Softwareentwicklung, sieht aber die Fachlichkeit einer Anwendung im Vordergrund. Anforderungen werden in einer ubiquitären Sprache beschrieben, welche von allen am Softwareentwicklungsprozess beteiligten Personen verstanden wird.

Auch bei BDD kommt eine ubiquitäre Sprache zum Einsatz, um fachliche Anforderungen in sogenannten Szenarios zu definieren. Das hier definierte Verhalten wird später mit automatisierten Tests überprüft. Bei der Beschreibung werden Schlüsselworte verwendet, damit die Sprache von den Testfällen korrekt interpretiert werden kann:

Given: Vorraussetzungen für den Testfall
When: Aktion die ausgeführt wird
Then: Überprüft ob das erwartete Verhalten eingetreten ist

Nach einer Aktion kann zunächst das Zwischenergebnis geprüft und anschließend mit weiteren Aktionen und Prüfungen fortgefahren werden. Folgen mehrere Sätze des gleichen Typs, können sie mit and verknüpft werden.

Kommen wir nun zu einem konkreten Beispiel. Es besteht die fachliche Anforderung, dass ein vorhandener Benutzer aktiviert werden kann. Diese Funktionalität wird im UserService realisiert. Das zu testende Verhalten wird mit folgendem Szenario beschrieben:
jbehave_scenario

Das Szenario wird unter src/test/resources/de/mz/jbehave/user_scenarios.story gespeichert und wird dem Testfall als Grundlage zur Ausführung dienen.

Als BDD-Framework wird JBehave in der aktuellen Version 3.7.5 eingesetzt, welches bequem als Maven Dependency eingebunden werden kann:

<properties>
<jbehave.version>3.7.5</jbehave.version>
</properties>

<dependency>
<groupId>org.jbehave</groupId>
<artifactId>jbehave-core</artifactId>
<version>${jbehave.version}</version>
<scope>test</scope>
</dependency>

Nun wird der UserService erstellt, der folgende Methoden implementiert:

void addUser(User user);

User getUser(String name);

boolean activateUser(String name);

Der hier verwendete User besteht aus den zwei Eigenschaften:

private String name;
private boolean active;

Nun wird der Testfall src/test/java/de/mz/jbehave/UserActivationStory erstellt, der somit die gleiche  Verzeichnisstruktur besitzt, wie das zuvor erstellte Szenario. Es handelt sich um eine Unterklasse von Embedder. An den verwendeten Annotations ist bereits ersichtlich, wie die textuelle Beschreibung mit den implementierten Testfällen in Verbindung steht. Jeder Satz des Szenarios, ist in einer Annotation der UserActivationStory wiederzufinden:

public class UserActivationStory extends Embedder {

private UserService userService = new UserServiceImpl();

@Given(„a user with the name $name“)
public void addUser(String name) {
User user = new User();
user.setName(name);
userService.addUser(user);
}

@When(„the user with the name $name will be activated“)
public void activateUser(String name) {
userService.activateUser(name);
}

@Then(„the user with the name $name should be active“)
public void userShouldBeActive(String name) {
User user = userService.getUser(name);
Assert.assertEquals(name, user.getName());
Assert.assertTrue(user.isActive());
}
}

Um die Wiederverwendbarkeit der Test-Methoden zu erhöhen, können Parameter benutzt werden. Innerhalb der Annotation werden sie mit dem Dollar-Symbol gekennzeichnet und stehen in der Test-Methode als Übergabe-Parameter zur Verfügung. Bei der Szenario-Beschreibung wird einfach der entsprechende Wert angegeben, in obigen Beispiel also mustermann.

Im gleichen Package wie der Testfall wird nun ein Runner zum Ausführen des selbigen erstellt. Dieser erbt von JUnitStory und benötigt eine Configuration und eine StepFactory. JBehave verwendet das Convention over Configuration Prinzip, so dass hier nur Einstellungen konfiguriert werden müssen, die nicht der Norm entsprechen. Will man während der Testausführung Meldungen auf der Konsole erhalten, muss ein StoryReportBuilder definiert werden. Als StepFactory wird die InstanceStepsFactory verwendet, welche die Configuration und die auszuführende Story-Klasse benötigt:

public class UserScenarios extends JUnitStory {

@Override
public Configuration configuration() {
return new MostUsefulConfiguration()
.useStoryReporterBuilder(new StoryReporterBuilder().withDefaultFormats().withFormats(Format.CONSOLE, Format.TXT));
}

@Override
public InjectableStepsFactory stepsFactory() {
return new InstanceStepsFactory(configuration(), new UserActivationStory());
}
}

Ohne weitere Konfiguration, wird die Szenario-Beschreibung im gleichen Package wie der Testfall gesucht. Möchte man dies ändern, so kann ein anderer StoryLoader verwendet werden:

configuration.useStoryLoader(new LoadFromURL(„pathToResource“));

Für dieses Beispiel ist das aber nicht nötig, so dass die Klasse UserScenarios nun als JUnit-Test ausgeführt werden kann. Im Anschluss befindet sich im target unter jbehave/view die Datei reports.html, die Auskunft über den Erfolg des Testfalls gibt.

Sollen die JBehave Testfälle automatisch beim Bauen mit maven ausgeführt werden, so kann das jbehave-maven-plugin verwendet werden. Hier die Anpassungen in der pom.xml:

<build>
<finalName>de.mz.jbehave</finalName>
<plugins>
<plugin>
<groupId>org.jbehave</groupId>
<artifactId>jbehave-maven-plugin</artifactId>
<version>${jbehave.version}</version>
<executions>
<execution>
<id>run-stories-as-embeddables</id>
<phase>integration-test</phase>
<configuration>
<scope>test</scope>
<includes>
<include>**/*Scenarios.java</include>
</includes>
</configuration>
<goals>
<goal>run-stories-as-embeddables</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

Sofern sich die Test-Klassen in src/test/java befinden, muss der Scope explizit auf test gesetzt werden. Andernfalls werden nur Klassen in src/main/java gefunden. Inkludiert werden alle Java-Klassen die auf Scenarios enden. Nun kann JBehave als maven goal ausgeführt werden:

mvn integration-test

Leider sind die Reports komplett unformatiert und werden ohne css-Styles generiert. Um grafisch ansprechende Reports zu erzeugen, wird das maven-dependency-plugin benötigt, welches zwei hierfür notwendige JBehave Artefakte lädt:

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>unpack-jbehave-site-resources</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jbehave.site</groupId>
<artifactId>jbehave-site-resources</artifactId>
<version>3.1.1</version>
<type>zip</type>
<outputDirectory>${project.build.directory}/jbehave/view</outputDirectory>
</artifactItem>
<artifactItem>
<groupId>org.jbehave</groupId>
<artifactId>jbehave-core</artifactId>
<version>${jbehave.version}</version>
<outputDirectory>${project.build.directory}/jbehave/view</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>

Nach erneutem Ausführen der Integrations-Tests sieht der Report nun so aus:jbehave_statistic

Sofern die Eclipse IDE mit dem m2e Plugin verwendet wird, erscheint nach Anpassung der pom.xml folgender Fehler in der Problem View:

maven-dependency-plugin (goals „copy-dependencies“, „unpack“) is not supported by m2e.

Über die Option „Permanently mark goal unpack in pom.xml as ignored in Eclipse build“ lässt sich der Fehler ignorieren. Die Funktionalität wird hierdurch nicht beeinträchtigt. Will man JBehave in einem bestehenden Projekt einsetzten, benötigt man zumeist eine Spring Integration. Hierfür werden zwei weitere Maven Dependencies benötigt:

<properties>
<spring.version>3.1.1.RELEASE</spring.version>
</properties>

<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-test</artifactId>
<version>${spring.version}</version>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.jbehave</groupId>
<artifactId>jbehave-spring</artifactId>
<version>${jbehave.version}</version>
</dependency>

Im Folgenden werden zwei Spring-Kontexte erstellt, der eine kommt während der Laufzeit zum Einsatz, während der andere für die Integrations-Tests benötigt wird. Zunächst wird unter src/main/resources/applicationContext.xml der Laufzeit-Kontext erstellt. Er beinhaltet den zu testenden UserService und aktiviert das autowiring:

<context:annotation-config />

<bean id=“userService“ class=“de.mz.jbehave.UserServiceImpl“/>

Für die Integrations-Tests wird unter src/test/resources/applicationTestContext.xml ein weiterer Kontext erstellt, der die UserActivationStory beinhaltet und den Laufzeit-Kontext importiert. So ist gewährleistet, dass Laufzeit- und Test-Kontext sich bis auf die zusätzlichen Test-Klassen gleichen:

<import resource=“classpath:applicationContext.xml“/>

<bean id=“userActivationStory“ class=“de.mz.jbehave.UserActivationStory“/>

Nun wird die Runner-Klasse UserScenarios angepasst. Statt der InstanceStepsFactory wird die SpringStepsFactory verwendet, die zusätzlich zur Configuration den Spring-Test-Kontext erhält. Die configuration-Methode kann aus obigem Beispiel übernommen werden:

@Override
public InjectableStepsFactory stepsFactory() {
ApplicationContext context = new SpringApplicationContextFactory(„classpath:applicationTestContext.xml“).createApplicationContext();
return new SpringStepsFactory(configuration(), context);
}

Die Klasse UserActivationStory erstellt nun den UserService nicht mehr selber, sondern erhält ihn per Dependency Injection:

@Autowired
private UserService userService;

So lassen sich Integration-Tests mittels JBehave auch in Spring-Projekten ausführen, so dass das BDD-Framework in vielen Projekten einfach zu integrieren ist.

Zur Unterstützung beim Erstellung von Szenarios, kann das JBehave Eclipse Plugin installieren werden http://jbehave.org/reference/eclipse/updates/. Bei mir führte dies allerdings wiederholt zu einem einfrieren von Eclipse, so dass ich mich von dem Plugin wieder getrennt habe.

16 Feb 2013

HTML5 und Javascript zur Darstellung von Graphen

von | Veröffentlicht in: javascript, js | 0

Im folgenden Beispiel soll ein Graph dargestellt und kontinuierlich aktualisiert werden, dessen Daten asynchron von einer Web-Ressource nachgeladen werden. Hierfür kommt die HTML5/Javascript Library RGraph (http://www.rgraph.net/) zum Einsatz, die im privaten Gebrauch umsonst verwendet werden darf. Es ist lediglich ein Verweis auf die Web-Seite von RGraph notwendig. Auf dieser kann die aktuelle Version der Library in Form eines ZIP-Archives bezogen werden. Aus dem Verzeichnis RGraph/libraries werden für dieses Beispiel die folgenden Javascript-Dateien benötigt:

  • jquery.min.js
  • RGraph.common.core.js
  • RGraph.line.js

Diese werden in die HTML-Seite eingebunden:

<script type=“text/javascript“ src=“js/jquery.min.js“ />
<script type=“text/javascript“ src=“js/RGraph.common.core.js“ />
<script type=“text/javascript“ src=“js/RGraph.line.js“ />

Die Grafik wird im HTML5-Element Canvas integriert:

<canvas id=“myCanvas“ width=“600″ height=“250″>[No canvas support]</canvas>

Am Ende der HTML-Seite wird das nun folgende Javascript eingebunden. Zuerst werden die Graph-Daten mit null initialisiert:

d1=[];

for (var i=0; i<250; ++i) {
d1.push(null);
}

Anschließend wir die Funktion getGraph implementiert. Beim ersten Aufruf wird ein Line-Graph erstellt, spätere Aufrufe geben das bereits erzeugte Objekt zurück. Im Konstruktor wird die Id des Canvas und das Daten Array übergeben. Eine vollständige Liste aller möglichen Eigenschaften inklusive ihrer Default-Werte können in RGraph.line.js eingesehen werden:

function getGraph(id, d1)
{
if (!window.line) {
window.line = new RGraph.Line(id, d1);
window.line.Set(‚chart.xticks‘, 100);
window.line.Set(‚chart.title.xaxis‘, ‚Time >>>‘);
window.line.Set(‚chart.title.yaxis‘, ‚Number of Worker‘);
window.line.Set(‚chart.title.vpos‘, 0.5);
window.line.Set(‚chart.title‘, ‚Assigned Jobs‘);
window.line.Set(‚chart.title.yaxis.pos‘, 0.5);
window.line.Set(‚chart.title.xaxis.pos‘, 0.5);
window.line.Set(‚chart.colors‘, [‚red‘]);
window.line.Set(‚chart.linewidth‘,3);
window.line.Set(‚chart.yaxispos‘, ‚right‘);
window.line.Set(‚chart.ymax‘, 30);
window.line.Set(‚chart.xticks‘, 25);
}

return window.line;
}

Nun wird die drawGraph-Funktion erstellt, die einen asynchronen AJAX-Aufruf auf eine Web-Ressource durchführt. In diesem Beispiel liefert sie einen Number-Wert, der im Graph dargestellt werden soll. Auf das Ergebnis kann in der übergebenen Callback-Funktion zugegriffen werden:

function drawGraph() {
RGraph.AJAX(‚http://server_url‘, myCallback);
}

Die Callback-Funktion setzt zunächst das Canvas-Element zurück, um anschließend den Graphen aus der getGraph-Funktion neu zu zeichnen. Über this.responseText erhält man den Rückgabe-Wert der Web-Ressource, welcher zu einer Number konvertiert und anschließend im Daten-Array hinterlegt wird. Sofern das Daten-Array mehr als die maximale Anzahl von 250 Elementen besitzt, wird das erste Element entfernt, so dass die Größe des Graphen trotz fortlaufender Aktualisierung gleich bleibt. Anschließend wird das neue Daten-Array dem Graphen-Objekt zugewiesen und die drawGraph-Funktion mit einer Verzögerung von 100 ms erneut aufgerufen:

function myCallback() {
RGraph.Clear(document.getElementById(„myCanvas“));

var graph = getGraph(‚myCanvas‘, d1);
graph.Draw();
var data = this.responseText;
d1.push(Number(data));

if (d1.length > 250) {
d1 = RGraph.array_shift(d1);
}

if (document.all && RGraph.isIE8()) {
alert(‚[MSIE] Sorry, Internet Explorer 8 is not fast enough to support animated charts‘);
} else {
graph.original_data[0] = d1;
setTimeout(drawGraph, 100);
}
}

Zum Schluss muss die drawGraph-Funktion einmal Initial ausgeführt werden, um die Graphen-Darstellung zu starten:

drawGraph();

Das Resultat kann dann – abhängig von den Daten der Web-Ressource – wie folgt aussehen:chart_example

RGraph wird von allen gängigen Browsern in den jeweils aktuellen Versionen unterstützt. Auch der Internet Explorer akzeptiert ab Version 9 das HTML5-Tag Canvas.

11 Nov 2012

Hibernate 4.x mit Spring 3.x

von | Veröffentlicht in: Hibernate, Java, spring | 0

Der nachfolgende Artikel beschreibt die Verwendung des ORM – Object-Relational Mapping – Frameworks Hibernate 4 inklusive der Hibernate Integration von Spring 3, wobei letztere auch die Vorgängerversion Hibernate 3 unterstützt. Als Persistenz-Schicht wird die In-Memory Datenbank HSQLDB verwendet. Es entfällt also die Installation einer Datenbank, da für den Einsatz der HSQLDB lediglich die entsprechende Library eingebunden werden muss.

In diesem Beispiel sollen Benutzer- und Adressdaten persistiert werden, wobei einem Benutzer-Eintrag beliebig viele Adress-Informationen zugewiesen werden können. Es gibt also ein 1..n Mapping zwischen Benutzer und Adressen. Weiterhin wird ein DAO – Data Access Object – implementiert, welches die CRUD – Create/Read/Update/Delete – Datenbank Operationen für die Haupt-Entität (Benutzer) zur Verfügung stellt.

Im ersten Schritt wird ein Maven-Projekt erstellt, in dessen pom.xml die folgenden Dependencys ergänzt werden:

<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<version>4.1.7.Final</version>
</dependency>

<dependency>
<groupId>cglib</groupId>
<artifactId>cglib</artifactId>
<version>2.2</version>
</dependency>

<dependency>
<groupId>org.hsqldb</groupId>
<artifactId>hsqldb</artifactId>
<version>2.2.9</version>
</dependency>

<dependency>
<groupId>commons-dbcp</groupId>
<artifactId>commons-dbcp</artifactId>
<version>1.4</version>
</dependency>

<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>3.1.0.RELEASE</version>
</dependency>

<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>3.1.0.RELEASE</version>
</dependency>

<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-orm</artifactId>
<version>3.1.0.RELEASE</version>
</dependency>

Zuerst werden die Entitäten erstellt, welche die Tabellen der relationalen Datenbank als Java-Klassen repräsentieren. Da der Benutzer Kenntnis über die zu ihm gehörenden Adressen benötigt, umgekehrt aber keine Verknüpfung notwendig ist, kennt die Adress-Entität lediglich sich selber. Ein guter Grund mit dieser zu beginnen:

@Entity
public class Address {

@Id
@GeneratedValue
private Long id;
private String street;
private String city;

// getter setter methods

}

Die Klasse Address wird mit der Annotation Entity versehen, um sie als solche zu kennzeichnen. Weiterhin erhält sie neben den benötigten Eigenschaften (Straße, Stadt, …) einen Identifier. Die entsprechende Annotation definiert diesen als Primär-Schlüssel, während GeneratedValue dafür sorgt, dass sein Wert automatisch von der Datenbank vergeben werden soll.

Nun kann auch die Klasse User mit Zugriff auf die Adress-Datensätze erzeugt werden:

@Entity
public class User {

@Id
@GeneratedValue
private Long id;
private String forname;
private String lastname;

@OneToMany
@Cascade(value=CascadeType.ALL)
private List<Address> addresses;

// getter setter methods

}

Da ein User eine beliebige Anzahl an Adressen erhalten kann, wird hier als Mapping die OneToMany-Annotation verwendet. Weiterhin wird der CascadeType ALL gewählt, der unter anderem die CascadeTypen SAVE_UPDATE und DELETE beinhaltet. Hiermit wird erreicht, dass beim Speichern des Users gleichzeitig seine Adress-Daten persistiert werden. Wäre der CascadeTyp SAVE_UPDATE nicht gewählt, müssten Adress- und Benutzerdaten separat gespeichert werden, wobei ein Benutzer nur auf Adressen verweisen darf, die bereits in der Datenbank existieren. Der CascadeType DELETE sorgt dafür, dass beim Löschen eines Benutzers auch seine Adressen aus der Datenbank entfernt werden.

Wie man an obigem Beispiel erkennt, gibt es Attribute die sich in den Entitäten wiederholen. In diesem Beispiel ist es nur der Identifier, der sowohl beim User als auch bei der Adresse vorkommt. Aber auch das Erstellungs- und letztes Änderungsdatum einer Entität wären Kandidaten, die zu Code-Wiederholung führen könnten. Doppelte Attribute können in eine gemeinsame Oberklasse ausgelagert werden, sofern die Oberklasse mit MappedSuperclass annotiert wird:

@MappedSuperclass
public abstract class AbstractEntity {

@Id
@GeneratedValue
private Long id;

// getter setter methods
}

Nachdem die Entitäten erstellt wurden, soll nun der UserDAO erzeugt werden, der sukzessive um die CRUD-Operationen erweitert wird. Hierfür benötigt er lediglich die SessionFactory. Wer bislang das HibernateTemplate verwendete, wird feststellen, dass dies unter Hibernate 4 nicht mehr unterstützt wird. Das ist nicht weiter verwunderlich, da dessen Verwendung bereits seit Hibernate 3.0.1 obsolet ist. Stattdessen kann bei gültigem Transaktions-Management über die SessionFactory auf die aktuelle Session zugegriffen und auf dieser Datenbank-Operationen ausgeführt werden. Auf die Konfiguration des Transaktions-Management wird später noch eingegangen. Aber zurück zum UserDAO, der zunächst nur aus folgendem Rumpf besteht:

public class UserDAO {

private SessionFactory sessionFactory;

// methods for crud operations
// and a setter method for the sessionFactory
}

Wenden wir uns nun der Spring Konfiguration zu, die in der Datei src/main/resources/applicationContext.xml erstellt wird. Zunächst muss die Verbindung zur Datenbank in einer Datasource konfiguriert werden. Es werden Details zum Datenbanktreiber, URL zur Datenbank, Benutzername und Passwort benötigt.

<bean id=“dataSource“ class=“org.apache.commons.dbcp.BasicDataSource“ destroy-method=“close“>
<property name=“driverClassName“ value=“org.hsqldb.jdbcDriver“/>
<property name=“url“ value=“jdbc:hsqldb:mem:myDB“/>
<property name=“username“ value=“sa“/>
<property name=“password“ value=““/>
</bean>

Bei Verwendung einer HSQLDB kommt der Treiber org.hsqldb.jdbcDriver zum Einsatz. Die URL besteht aus drei Teilen, wobei der erste für alle HSQLDBs gleich ist und jdbc:hsqldb: lauten muss. Der Prefix mem: signalisiert, dass es sich um eine In-Memory Datenbank handelt, während der letzte Teil den Namen der zu verwendeten Datenbank – myDB – bestimmt.

Will man später von einer In-Memory Datenhaltung auf eine dauerhafte Persistierung wechseln, kann die Datasource ersetzt und hier die Verbindungsdaten an die neue Datenbank angepasst werden.

Nun soll die SessionFactory definiert werden, die der UserDAO für die Datenbank-Operationen benötigt:

<bean id=“sessionFactory“ class=“org.springframework.orm.hibernate4.LocalSessionFactoryBean“>
<property name=“dataSource“ ref=“dataSource“/>
<property name=“packagesToScan“>
<list>
<value>de.mz.entity</value>
</list>
</property>
<property name=“hibernateProperties“>
<props>
<prop key=“hibernate.dialect“>org.hibernate.dialect.HSQLDialect</prop>
<prop key=“hibernate.hbm2ddl.auto“>create</prop>
<prop key=“hibernate.show_sql“>true</prop>
</props>
</property>
</bean>

Die SessionFactory braucht Zugriff auf die bereits definierte Datasource und verwaltet alle verfügbaren Entitäten. Hierzu muss entweder eine Liste aller annotierten Klassen – User und Address – über das Property annotatedClasses angegeben werden oder es wird, wie in diesem Beispiel, eine Liste von zu scannenden Packages übergeben. Anschließend können noch Hibernate-Eigenschaften konfiguriert werden, wobei die Angabe des Datenbank-Dialekts zwingend nötig ist. Bislang hat nur die Datasource Informationen über die zu konnektierende Datenbank. Aber auch Hibernate muss wissen, um welche Datenbank es sich handelt, damit die entsprechende Kommunikation gewählt werden kann. Für eine HSQLDB wird der Dialekt org.hibernate.dialect.HSQLDialect verwendet. Die weiteren Einstellungen können die Entwicklung erheblich erleichtern. So sorgt die Property hibernate.hbm2ddl.auto mit dem Wert create dafür, dass Hibernate die Datenbank-Struktur mit Tabellen, Primär- und Fremdschlüsseln automatisch anlegt. Erhält hibernate.show_sql den Wert true, wird jedes von Hibernate ausgeführte SQL-Statement geloggt und kann so nachvollzogen werden. Dies ist zwar für eine Live-Umgebung tödlich, kann aber beim Aufsetzten eines neuen Projektes durchaus hilfreich sein.

Wie bereits erwähnt, wird ein Transaktion-Management benötigt, damit die SessionFactory den UserDAO mit einer gültigen Session versorgen kann. Die Transaktionen sollen dabei über Annotationen definierbar sein. Zunächst wird der HibernateTransactionManager konfiguriert, der Zugriff auf die SessionFactory benötigt:

<bean id=“transactionManager“ class=“org.springframework.orm.hibernate4.HibernateTransactionManager“>
<property name=“sessionFactory“ ref=“sessionFactory“ />
</bean>

Um die Steuerung von Transaktionen mit der Annotation Transactional zu ermöglichen, muss dieses Verhalten aktiviert werden:

<tx:annotation-driven/>

Sofern der Name des TransactionManagers nicht transactionManager lauten würde, müsste hier noch der entsprechende Name angegeben werden:

<tx:annotation-driven transaction-manager=“transactionManager“/>

Zu guter Letzt muss der UserDAO in der Spring-Konfiguration aufgenommen werden und Zugriff auf die SessionFactory erhalten:

<bean id=“userDAO“ class=“de.mz.dao.UserDAO“>
<property name=“sessionFactory“ ref=“sessionFactory“ />
</bean>

Nun wird der UserDAO um die erste CRUD-Operationen erweitert, wobei mit dem Speichern eines Benutzers begonnen wird:

@Transactional
public User save(User user) {
Session session = sessionFactory.getCurrentSession();
session.saveOrUpdate(user);
return user;
}

Die save-Methode wird mit der Annotation Transactional versehen. Beim Aufruf der Methode wird nun eine Transaktion erzeugt, die erst beim Verlassen wieder geschlossen wird, womit dann die Datenbank-Änderungen wirksam werden. Träte zuvor eine Exception auf, so fände keine der Datenbank-Operationen der save-Methode statt. Weiterhin sorgt die Transaktion dafür, dass die SessionFactory eine gültige Session liefert, über die der Benutzer gespeichert werden kann.

Durch die Verwendung der saveOrUpdate-Methode kann die gleiche Methode zum Anlegen und Aktualisieren von Benutzerdaten verwendet werden. Besitzt der User keine Id, vergibt Hibernate den Primär-Schlüssel und führt das SQL-Statement Insert aus, andernfalls wird ein Update ausgeführt.

Anschließend wird zum Testen der Anwendung eine Klasse mit ausführbarer main-Methode erstellt, die den Spring-Context hochfährt und den UserDAO aus selbigem lädt:

ApplicationContext context = new ClassPathXmlApplicationContext(„applicationContext.xml“);
UserDAO userDAO = (UserDAO) context.getBean(„userDAO“);

Nun wird ein Benutzter mitsamt zugehöriger Adresse erstellt und über den UserDAO gespeichert:

List<Address> addresses = new ArrayList<Address>();
Address address = new Address();
address.setCity(„Cologne“);
addresses.add(address);

User user = new User();
user.setForname(„Max“);
user.setLastname(„Mustermann“);
user.setAddresses(addresses);

userDAO.save(user);

Dank der Hibernate-Einstellung show_sql lässt sich in den Log-Meldungen gut nachvollziehen, was für SQL-Statements Hibernate durchführt. Zuerst werden die Datenbank-Tabellen erstellt:

Hibernate: create table Address (id bigint generated by default as identity (start with 1), city varchar(255), street varchar(255), primary key (id))
Hibernate: create table User (id bigint generated by default as identity (start with 1), forname varchar(255), lastname varchar(255), primary key (id))
Hibernate: create table User_Address (User_id bigint not null, addresses_id bigint not null, unique (addresses_id))

Die Tabellen Address und User entsprechen unseren Java-Entitäten, während die Tabelle User_Address als Mapping-Tabelle zwischen Benutzer und Adressen fungiert. Anschließend werden der Mapping-Tabelle per constraints Fremdschlüssel auf die Haupt-Entitäten hinzugefügt:

Hibernate: alter table User_Address add constraint FK838B1F807A26EF9A foreign key (User_id) references User
Hibernate: alter table User_Address add constraint FK838B1F805ABA690C foreign key (addresses_id) references Address

Als nächstes werden nun die Benutzerdaten gespeichert. Es lässt sich gut nachvollziehen wie aufgrund des CascadeTypes SAVE_UPDATE der Benutzer und die dazugehörigen Adressen gespeichert werden. Natürlich darf auch der Eintrag in der Mapping-Tabelle nicht fehlen:

Hibernate: insert into User (id, forname, lastname) values (default, ?, ?)
Hibernate: insert into Address (id, city, street) values (default, ?, ?)
Hibernate: insert into User_Address (User_id, addresses_id) values (?, ?)

Die ersten zwei CRUD-Operationen wurden umgesetzt, als nächstes sollen Benutzer-Daten aus der Datenbank ausgelesen werden. Hierzu wird der UserDAO um die find-Methode erweitert:

@Transactional
public List<User> find() {
Criteria criteria = sessionFactory.getCurrentSession().createCriteria(User.class);
List<User> users = criteria.list();
return users;
}

Hibernate bietet verschiedene Möglichkeiten, um Datenbank-Abfragen umzusetzen, so kann auf einer Session ein HQL- (Hibernate Query Language) oder SQL-Statement ausgeführt oder wie in diesem Beispiel eine Criteria erstellt werden. Criterias bieten die Möglichkeit Objekt-Orientierte-Abfragen formulieren zu können. Wie auf einer Criteria Einschränkungen definiert werden können, wird im Folgenden noch erläutert. Zunächst soll nur eine Liste aller Benutzer zurückgegeben werden.

Bei der Verarbeitung der Ergebnisliste ist zu beachten, dass Hibernate verschiedene FetchMode zum Umgang mit verknüpften Entitäten bietet. Per Default ist dies Lazy-Loading, wobei verknüpfte Entitäten nur geladen werden, sofern auf sie zugegriffen wird. In diesem Beispiel werden die Adress-Datensätze nicht geladen, da innerhalb der Transaktion kein Zugriff stattfindet. Nach Abschluss der Transaktion – also beim Verlassen der find-Methode – kann nicht mehr auf sie zugegriffen werden, ohne dass eine LazyLoading–Exception geworfen wird:

org.hibernate.LazyInitializationException: could not initialize proxy – no Session
at org.hibernate.collection.internal.AbstractPersistentCollection.initialize(AbstractPersistentCollection.java:430)
at org.hibernate.collection.internal.AbstractPersistentCollection.read(AbstractPersistentCollection.java:121)
at org.hibernate.collection.internal.PersistentBag.iterator(PersistentBag.java:266)

Wenn die Transaktion im verarbeitenden Service gestartet würde – nicht wie hier im UserDAO – wäre der Zugriff auf die entsprechenden Adress-Daten möglich. Hierbei wird der Vorteil des Lazy-Loadings ausgenutzt, es werden nur Daten geladen, die auch tatsächlich benötigt werden. Bei verteilten Systemen ist dies natürlich nicht unbedingt so möglich. Benötigt ein Client Adress-Informationen, die im Server geladen werden, so ist hier die Session bereits geschlossen. Daher kann für Entity-Verknüpfungen, die zwangsläufig mit der Haupt-Entität geladen werden sollen, der FetchMode Eager-Loading verwendet werden. Hier werden beim Laden des Benutzers direkt alle Adressen mitgeladen. Dies wird in der Annotation OneToMany definiert, die zusätzlich das Attribut fetch erhält. Die Property addresses der Klasse User besitzt nun folgende Annotationen:

@OneToMany(fetch=FetchType.EAGER)
@Cascade(value=CascadeType.ALL)
private List<Address> addresses;

Für große Daten-Mengen, die nicht immer benötigt werden, bietet sich dieses Verfahren natürlich nicht an. Hier kann das DTO – Data Transfair Object – Pattern zum Einsatz kommen. Hierbei wird nicht die User-Entity selber zum Client geschickt, sondern ein UserDTO, welches aber die gleichen Attribute besitzt. Bei der Anforderung der Daten werden die mitzuladenden Abhängigkeiten der Serverseite mitgeteilt, so dass die Antwort alle benötigten Daten in Form von DTOs beinhaltet. In unserem Beispiel würden beim Server die Benutzerdaten mitsamt der Adress-Datensätze angefragt werden. Sowohl die User– als auch die Adress-Daten werden in DTOs umgewandelt, wobei das UserDTO die Adressen in Form einer Liste von AddressDTOs besitzt. Da die Konvertierung innerhalb einer gültigen Session stattfindet, kommt es bei diesem Verfahren zu keiner LazyLoading–Exception und es werden nur die Daten geladen, die der Client auch tatsächlich benötigt.

Der Nachteil dieses Verfahrens liegt auf der Hand, bei jeder Client-Server-Kommunikation müssen DTOs in Entitäten und anschließend wieder zurück in DTOs konvertiert werden. Außerdem gibt es für jede Entität eine entsprechendes DTO, was zu dupliziertem Code führt. Der Vorteil der DTOs ist die Kapselung, da die Datenschicht vor dem Client-System versteckt wird.

Aber zurück zum Beispiel. Die find-Methode soll nicht mehr alle Benutzer liefern, sondern nur solche, deren Nachname Mustermann lautet. Hierfür wird auf der Criteria eine entsprechende Einschränkung definiert:

Criteria criteria = sessionFactory.getCurrentSession().createCriteria(User.class);
criteria.add(Restrictions.eq(„lastname“, „Mustermann“));
List<User> users = criteria.list();

Der Criteria wird hierzu eine Restriction hinzugefügt, deren erster Parameter den Namen der Property erhält, der zweite den zu prüfenden Wert. Die Restriction besitzt verschiedene Prüfungs-Methoden. Hier wurde auf Gleichheit getestet – equals – aber auch die anderen aus der SQL-Syntax bekannten Prüf-Operationen wie like, between usw. stehen zur Verfügung. Anschließend wird die Criteria wie gehabt ausgeführt und man erhält eine passende Liste von Benutzern.

Es sind aber nicht nur Suchkriterien auf dem Benutzer möglich, es können auch Einschränkungen auf der Adresse festgelegt werden. So interessieren im Folgenden nur Benutzer, die aus Köln kommen:

Criteria criteria = sessionFactory.getCurrentSession().createCriteria(User.class);
Criteria addressCiteria = criteria.createCriteria(„addresses“);
addressCiteria.add(Restrictions.eq(„city“, „Cologne“));
List<User> users = criteria.list();

Auf der bereits erstellen User–Criteria, wird eine weitere Criteria erzeugt. Der übergebene String enthält hierbei den Namen der Property aus der User-Entität, die auf die entsprechende Tabelle verweisst – in diesem Beispiel also addresses. Über die neue Criteria können nun Suchkritieren auf der Adressen definiert werden. Die list-Methode wird allerdings weiterhin auf der User–Criteria ausgeführt, da als Ergebnis-Menge eine Liste von Benutzern und keine Adressen erwartet werden.

Soweit ein kleiner Einblick in die Welt der Criterias. Bereits einen vorangegangenen Artikel – http://martinzimmermann1979.wordpress.com/2012/03/20/verwendung-einer-having-bedingung-bei-hibernate-criterias/ – widmete ich diesem Thema, wobei hier die Having-Bedingung im Vordergrund stand.

Aber zurück zum Thema, noch ist der UserDAO nicht vollständig, da die Lösch-Funktion fehlt:

@Transactional
public void delete(User user) {
sessionFactory.getCurrentSession().delete(user);
}

Diese ist denkbar einfach zu realisieren. Es muss lediglich auf der aktuellen Session die delete-Methode aufgerufen werden, die als Parameter die entsprechende Entität erwartet. Es mag merkwürdig erscheinen, dass zunächst die ganze Entität geladen werden muss, nur um sie anschließend zu löschen. Alternativ könnte eine HQL-Query zum Löschen des Benutzers verwendet werden, aber auch hier wird der Benutzer zuerst in den Hibernate internen Cache geladen, bevor er gelöscht wird. Die einzige Möglichkeit die obige Lösch-Funktion performanter zu gestalten, wäre das Laden und Löschen des Benutzers in derselben Session.

Der Artikel ist für den Einstieg in Hibernate und für das initiale Aufsetzten eines Hibernate Projektes mit Spring Integration gedacht. Es wurde der Einsatz der CRUD-Operationen und ein einfaches Mapping zwischen zwei Enitäten erläutert. Wirklich knifflig wird es erst anschließend, wenn es an das Mapping von Entitäten geht. Welche Entitäten kennen sich untereinander, wie werden sie miteinander verknüpft, welchen CascadeType und welchen FetchMode erhält welche Verbindung. Diese Fragen müssen für jedes Projekt und jede Anwendung einzeln Entschieden werden.

21 Okt 2012

JAXB und Anpassungen des JAXB Bindings

von | Veröffentlicht in: Java | 0

JAXB – Java Architecture for XML Binding – (http://jaxb.java.net/) wird eingesetzt um ein Mapping zwischen XML und Java-Klassen herzustellen und aus einer XSD-Schema-Datei Java-Klassen zu generieren. Hierfür kann das Programm xjc verwendet werden, dass seit Java 6 Bestandteil vom Java SE JDK ist.

Im nun folgenden Beispiel sollen die Daten eines Benutzers von XML in ein Java-Objekt konvertiert werden (marshalling). Auch der Umgekehrte Weg – also das Umwandeln eines Java-Objektes in XML (unmarshalling) – soll möglich sein. Ein Benutzer hat verschiedene Eigenschaften, wie z.B. Vor- und Nachname, die beim Konvertieren berücksichtigt werden sollen. Außerdem soll ein Benutzer beliebig viele Adress-Informationen besitzen können.

Zunächst wird ein Maven-Projekt erstellt. Die Beschreibung der Benutzer-Eigenschaften wird in der Schema-Datei src/main/resources/user.xsd hinterlegt. Die Definition sieht wie folgt aus:

<xs:schema xmlns:xs=“http://www.w3.org/2001/XMLSchema“
targetNamespace=“http://www.mz.de/user/schema“
xmlns=“http://www.mz.de/user/schema“
elementFormDefault=“qualified“
attributeFormDefault=“unqualified“>

<xs:element name=“user“ type=“UserType“ />

<xs:complexType name=“UserType“>
<xs:sequence>
<xs:element name=“forename“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“lastname“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“title“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“phonenumber“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“mail“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“age“ type=“xs:int“ minOccurs=“0″ />
<xs:element name=“addresses“ type=“AddressType“ minOccurs=“0″ maxOccurs=“unbounded“ />
</xs:sequence>
</xs:complexType>

<xs:complexType name=“AddressType“>
<xs:sequence>
<xs:element name=“street“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“housenumber“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“citycode“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“country“ type=“xs:string“ minOccurs=“0″ />
</xs:sequence>
</xs:complexType>
</xs:schema>

Eine XML-Datei die zu obigem Schema passen würde, sähe folgendermaßen aus:

<user xmlns=“http://www.mz.de/user/schema“>
<forename>Max</forename>
<lastname>Mustermann</lastname>
<addresses>
<street>Musterweg</street>
<citycode>50123</citycode>
</addresses>
<addresses>
<street>Musterstrasse</street>
<citycode>50123</citycode>
</addresses>
</user>

Aus der Schema-Datei lassen sich auch ohne Maven die entsprechenden Java-Klassen generieren. Hierfür führt man im Projekt-Verzeichnis xjc mit folgenden Parametern aus:

xjc -d generated-sources/xjc src/main/resources/user.xsd

Sofern in der Projekt-Struktur die Verzeichnisse generated-sources/xjc existieren, werden hier nun folgende Dateien erzeugt:

  • AddressType
  • ObjectFactory
  • package-info
  • UserType

Die Klassen UserType und AddressType ergeben sich aus der XSD-Beschreibung. Die ObjectFactory wird mit Methoden zum Erstellen der automatisch generierten Klassen versehen und bietet zudem die Möglichkeit alle Elemente, die auf nicht anonyme komplexe Typen verweisen – das name-Attribut muss gesetzt sein – zu JAXBElementen zu transformieren. In diesem Beispiel trifft das also auf das Element UserType zu.

Statt xjc nach jeder Änderung der XSD-Datei manuell auszuführen, kann alternativ Maven zum Bauen des Projektes und zur Generierung der Java-Klassen eingesetzt werden. Hierfür kommt das Maven JAXB2 Plugin (http://java.net/projects/maven-jaxb2-plugin/) zum Einsatz, wofür der build-Eintrag der pom.xml-Datei ergänzt werden muss:

<build>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<version>0.8.0</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

Wie bei Maven üblich, werden die gebauten Klassen im target-Verzeichnis abgelegt. Die von xjc generierten Klassen sind hier unter generated-sources/xjc zu finden, wobei das Verzeichnis automatisch einen ClassPathEntry erhält und die hier liegenden Klassen somit im Projekt direkt verwendet werden können. Sollte dies in der Eclipse IDE einmal nicht der Fall sein, so reicht es Maven – Update Project Configuration auszuführen.

Nun wird der oben aufgeführte XML-Inhalt in der Datei src/main/resources/user.xml gespeichert, die anschließend unmarshallt werden soll.

JAXBContext jaxbContext = JAXBContext.newInstance(UserType.class);
Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
UserType user = (UserType) unmarshaller.unmarshal(getClass().getResourceAsStream(„/user.xml“));

Das Root-Element der XML-Datei ist vom Typ UserType, daher wird zunächst eine JAXBContext-Instanz für dieses Objekt erstellt. Anschließend wird auf dieser Instanz ein Unmarshaller erstellt, der den Inhalt der XML-Datei in Form eines InputStreams unmarshallen soll. Hierbei kommt es jedoch zu einer Exception, deren Ursache im StackTrace nicht direkt ersichtlich ist:

Exception in thread „Main“ javax.xml.bind.UnmarshalException: unexpected element (uri:“http://www.mz.de/user/schema“, local:“user“). Expected elements are (none) at com.sun.xml.internal.bind.v2.runtime.unmarshaller.UnmarshallingContext.handleEvent(UnmarshallingContext.java:631)
…

Ursache für diesen Fehler ist die fehlende Annotation XmlRootElement in der Klasse UserType. Klassen die mit JAXB unmarshallt werden sollen (Root-Elemente), müssen diese Annotation besitzen. Im Fall der Klasse UserType sähe die korrekte Annotation so aus:

@XmlRootElement(name = „UserType“)

Es gibt verschiedene Möglichkeiten, um xjc dazu zu bewegen, die Klasse UserType wie gewünscht zu annotieren.
Eine Möglichkeit ist es, die XSD-Datei anzupassen:

<xs:element name=“UserType“>
<xs:complexType>
<xs:sequence>
<xs:element name=“forename“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“lastname“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“title“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“phonenumber“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“mail“ type=“xs:string“ minOccurs=“0″ />
<xs:element name=“age“ type=“xs:int“ minOccurs=“0″ />
<xs:element name=“addresses“ type=“AddressType“ minOccurs=“0″ maxOccurs=“unbounded“ />
</xs:sequence>
</xs:complexType>
</xs:element>

Hintergrund ist, dass das Element UserType nun einen anonymen complexType beinhaltet. Damit ist gewährleistet, dass der complexType nicht nur nicht in dieser XSD-Datei, sondern auch in keiner anderen referenziert werden kann. Damit ist der complexType zwangsläufig ein Root-Element und wird auch als solches von xjc erkannt und annotiert.

Bevor die obige XML-Datei unmarshallt werden kann, muss für diese Lösung noch das Root-Element von User auf UserType unbenannt werden:

<UserType xmlns=“http://www.mz.de/user/schema“>
<lastname>Mustermann</lastname>
…
</UserType>

Nun kann die XML-Datei unmarshallt werden und deren Inhalt steht im Objekt UserType zur Verfügung.

Die Lösung hat allerdings einen Nachteil. Da der complexType des UserType-Elementes annonym ist, erhält die ObjectFactory keine Methode zum Transformieren des UserTypes in ein JAXBElement. Sofern das Unmarshallen von XML-Inhalt in Java Objekte ausreicht, kann das vernachlässigt werden. Ist der umgekehrte Weg ebenfalls gewünscht – Java Objekt in XML marshallen – muss eine andere Lösung gefunden werden.

So gibt es die Möglichkeit das Standardverhalten des JAXB Bindings anzupassen, wofür die Datei src/main/resources/jxbBindings.xjb mit folgendem Inhalt erstellt wird:

<jxb:bindings version=“1.0″
xmlns:jxb=“http://java.sun.com/xml/ns/jaxb“
xmlns:xs=“http://www.w3.org/2001/XMLSchema“
xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance“
xmlns:xjc=“http://java.sun.com/xml/ns/jaxb/xjc“
xmlns:annox=“http://annox.dev.java.net“
xsi:schemaLocation=“http://java.sun.com/xml/ns/jaxb http://java.sun.com/xml/ns/jaxb/bindingschema_2_0.xsd“
jxb:extensionBindingPrefixes=“xjc“>

<jxb:bindings schemaLocation=“user.xsd“ node=“/xs:schema/xs:complexType[@name = ‚UserType‘]“>
<annox:annotate>
<annox:annotate annox:class=“javax.xml.bind.annotation.XmlRootElement“ name=“user“/>
</annox:annotate>
</jxb:bindings>

</jxb:bindings>

Die schemaLocation des jxb:binding bestimmt für welches Schema Anpassungen vorgenommen werden sollen, in diesem Fall also für die XSD-Datei user.xsd. Das Attribut node definiert mittels XPath, welche XSD-Einträge anzupassen sind. Der gewählte XPath Ausdruck matched auf alle complexType-Einträge, die sich direkt unterhalb des Schemas befinden. Da dies auch den AddressType betreffen würde, muss zusätzlich mit dem name-Attribut gearbeitet werden, welches den Wert UserType besitzt.

Über annox:annotate wird letztendlich bestimmt, was an den zuvor ausgewählten XSD-Einträgen modifiziert werden soll. Die Klasse UserType erhält die Annotation XmlRootElement mit dem name-Attribut user:

@XmlRootElement(name = „user“)

Der Anschließende Maven-Build wird allerdings fehlschlagen, da weitere Anpassungen an der build-Einstellung in der pom.xml-Datei vorzunehmen sind:

<build>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<version>0.8.0</version>
<configuration>
<strict>false</strict>
<extension>true</extension>
<args>
<arg>-Xannotate</arg>
</args>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics</artifactId>
<version>0.8.0</version>
</plugin>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics-annotate</artifactId>
<version>0.8.0</version>
</plugin>
</plugins>
</configuration>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>javax.activation</groupId>
<artifactId>activation</artifactId>
<version>1.1</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>

Zunächst muss eine Konfiguration hinzugefügt werden. Damit komplexe Typen als Root-Element behandelt werden, auf die theoretisch von anderen XSD-Dateien verwiesen werden könnte, darf nicht der strict-Mode zum Einsatz kommen. Weiterhin müssen Extensions von Fremd-Anbietern zugelassen werden, da andernfalls die annotate-Anweisung nicht verwendet werden darf. Für diese Library ist außerdem der Argument-Eintrag Xannotate nötigt. Außerdem werden die Plugins jaxb2-basics und jaxb2-basics-annotate und die Dependency activation benötigt, damit der Build-Prozess wie gewünscht durchläuft.

Als Ergebnis ist die Klasse UserType korrekt annotiert und die ObjectFactory bietet nun wieder die Möglichkeit Objekte vom Typ UserType zu JAXBElementen zu transformieren. Damit ist auch die Möglichkeit gegeben, Java-Objekte zu marshallen und so in XML-Inhalt umzuwandeln. Hierzu wird das entsprechende Java-Objekt über die ObjectFactory erstellt:

ObjectFactory factory = new ObjectFactory();
UserType userType = factory.createUserType();
userType.setForename(„Max“);
userType.setLastname(„Mustermann“);

AddressType addressType = factory.createAddressType();
addressType.setCitycode(„50123“);
addressType.setStreet(„Musterweg“);
userType.getAddresses().add(addressType);

addressType = factory.createAddressType();
addressType.setCitycode(„50123“);
addressType.setStreet(„Musterstrasse“);
userType.getAddresses().add(addressType);

Nun kann der UserType in ein JAXBElement umgewandelt werden:

JAXBElement<UserType> jaxbElement = factory.createUser(userType);

Das marshallen ähnelt dem unmarshallen aus obigem Beispiel. Es wird zunächst der JAXBContext für die Klasse UserType und im Anschluss der entsprechende Marshaller erzeugt. Dieser erhält das JAXBElement zum marshallen und einen OutputStream in den der XML-Inhalt geschrieben wird:

JAXBContext jaxbContext = JAXBContext.newInstance(UserType.class);
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.marshal(jaxbElement, outputStream);

Benötigt man den XML-Inhalt in einer Datei, so kann dem Marshaller statt dem OutputStream auch ein File übergeben werden.

Weiter Information zur Anpassung des JAXB Bindinings sind auf der Oracle Webseite zu finden:

http://docs.oracle.com/cd/E17802_01/webservices/webservices/docs/2.0/tutorial/doc/JAXBUsing4.html

1 Sep 2012

Eclipse Extension Points und Extensions

von | Veröffentlicht in: Eclipse, RCP | 1

Eclipse beinhaltet ein hoch modulares Konzept um Erweiterungen Plugin-übergreifend realisieren zu können. Das zu erweiternde Plugin bietet einen Extension-Point an, an dem andere Plugins mit ihren Extensions andocken können. Beide Arten an Plugins müssen hierbei zwangsläufig im Manifest als singleton definiert sein.

Um einen Extension-Point zu definieren, wird die plugin.xml Datei des zu erweiternden Bundles geöffnet und zum Reiter Extension Points gewechselt. Sofern keine plugin.xml Datei existiert, kann alternativ im Manifest (MANIFEST.MF) der genannte Reiter aktiviert werden, Eclipse erstellt nun automatisch die plugin.xml Datei. Nun kann ein Extension-Point erzeugt werden, als ID und Namen erhält er im folgenden Beispiel den Wert de.mz.myExtensionPoint und myExtensionPoint.


Nach erfolgreicher Erstellung des Extension-Points wird automatisch das dazugehörige Schema geöffnet. Auch wenn es nicht zwingend notwendig ist, sollten alle Attribute im Schema – Reiter Definition – definiert werden. Nur so können die Felder beim Anlegen einer Erweiterung bequem im Plug-In Manifest Editor über die UI angegeben werden können. Will man später Veränderungen am Schema vornehmen, so ist dieses in der Dateistruktur des Projektes unter schema/myExtensionPoint.exsd zu finden.

Hier wird nun ein neues Element mit dem Namen client erzeugt, dem zwei Attribute zugewiesen werden. Das Erste Attribut hat den Namen class und ist vom Typ Java. Hier hat man nun die Möglichkeit ein Interface zu hinterlegen, welches von der im Attribut class verwiesenen Klasse zu implementieren ist. Im folgenden Beispiel ist das zu implementierende Interface IMyExtension.

Das Interface selber enthält für Beispielzwecke die Methode doSomething:

public interface IMyExtension {
public void doSomething(String text);
}

Das zweite Attribut erhält den Namen text und ist vom Typ String. Hier sind keine weiteren Einstellungen nötig.

Per Context-Menü wird der extension zunächst ein Choice-Element zugewiesen, welches wiederum den Eintrag client erhält. Damit die Extension beliebig viele Client-Einträge erhalten kann, wird die Max Occurrences des Client-Elements auf Unbounded gesetzt. Eine Extension kann also mehrere Erweiterungen enthalten.

Die Plugin.xml hat nun folgenden Eintrag erhalten:

<extension-point id=“de.mz.myExtensionPoint“ name=“myExtensionPoint“ schema=“schema/myExtensionPoint.exsd“/>

Damit andere Bundles nun tatsächlich den Extension-Point erweitern können, müssen sie das Interface IMyExtension implementieren können. Daher muss im Manifest das Package des Interfaces exportiert werden:

Export-Package: de.mz

Damit ist die Definition des Extension-Points abgeschlossen und wir können uns der Erstellung einer Extensions zuwenden. Öffnen wir hierzu die plugin.xml Datei des Bundles, welches den Extension-Point erweitern soll. Auf dem Reiter Extensions kann zwischen den möglichen Erweiterungen gewählt werden, auch der zuvor erstelle Extension-Point de.mz.myExtensionPoint wird hier aufgeführt. Per Context-Menü können hier die Client-Erweiterungen hinzugefügt werden. Für die im Schema deklarierten Attribute stehen im Plug-In Manifest Editor Eingabehilfen zur Verfügung, so kann bequem für das class Attribut eine Implementierung und für das text Attribut ein String angegeben werden.

Diese Einstellung führt zum folgenden Eintrag in der plugin.xml Datei:

<extension point=“de.mz.myExtensionPoint“>
<client
class=“de.mz.MyExtensionImpl“
text=“Hallo Welt“>
</client>
</extension>

Extension-Point und eine dazu passende Extension wurden bereits erstellt, nur Verwendung findet die Erweiterungen bislang noch nicht. Doch hierzu bietet Eclipse die ExtensionRegistry an, auf die man über die Runtime-Platform Zugriff erhält:

IConfigurationElement[] extensions = Platform.getExtensionRegistry().getConfigurationElementsFor(„de.mz.extension.example.myExtensionPoint“);
for (IConfigurationElement extension : extensions) {
try {
String text = extension.getAttribute(„text“);
IMyExtension myExtension = (IMyExtension) extension.createExecutableExtension(„class“);
myExtension.doSomething(text);
// do with myExtension what you have to do
} catch (CoreException e) {
// do some logging
}
}

In obigem Beispiel erhält man alle Erweiterungen die zum Extension-Point de.mz.extension.example.myExtensionPoint gehören. Nun können die Attribute der einzelnen Erweiterungen erfragt werden – hierbei ist es nicht relevant, ob diese im Schema definiert sind – und für das Klassen-Attribut ein entsprechendes Objekt erstellen werden (createExecutableExtension). Bei einem optionalen Klassen-Feld macht es Sinn, sich zunächst zu vergewissern, dass das Attribut einen Wert zugewiesen bekommen hat. Andernfalls wird nämlich eine CoreException geworfen, die über diese Abfrage verhindert werden kann.

Auch wenn das Beispiel auf die Eclipse 3.x Plattform ausgelegt ist, funktioniert der Mechanismus grundsätzlich auch bei Eclipse 4. Hier spart man sich den Umweg über die Runtime-Platform, da sich die ExtensionRegistry bequem per Dependency Injection injizieren lässt.

Will man das Beispiel testen, kann das Laden der Extensions in einem Activator vorgenommen werden, der hierfür lediglich im Manifest eingetragen werden muss:

Bundle-Activator: de.mz.Activator

Nun kann das Extension-Point Bundle als OSGI Framework ausgeführt werden. Treten hierbei Fehler auf, sollten in der Run-Configuration zunächst alle Bundles deselektiert und anschließend nur die Plugins ausgewählt werden, die den Extension-Point und die Extensions beinhalten. Natürlich werden auch Eclipse spezifische Bundles benötigt, die sich über einen Klick auf Add Required Bundles hinzufügen lassen.

15 Aug 2012

Spring AOP

von | Veröffentlicht in: spring | 0

Der folgende Artikel beschäftigt sich mit Spring 3.x AOP, wobei Spring lediglich den Support für das eigentliche AOP-Framework AspectJ zur Verfügung stellt. Die Aspekt orientierte Programmierung – kurz AOP – ermöglicht es, die eigentliche Business-Logik einer Anwendung von querschnittlichen Aspekten zu trennen. Als typische Aspekte seien hier Logging- oder Security-Layer genannt. Statt nun die Aspekte mit der Business-Logik zu verweben, findet eine klare Kapselung statt, die es ermöglicht, die Aspekte autonom umzusetzen und anschließend explizit über die Business-Logik zu legen. So können öffentliche Methoden, ganze Projekte, einzelne Packages oder nur bestimmte Methoden eines Services mit Aspekten versehen werden.

Der Artikel erläutert wann und wie ein Aspekt in den Programmfluss eingreifen kann und wie die Aspekte mit der Business-Logik verwoben werden. Ersteres wird über Advices, Zweiteres per Pointcuts realisiert.

Bevor es an die Implementierung geht, müssen zunächst die entsprechenden Libraries eingebunden werden. Für den Spring AOP Support werden die Libraries core und context benötigt, die aktuell in der Version 3.1.0 verfügbar sind:

<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>3.1.0.RELEASE</version>
</dependency>

<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>3.1.0.RELEASE</version>
</dependency>

Wie bereits erwähnt handelt es sich bei Spring lediglich um den Wrapper um die AOP-Schicht. Für das eigentliche AOP Framework AspectJ werden folgende Libraries verwendet:

<dependency>
<groupId>org.aspectj</groupId>
<artifactId>com.springsource.org.aspectj.runtime</artifactId>
<version>1.7.0</version>
</dependency>

<dependency>
<groupId>org.aspectj</groupId>
<artifactId>com.springsource.org.aspectj.weaver</artifactId>
<version>1.7.0</version>
</dependency>

Um den AspectJ-Support für Spring zu aktivieren, muss folgende Zeile in der Spring-Konfiguration aufgenommen werden:

<aop:aspectj-autoproxy/>

Anschließend wird die Klasse MyService erstellt, welche die eigentliche Business-Logik beinhalten soll.

public class MyService {

public void doSomeStuff() {
// do some business logic
}
}

Dieser Service soll nun mit einem Aspekt versehen werden, der z.B. das Logging von der Business-Logik kapselt.

@Aspect
public class MyAspect {

@Before(„execution (* de.mz.MyService.doSomeStuff(..))“)
public void aspect() {
// do some logging
}
}

Nun muss sowohl der Service als auch der Aspekt als Spring-Bean definiert werden:

<bean id=“myAspect“ class=“de.mz.MyAspect“ />
<bean id=“myService“ class=“de.mz.MyService“ />

Wird nun die Methode doSomeStuff des MyService aufgerufen, wird nicht nur die eigentliche Methode, sondern auch der Aspekt ausgeführt. Die Reihenfolge wird hierbei über den Advice definiert. In obigen Beispiel wird dieser über die Before-Annotation festgelegt, so dass zuerst der Aspekt und erst anschließend die Methode des MyService ausgeführt wird.

Die folgenden Advices bieten die Möglichkeit Eingriffe im Programmfluss vorzunehmen:

  • Before – Der Aspekt wird vor der eigentlichen Methode ausgeführt.
  • Around – Die Methodenausführung findet im Aspekt selber statt. Es kann also vor und nach der Methodenausführung eingegriffen werden.
  • After – Der Aspekt wird erst nach der Methodenausführung aktiv.
  • AfterReturning – Dieser Aspekt wird ebenfalls erst nach der Methodenausführung aktiv, es kann allerdings zusätzlich auf den Rückgabewert zugegriffen werden.
  • AfterThrowing – Der Aspekt wird nur aktiv, sofern in der eigentlichen Methode ein Fehler auftritt.

Um Methoden mit Aspekten zu versehen, werden die bereits erwähnten Pointcuts verwendet. In obigem Beispiel wurde der Pointcut einfach in der Before-Annotation mit angegeben. Wesentlich eleganter ist es, Pointcuts separat zu definieren und im Advice lediglich auf sie zu verweisen. So können die Pointcuts mehrfach verwendet werden und sind beliebig kombinierbar:

@Pointcut(„execution (* de.mz.MyService.doSomeStuff(..))“)
private void pointcutForDoSomeStuff() {}

@Before(„pointcutForDoSomeStuff()“)
public void aspect() {
// do what the aspect has to do
}

Nun wird in der Pointcut-Annotation auf die doSomeStuff-Methode vom MyService verwiesen, wobei der Pointcut selber lediglich aus einer leeren Methoden besteht, deren Rückgabetyp void seien muss. Auch wenn es nicht zwingen notwendig ist, wird als Sichtbarkeit private festgelegt, damit der Pointcut nicht aufgerufen werden kann. Auf die Pointcut-Methode wird nun in der Before-Annotation verwiesen.

Es gibt verschiedene Möglichkeiten mit denen Pointcut-Ausdrücke auf entsprechende Java-Resourcen gematched werden können. Um auf Methoden zu matchen, wird der bereits verwendete Pointcut-Designator (PCD) execution verwendet. Es ist nicht zwingend notwendig, dass hier nur explizit auf eine Methode verwiesen wird, so kann z.B. auch auf alle öffentlichen Methoden des MyService verwiesen werden:

@Before(„execution(public * de.mz.MyService.*(..)))“)

Alternativ können auch alle öffentlichen Methoden – bzw. alle Methoden mit einer fest definierten Sichtbarkeit – mit einem Aspekt versehen werden:

@Before(„execution(public * *(..))“)

Will man Aspekte nicht für Methoden sondern auf einer bestimmten Package-Ebene definieren, wird statt dem execution Designator within verwendet:

@Pointcut(„within(de.mz.*)“)

Sollen zusätzlich die Sub-Packages mit Aspekten versehen werden, muss das Statement minimal angepasst werden:

@Pointcut(„within(de..*)“)

Weiterhin kann man alle Klassen, die ein bestimmtes Interface implementieren mit einem Aspekten versehen, indem man den Designator this verwendet. Würde der MyService nun das Interface IMyService implementieren, würde auch folgender Pointcut matchen:

@Pointcut(„this(de.mz.IMyService)“)

Es gibt noch viele weitere Möglichkeiten, so dass sich hier ein Blick in die Dokumentation allemal lohnt:

http://static.springsource.org/spring/docs/current/spring-framework-reference/html/aop.html

Wie bereits erwähnt, können Pointcuts auch kombiniert werden. Hierbei sind AND &&, OR || und NOT ! Verknüpfungen möglich.

Sollen die Methode doSomeStuff und doSomeOtherStuff denselben Aspekt erhalten wird zunächst ein weiterer Pointcut für die zweite Methode definiert:

@Pointcut(„execution (* de.mz.MyService.doSomeOtherStuff())“)
private void pointcutForSomeOtherStuff() {}

Anschließend können beide Pointcuts mit ODER Verknüpft werden, so dass der Aspekt ausgeführt wird, sobald eine der Methoden aufgerufen wird:

@Pointcut(„pointcutForDoSomeStuff() || pointcutForSomeOtherStuff()“)
private void allPointcuts() {}

Weiterhin kann es nützlich sein im Aspekt auf die Übergabeparameter der aufgerufenen Methode zugreifen zu können. Hierzu wird die Methode doSomeStuff um zwei Übergabeparameter vom Typ String erweitert:

public void doSomeStuff(String para1, String para2) {
// do some business logic
}

Der bestehende Pointcut wird mittels UND mit dem Designator args verknüpft, welcher Zugriff auf die Parameter gewährt. Diese stehen dem Aspekt dann als eigene Übergabeparameter zur Verfügung:

@Before(„pointcutForDoSomeStuff() && args(para1,para2)“)
public void printParams(String para1, String para2) {
// nice aspect with access to parameters
}

Interessiert einen nur der erste Parameter, sieht das Statement so aus:

@Before(„pointcutForDoSomeStuff() && args(para1,..)“)

Für Zugriff auf den zweiten Parameter muss folgende Modifizierung vorgenommen werden:

@Before(„pointcutForDoSomeStuff() && args(..,para2)“)

Da aus Programmierer Sicht kein Unterschied zwischen Before- und After-Advice existiert, beschäftigt sich das folgende Beispiel mit dem Around-Advice. Hier ergeben sich interessante Möglichkeiten, da der Aspekt Zugriff auf den JoinPoint erhält und für dessen Ausführung zuständig ist. Bei dem JoinPoint handelt es sich um die mit einem Aspekt versehene Methode. Dadurch das die Ausführung dem Aspekt obliegt, kann im Fehlerfall eingegriffen und z.B. ein Retry-Mechanismus implementiert werden. Die Exception kann gecatched und der Methoden-Aufruf beliebig oft wiederholt werden:

@Around(„pointcutForDoSomeStuff“)
public Object retryexecution(ProceedingJoinPoint joinPoint) throws Throwable {
Exception exception = null;
int i = 0;
while (i < MAX_RETRY) {
try {
return joinPoint.proceed();
} catch (MyException e) {
exception = e;
}
i++;
}
throw exception;
}

Grade beim Aufruf von externen Services in verteilten Systemen kann so ein Retry-Mechanismus Sinn machen. Geht der erste Aufruf noch auf einen defekten Service, so kann der zweite erfolgreich die gewünschte Arbeit verrichten. Der Benutzer bekommt hierbei nicht einmal mit, dass ein Fehlverhalten aufgetreten ist.

Wer bereits mit Spring 2.x AOP gearbeitet hat, dem wird das Handling der obigen Beispiele vertraut vorkommen. Tatsächlich hat sich die Spring-API im AOP-Bereich seit der letzten Spring Version nicht geändert. Aufgrund der komfortablen API ist dies aber auch nicht Notwendig.

31 Jul 2012

Datei Upload mit Spring 3

von | Veröffentlicht in: Java, spring | 0

Mein letzter Artikel beschäftigte sich mit der Erstellung eines Spring Web MVC Projektes ( http://martinzimmermann1979.wordpress.com/2012/05/23/in-10-minuten-ein-spring-web-mvc-projekt-erstellen/ ). Hier stand ein Controller zur Behandlung von GET- und POST-Requests zur Verfügung. Ersterer lieferte eine Benutzerliste, die in einer entsprechenden View angezeigt wurde. Zweiterer war für das Hinzufügen von weiteren Benutzern zuständig. Die bereits bestehenden Funktionalitäten sollen nun um einen Datei-Upload erweitert werden.

Zusätzlich zu den bereits verwendeten Spring-Libraries, wird folgende Maven dependency benötigt:

<dependency>
<groupId>commons-fileupload</groupId>
<artifactId>commons-fileupload</artifactId>
<version>1.2.2</version>
</dependency>

In einem neu zu erstellenden FileController wird die Methode handleUpload benötigt. Da die Datei per POST-Request hochgeladen wird, erhält das Attibute method des RequestMappings den entsprechenden Wert. In der Methoden-Signatur wird diesmal kein
ModelAttribute verwendet, da kein Mapping zwischen Model und Formular-Daten stattfinden muss. Die Binär-Daten sind direkt im Request enthalten und per RequestParam zugreifbar.
Die Datei wird vom Client als Multipart-Request zum Server gesendet, welche in Spring von der Klasse MultipartFile repräsentiert wird. Über die getInputStream-Methode erhält man Zugriff auf den InputStream, der nun verarbeitet werden kann.

@RequestMapping(value = „/file“, method = RequestMethod.POST)
public String handleUpload(@RequestParam(„file“) MultipartFile file) {
if (file.isEmpty()) {
return „redirect:/uploadFailure“;
}
try {
InputStream inputStream = file.getInputStream();
// do with the InputStream, what you want to do
} catch (IOException e) {
return „redirect:/uploadFailure“;
}
return „redirect:/uploadSuccess“;
}

Die obigen Redirects auf die Ressourcen uploadSuccess und uploadFailure führen natürlich noch ins Leere. Wie diese Umzusetzen sind, kann meinem letzten Artikel entnommen werden.

Um per HTLM-Formular eine Datei hochzuladen muss das form-Attribut enctype auf multipart/form-data gesetzt werden. Außerdem wird über die action auf die handleUpload-Ressource verwiesen. Da der RequestParam MultipartFile im RequestParam mit file benannt wurde, muss auch das input-Tag diesen Namen erhalten. Das Attribut type wird ebenfalls auf file gesetzt, damit sich im Browser der Dateiauswahl-Dialog öffnet.

<form action=“file“ method=“post“ enctype=“multipart/form-data“>
<p>Datei:<br>
<input name=“file“ type=“file“>
<input type=“submit“ value=“Absenden“>
</p>
</form>

Die Spring Konfiguration, die für das Hochladen von Dateien notwendig ist, ist recht übersichtlich. Es muss lediglich ein CommonsMultipartResolver definiert werden, damit Spring mit dem MultipartFile umgehen kann:

<bean id=“multipartResolver“
class=“org.springframework.web.multipart.commons.CommonsMultipartResolver“ />

Anschließend können Dateien über das oben definierte Formular auf den Server hochgeladen und dort verarbeitet werden.