Maven Grundlagen und Rezepte

1. Überblick

Maven ist ein sehr leistungsfähiges Build-Tool (mit vielen weiteren Funktionalitäten), das weltweit im professionellen Bereich sehr hohe Verbreitung hat (Schwerpunkt Java, aber auch in anderen Systemen).

Die Konfiguration erfolgt größtenteils in einer XML-Datei mit dem fixen Namen pom.xml ("Project Object Model").

Projekt-Verschachtelung ist möglich, hier aber nicht Thema.

Die Verwendung kann entweder auf der Kommandozeile erfolgen oder es werden die in der IDE integrierten Möglichkeiten genutzt.

Vermutlich fast alle verbreiteten IDEs oder leistungsfähigen Programm-Editoren unterstützen Maven.

Komplexe Projekte müssen beim "Build" compilieren, Code-Tests auf verschiedenen Ebenen durchführen, viele Zusatzbibliotheken einbinden und bei erstmaliger Nutzung aus dem Internet laden, sogar automatisch Code generieren, die Dokumentation neu erstellen bzw. Status-Seiten aktualisieren u.v.a.m..

Die Kommandozeilen-Nutzbarkeit ist äußerst wichtig für automatisierten "Build".

2. Eindeutige Identifizierbarkeit von Funktionalitäten/Bibliotheken

Zum Einbinden von "fremden" Funktionalitäten/Bibliotheken ist die weltweit eindeutige Identifizierbarkeit Grundvoraussetzung.

Maven verwendet dazu die Kombination von Group, Artifact und Version. Dies ermöglicht z.B. die einfache Nutzung von öffentlich zugänglichen und auch privaten Maven-Servern (z.B. Maven Central Repository.

Das Default-Repository ist Maven Central Repository (wird automatisch verwendet, wenn kein anderes angegeben wird).

groupId ist dabei eine weltweit eindeutige Bezeichnung des Projekts - sollte wie bei Java-Packages mit dem umgekehrten Domain-Namen der Organisation beginnen, danach bei Bedarf eine intern eindeutige Ergänzung (z.B. at.meine-domain.rx2324-2chif). Details siehe Maven – Guide to Naming Conventions.
Wie in DNS-Domainnamen – aber im Gegensatz zu Java-Packages – sind '-' erlaubt. In Java-Packages kann man stattdessen '_' verwenden. Generell sollte die groupId exakt mit dem umgekehrten Domainnamen (in Kleinbuchstaben) beginnen.

artifactId ist der Name des Projekts und des entstehenden JAR-Files (ohne dessen Versionsbezeichnung) (z.B. demo-01)

version ist die Versionsnummer (z.B. 1.0-SNAPSHOT), die auch hinten (mit '-') an das entstehende JAR-File angehängt wird (z.B. demo-01-1.0-SNAPSHOT.jar).
Eine Versionsnummer mit Ende -SNAPSHOT ist eine "Entwicklungs-Version" (z.B. 1.0-SNAPSHOT), die nicht für die Produktion gedacht ist.
Normalerweise sollte die Versionsnummer mit einer Zahl beginnen (z.B. 1.0), aber auch andere Zeichen sind erlaubt (z.B. 1.0-alpha). Bis zu 3 Zahlen werden von Maven dirkt unterstützt: Major (inkompatible Änderungen möglich), Minor (Ergänzungen, kompatible Änderungen), Patch (Fehlerkorrekturen) – z.B. 1.0.0.

3. Maven Lifecycle mit Phasen und Goals

Ein zentrales Konzept von Maven ist der Lifecycle. Bereitgestellt als Standard gibt es 3 davon:

  • default zuständig für Erzeugen und "Ausliefern" (deployment) von Software (Programme, Bibliotheken, etc)

  • clean entfernen aller Ergebnisse von Builds

  • site Erzeugen und "Ausliefern" der Projekt-Website (oder Teile davon)

Weitere Lifecycles können von Plugins bereitgestellt werden.

Maven gliedert den jeweiligen Lifecycle in sogenannte "Phasen". Diese haben eine festgelegte Reihenfolge. Durch Angabe einer Phase werden alle Phasen bis (inclusive) zur angegebenen abgearbeitet.

Details siehe Maven – Introduction to the Build Lifecycle

Diese Phasen sind beim "default"-Lifecycle (in dieser Reihenfolge):

  • validate - validate the project is correct and all necessary information is available

  • compile - compile the source code of the project

  • test - test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed

  • package - take the compiled code and package it in its distributable format, such as a JAR.

  • verify - run any checks on results of integration tests to ensure quality criteria are met

  • install - install the package into the local repository, for use as a dependency in other projects locally

  • deploy - done in the build environment, copies the final package to the remote repository for sharing with other developers and projects.

Für den "clean"-Lifecycle sind die Phasen: pre-clean, clean, post-clean (Details sind für uns derzeit weniger wichtig)

Einer Phase kann ein sogenanntes goal (oder mehrere) zugeordnet werden Jedes Maven-Plugin (Teil-Funktionalität) bietet ein oder mehrere Goals an und einige davon sind automatisch einer Phase zugeordnet (überschreibbar).

4. Maven Plugins

Die gesamte konkrete Arbeit wird in Maven von Plugins erledigt. Diese können von der Maven-Community oder von der eigenen Organisation bereitgestellt werden. Auch sie sind weltweit eindeutig identifizierbar und können von Maven-Servern geladen werden.

Beispiele:

Eine Liste vieler offizieller Plugins findet sich hier: Apache Maven - Available Plugins

5. Properties

Properities ermöglichen die zentrale Festlegung wichtiger Werte unter einem Namen – vor allem wichtig bei mehrfacher Verwendung z.B. von Versionsnummern oder auch nur der Übersichtlichkeit halber.
Maven – Introduction to the POM + Maven – POM Reference

6. Weitere Konzepte (hier nicht weiter besprochen)

Module

Projekte können in Module unterteilt werden, die wiederum eigene pom.xml-Dateien haben können und optional hierarchisch verschachtelt sind. Dabei kann ein Vererbungskonzept verwendet werden. (ACHTUNG: nicht zu verwechseln mit Java-Modulen oder IntelliJ-Modulen!)

Profiles

Profile ermöglichen unterschiedliche Konfigurationen für unterschiedliche Zwecke, z.B. kann ein Profil für die Entwicklung und ein anderes für die Produktion verwendet werden.

etc.

7. Die Konfigurationsdatei 'pom.xml'

Die Bezeichnung ist die Abkürzung für "Project Object Model".

Diese XML-Datei liegt im Maven-Projekt-Basisverzeichnis (bei uns üblicherweise das IntelliJ-Modul-Vezeichnis!!).

Sie besteht aus mehreren Abschnitten, deren Reihenfolge nicht beliebig ist.

TODO: in Arbeit …​

7.1. Beispiel-Konfigurationsdatei 'pom.xml'

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>at.htlw5.rx2223_2chif</groupId>
  <artifactId>demo-01</artifactId>
  <version>1.0-SNAPSHOT</version>

<!-- ab hier Ergänzungen -->
<!-- XML-Kommentar (wie in HTML) -->
  <properties> <!-- Java-21 verwenden (SourceCode und generiertes Binär-Format) -->
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies> <!-- Abhängigkeiten zu anderen Projekten -->
    <dependency>
      <groupId>org.openjfx</groupId>
      <artifactId>javafx-controls</artifactId>
      <version>17</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <version>3.2.1</version>
        <executions>
          <execution>
            <id>rx-generate-sources-jar</id>
            <phase>package</phase>  <!-- produzieren des JAR-Archivs -->
            <goals>
              <goal>jar-no-fork</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.4.1</version>
        <executions>
          <execution>
            <id>rx-generate-javadoc</id>
            <phase>package</phase>  <!-- produzieren des JAR-Archivs -->
            <goals>
              <goal>jar</goal>
              <!-- <goal>javadoc</goal> -->
            </goals>
          </execution>
        </executions>
        <configuration>
          <show>protected</show>
          <nohelp>false</nohelp>
        </configuration>
      </plugin>

    </plugins>
  </build>
<project>

7.2. Die im Hintergrund wirkende Effektive POM-Datei

Die Effektive POM-Datei kann auf der Kommandozeile (mit installierter Kommandozeilen-Version von Maven) angezeigt werden mit
mvn -Dverbose=true help:effective-pom (-Dverbose=true ist optional, erzeugt XML-Kommentare, die den Ursprung jedes Elements nennen).

Auch in IntelliJ kann sie leicht angezeigt werden!

Die Effektive POM-Datei ist die Konfigurationsdatei, die tatsächlich verwendet wird. Sie wird aus der eigentlichen Konfigurationsdatei und allen Eltern-Konfigurationsdateien erzeugt.

Eine immer vorhandene Eltern-Konfigurationsdatei ist die von Maven selbst. Diese ist nicht sichtbar, aber die Effektive POM-Datei enthält alle Elemente daraus.

7.3. Doku zum 'maven-source-plugin':

7.4. Doku zum 'maven-javadoc-plugin':

Apache Maven Javadoc Plugin – Introduction
Apache Maven Javadoc Plugin – Goal 'javadoc'
Apache Maven Javadoc Plugin – Goal 'jar'

7.5. Maven Diverses

Override Maven Plugin Configuration from Parent | Baeldung …​ 2022-09-24

Plugin Management in Maven | Baeldung …​ 2022-09-24

ITOM Practitioner Portal …​ 2022-09-24

Maven Dependency Scopes - HowToDoInJava …​ 2022-10-05

Maven Dependency Management and Version Ranges - External Dependencies …​ 2022-10-05:

<dependency>
  <groupId>extDependency</groupId>
  <artifactId>extDependency</artifactId>
  <scope>system</scope>
  <version>1.0</version>
  <systemPath>${basedir}\war\WEB-INF\lib\extDependency.jar</systemPath>
</dependency>

  • The groupId and artifactId are both set to the name of the dependency.

  • The scope element value is set to system.

  • The systemPath element refer to the location of the JAR file.

https://www.baeldung.com/maven [Apache Maven Tutorial | Baeldung] …​ 2023-12-20

7.6. Maven Wrapper

https://maven.apache.org/wrapper/ [Apache Maven Wrapper – Maven Wrapper] …​ 6.10.2022, 17:02:25

7.7. xx

https://www.baeldung.com/maven-dependency-scopes [Maven Dependency Scopes | Baeldung] …​ 28.12.2022, 16:17:59

https://stackoverflow.com/questions/38882221/how-to-inherit-dependency-from-a-parent-pom-to-a-child-pom [maven - How to inherit dependency from a parent pom to a child pom - Stack Overflow] …​ 2022-12-30

https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html [Maven – Introduction to the Dependency Mechanism] …​ 2022-12-30

https://metamug.com/article/java/build-run-java-maven-project-command-line.html [Java - Build Run Maven Project Command Line] …​ 2022-12-30

https://www.digitalocean.com/community/tutorials/maven-commands-options-cheat-sheet [20+ Maven Commands and Options (Cheat Sheet) | DigitalOcean] …​ 2022-12-30

https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html [Maven – Maven in 5 Minutes] …​ 2022-12-30

7.8. Exec Plugin

https://www.mojohaus.org/exec-maven-plugin/ [Exec Maven Plugin – Introduction] …​ 2022-12-30

7.9. JavaFX

https://github.com/openjfx/javafx-maven-plugin [GitHub - openjfx/javafx-maven-plugin: Maven plugin to run JavaFX 11+ applications] …​ 2022-12-30

https://openjfx.io/openjfx-docs/#maven [Getting Started with JavaFX] …​ 2022-12-30

https://openjfx.io/openjfx-docs/maven [https://openjfx.io/openjfx-docs/maven] …​ 2022-12-30

https://github.com/openjfx/javafx-maven-archetypes [GitHub - openjfx/javafx-maven-archetypes: Maven Archetypes for various JavaFX projects] …​ 2022-12-30

https://stackoverflow.com/questions/54258875/javafx-with-maven-works-with-execjava-but-not-in-the-jar-at-runtime [JavaFX with Maven works with exec:java but not in the jar at runtime - Stack Overflow] …​ 2022-12-30

https://github.com/openjfx/openjfx-docs/issues/76 [mvn exec:java might cause issues · Issue #76 · openjfx/openjfx-docs · GitHub] …​ 2022-12-30

https://www.java-forum.org/thema/javafx-jar-mit-maven.190267/ [JavaFX jar mit Maven ♨󠄂‍󠆷 Java - Hilfe | Java-Forum.org] …​ 2022-12-30

https://stackoverflow.com/questions/62849887/is-there-a-good-approach-at-automatically-incrementing-maven-versions [git - Is there a good approach at automatically incrementing maven versions - Stack Overflow] …​ 2023-03-06

https://gist.github.com/xmeng1/5b2c5b4b2cf326348b8741a2e3cd4e7e [Script that uses the versions-maven-plugin to automatically increment the build number in the version of a project. This …​] …​ 2023-03-06

https://wyssmann.com/blog/2021/03/how-to-increment-versions-in-maven-builds-alternative-to-maven-release-plugin/ [How to increment versions in maven builds - alternative to maven release plugin - Wyssmann Engineering] …​ 2023-03-06

https://github.com/Invvk/auto-increment-plugin [GitHub - Invvk/auto-increment-plugin: Maven plugin that automatically increases the version number accordingly, it suppo …​] …​ 2023-03-06

7.10. Scribble JavaFX

mvn archetype:generate \ -DarchetypeGroupId=org.openjfx \ -DarchetypeArtifactId=javafx-archetype-fxml \ -DarchetypeVersion=0.0.6 \ -DgroupId=athtlw5.rx_scribble \ -DartifactId=mvn-archetype-fxml-trial1 \ -Dversion=1.0-SNAPSHOT \ -Djavafx-version=19 \ -Dadd-debug-configuration=Y

8. Unsortiert

https://michakutz.medium.com/legit-but-useless-maven-version-ranges-explained-d4ba66ac654 [Legit but Useless: Maven Version Ranges Explained | by Michael Kutz | Medium] …​ 30.4.2023, 08:15:24

https://stackoverflow.com/questions/30571/how-do-i-tell-maven-to-use-the-latest-version-of-a-dependency [java - How do I tell Maven to use the latest version of a dependency? - Stack Overflow] …​ 30.4.2023, 08:16:23

https://www.mojohaus.org/versions/versions-maven-plugin/examples/resolve-ranges.html [Versions Maven Plugin – Resolve Ranges] …​ 30.4.2023, 08:16:57

https://www.baeldung.com/maven-dependency-latest-version [Use the Latest Version of a Dependency in Maven | Baeldung] …​ 30.4.2023, 08:20:58