Maven Projekt Tutorial

Auf dieser Seite wird kurz beschrieben werden, wie in Maven eine Projektstruktur mit Dokumentation in Maven Site aufgebaut, angepasst, für Eclipse vorbereitet und gebuildet wird.

Generell werden dazu in etwa die folgenden Schritte durchlaufen:

Maven Installation
Maven Archetyp erzeugen
Projektdatei anpassen
Maven Site erzeugen
Sitestruktur anpassen
Dokumentation erzeugen
Projekt für Eclipse vorbereiten
Build Lifecycle

Maven Installation

Unter diesem Link lässt sich Maven downloaden (unten auf der Seite steht eine ähnliche Installationsweise wie hier beschrieben).
Da Maven auf Java basiert, muss logischerweise auch Java auf dem Rechner installiert sein/werden und die Umgebungsvariable JAVA_HOME korrekt gesetzt.
Das downgeloadete Archiv wird in ein wahlfreies Directory entpackt. Sinnvoll ist es natürlich die Distribution dort abzulegen wo alle anderen Programme sind. Es ist auch sinnvoll Maven so abzulegen, dass keine Leerzeichen im Pfad sind, da dies immer wieder mal zu Problemen führen kann.
- Windows: z.B. "C:\Programme\maven_version"
- Linux: z.B. "/usr/local/maven_version"
Um von überall aus der Dateistruktur aufgerufen werden zu können, muss der Umgebungsvariable Path der Pfad der Binärdateien von Maven hinzugefügt werden.
- Windows: Windowstaste + Pause - Erweitert - Umgebungsvariablen (unten) - Systemvariablen - "C:\Programme\maven_version\bin" hinzufügen
- Linux: in der Konsole "export PATH=/usr/local/maven_version/bin:$PATH"
Mit mvn --version wird geprüft ob die Distrubution erfolgreich installiert wurde.

Anmerkung: Ich würde für Windowsbenutzer auch noch empfehlen, das Repository das unter "C:\Dokumente und Einstellungen\User\.m2\repository" angelegt wird in ein Verzeichnis ohne Leerzeichen zu verschieben und dann diese Position in "installdir\conf\settings.xml" beim Tag <localrepository> einzustellen.

Weitere Konfiguration von Maven.

top

Maven Archetyp erzeugen

Konsole öffnen und in das Verzeichnis wechseln, in dem das Projektverzeichnis erzeugt werden soll.
mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes -DgroupId=com.mycompany.app -DartifactId=my-app ausführen.

Dieser Befehl erzeugt ein neues Verzeichnis mit dem Namen my-app das die folgenden Inhalte hat.

  my-app
  |- src
  |  |- main
  |  |  `- java
  |  |     `- com
  |  |        `- mycompany
  |  |           `- app
  |  |              `- App.java
  |  `- test
  |     `- java
  |        `- com
  |           `- mycompany
  |              `- app
  |                 `- AppTest.java
  `- pom.xml

Die unteren Strukturen, also com\mycompany\app repräsentieren dabei schon die Verzeichnisstruktur der Java Packages. Das heißt die Klasse App gehört zum Package com.mycompany.app

Anmerkung: Werden im Projekt zusätzliche Dateien, wie externe Bilder für Buttons, Konfigurationsfiles oder MessageBundles für l18n, benötigt, muss im Verzeichnis main und test jeweils ein Verzeichnis resources erstellt werden. Die darin enthaltenen Dateien können direkt im Projekt verwendet werden und werden beim builden automatisch eingebunden.

top

POM anpassen

Die Datei pom.xml (POM) ist die Einstellungsdatei des Projektes. In ihrer Rohform stehen nur recht wenige notwendige Einträge.

  <projekt>
    <modelVersion>4.0.0</modelVersion> 
    <groupId>net.fatlenny</groupId> 
    <artifactId>projekt</artifactId> 
    <packaging>jar</packaging> 
    <version>1.0-SNAPSHOT</version> 
    <name>projekt</name> 
    <url>http://maven.apache.org</url> 
    <dependencies>
      <dependency>
        <groupId>junit</groupId> 
        <artifactId>junit</artifactId> 
        <version>3.8.1</version> 
        <scope>test</scope> 
      </dependency>
    </dependencies>
  </project>

Eine vollständige pom.xml die für ein Projekt findet sich hier.

Wichtig für das Projekt sind erst mal der Name, mit dem das Projekt identifiziert werden kann, und die Art wie das Projekt gepackt wird. Die Grundeinstellung ist jar, wobei das Projekt aber auch als war oder pom (in diesem Fall werden Kindprojekte erwartet).
Im <dependecies> Bereich werden die Abhängigkeiten des Projekts von externen Libraries angegeben. Auf dieser Seite kann nach externen Libraries und deren korrekte Eintragung für die POM gesucht werden
Im Bereich <reporting> (nicht in der MinimalPOM enthalten - siehe nächster Punkt) werden die Plugins angegeben, die für die automatische Dokumentation, die später im Abschnitt über Maven Site behandelt wird, wichtig ist.
Wichtige und nützliche Plugins für Maven finden sich hier.
Ich empfehle die pom.xml des Basisbeispiels anzusehen, bzw. in das eigene Projekt zu übernehmen und anzupassen.

Weitere Abschnitte der POM und deren Erklärungen finden sich hier

top

Maven Site erzeugen

Konsole öffnen und in das Verzeichnis wechseln in dem sich das Projektverzeichnis befindet.
mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-site -DgroupId=com.mycompany.app -DartifactId=my-app ausführen (Verwenden der gleichen Werte für groupId und artifactId wie im oberen Befehl).

Dieser Befehl verändert die Verzeichnisstruktur im bereits vorhandenen Projekt sodass diese dann wie folgt aussieht.

  my-app
  |- src
  |  |- main
  |  |  `- java
  |  |     `- com
  |  |        `- mycompany
  |  |           `- app
  |  |              `- App.java
  |  |- site
  |  |  |- apt
  |  |  |  |- format.apt
  |  |  |  `- index.apt
  |  |  |- fml
  |  |  |  `- faq.fml
  |  |  |- fr
  |  |  |  `- ...
  |  |  |- xdoc
  |  |  |  `- xdoc.xml
  |  |  |- site.xml
  |  |  `- site_fr.xml
  |  `- test
  |     `- java
  |        `- com
  |           `- mycompany
  |              `- app
  |                 `- AppTest.java
  `- pom.xml

Den Ordner fr und die Datei site_fr.xml kann gelöscht werden, wenn nicht in mehreren Sprachen dokumentiert werden soll.

Die Dateien mit den Endungen apt, fml und xdoc sind Dateien mit Dokumentationsinhalten, wobei zum Schreiben unterschiedliche Formate verwendet werden. Die Erklärung der Formate wird direkt in den erzeugten Dateien behandelt.

Anmerkung: Werden im Projekt zusätzliche Dateien für die Dokumentation, wie externe Bilder für Domainmodelle, Stundenlisten oder Besprechungsprotokolle, benötigt, muss im Verzeichnis site ein Verzeichnis resources erstellt werden. Die darin enthaltenen Dateien können direkt in der Dokumentation verwendet werden und werden beim builden automatisch eingebunden.

top

Sitestruktur anpassen

Die Menüstruktur der Dokumentation kann durch Anpassen der Datei site.xml aufgebaut werden.

Als Vergleich wird auch hier empfohlen die jeweiligen Bereiche der site.xml des Basisbeispiels anzusehen bzw. anzupassen. Eine allgemeine Hierarchie sieht folgendermaßen aus.

  <menu name="Hierarchie 1">
    <item name="Hierarchie 2" href="test.html"/>
    <item name="Hierarchie 2" href="team-list.html">
	  <item name="Hierarchie 3" href="test.html"/>
	</item>
  </menu>

Insbesondere automatisch generierte Reports, wie Codequalität, Javadoc oder Testauswertungen, in der Menüstruktur werden durch den Eintrag von <menu ref="reports" /> angegeben.
Verweise zu Subprojekten oder zum Superprojekt, werden durch <menu ref="modules" /> oder <menu ref="parent" /> angegeben.

top

Dokumentation builden

Konsole öffnen und wechseln in den Projektordner.
mvn site ausführen.
Im Verzeichnis target\site werden die html Dateien erzeugt, die die Dokumentation enthalten. Durch öffnen von index.html wird die Startseite der Dokumentation aufgerufen.

Anmerkung: Wenn ein Projekt ein oder mehrere Unterprojekte enthält, sollte die Dokumentation mit dem Befehl mvn site:stage -DstagingDirectory=ein_Verzeichnis gebuiltet werden, da erst dann auch Links zu den Subprojekten und insbesondere die Reports richtig dargestellt werden.

top

Projekt für Eclipse vorbereiten

Öffnen der Konsole und wechseln in den Projektordner.
mvn eclipse:eclipse ausführen.
Dieser Befehl erzeugt alle zusätzlichen Verzeichnisse und Dateien, die von Eclipse benötigt werden.

Die Verzeichnisstruktur sieht dann so aus (oberste Ebene).

  my-app
  |- .settings
  |- src
  |- target
  |- .classpath
  |- .projekt
  `- pom.xml

Das Projekt kann jetzt direkt über den Dialog New Project in Eclipse importiert werden und ist fertig zum Bearbeiten.

Anmerkung: Manchmal treten durch den Arbeitsprozess und die Veränderungen durch das updaten/comitten aus dem CVS/SVN Inkonsistenen auf, die beim run Fehler erzeugen. In diesem Fall ist es sinnvoll mit mvn eclipse:clean "von außen" die Projektdateien zu säubern und erneut mvn eclipse:eclipse auszuführen. Das Projekt muss dabei nicht erneut importiert werden, sondern nur Eclipse während diesem Vorgang geschlossen sein.

Build Lifecycle

Meiner Meinung nach empfiehlt es sich NICHT Maven in Eclipse zu integrieren. Vielmehr sollte es unabhängig von Eclipse für den Build Lifecycle verwendet werden. Die Gründe dafür liegen vorallem in der einheitlichen Einhaltung des Build Lifecycles, der oft durch verschiedene IDEs bzw. unterschiedliche Versionen und Ausprägungen nicht erreicht wird.
Bei der Verwendung von Code Repositories wie CVS oder SVN ist es am sinnvollsten nur eine komplett gereinigte Projektstruktur zu comitten. Für diesen Fall sind das nur die Struktur des src Ordners und die pom.xml. Dadurch lassen sich Verunreinigungen der Projekte großteils vermeiden.
Die Phasen von Maven und deren Beschreibungen werden im Folgenden aufgelistet.
- mvn clean - Reinigen des Projektes von allen compilierten Strukturen, durch Löschen der taget Ordner. (Empfiehlt ist vor dem committen bzw. groben Veränderungen in der Projektstruktur oder des Codes.)
- mvn compile - Compilen aller Sources des Projekts in die jeweiligen target Ordner. (Empfiehlt sich beim externen Ausführen des Projekts.)
- mvn test - Durchlaufen aller Tests des Projektes.
- mvn package - Packen des Projektes in das gewünschte Archiv.
- mvn install - Installieren eines gültigen Projektes in ein Repository.
- mvn deploy - Deployen des Projektes auf eine production plattform.
- mvn site - Erzeugen der Dokumentation des Projektes.

Autor: Kristof Meixner
Bei Frage, Anmerkungen, Verbesserungsvorschlägen und Fehlerkorrekturen zum Tutorial, wenden Sie sich bitte an die folgende E-Mailadresse.