Please take note that this blog will be featured in English and German since our development group is located in Mainz on the Rhine, Germany.
A Maven Archetype is a project template to generate new projects on the fly. Even though there is a variety of different archetypes to start with, software developers come to the point where they want to start from an individual archetype that is more appropriate to the application they have in mind.
Even more important companies may create a variety of standardized archetypes that follow the internal code conventions and could be used as start setup for future programs.
A straightforward way to generate such archetypes is to create them form existing projects. But how can this be done?
Since this task was very important recently and our group stumbled upon a certain issue we thought to share this experience with you and show how to create and use the archetype step by step.
To start you´ll need a functioning artefact that you want to use as source of your future archetype. In our example the artefact Id will be “ReferenceProject” and the group Id will be “de.triona.blog”.
Navigate to the workspace folder of your project and open the command prompt. Make sure your project is installed correctly by using the command
mvn clean install
Now you are able create your very own archetype. All you´ll have to do, is navigate into your projects main maven structure, which is in our example:
ReferenceProject
src/main/java
src/main/recources
…
pom.xml
There you can create your archetype with the command:
mvn archetype:create-from-project
which creates your archetype directory in the target/generated-sources folder.
This archetype directory is the starting point for all new projects you want to be based on your reference project.
Now let´s create a new project based on this reference archetype.
First you´ll have to install your new archetype. To do that navigate into your archetype directory folder and again use the command:
mvn clean install
Now your archetype will be installed in your own maven repository, which in our example will be: “C:\Users\user\.m2\repository\de\triona\blog\referenceproject”.
Secondly, navigate to the folder where your future project shall be deployed and open the command prompt. Use the following command:
mvn archetype:generate -DarchetypeGroupId=de.triona.blog -DarchetypeArtifactId=referenceproject -DarchetypeVersion=1.0.0
which will lead to an interactive creation of your new project. You will be asked for the following input:
Define value for property ‘groupId’: <your own group id>
Define value for property ‘artifactId’: <name of your new application>
Define value for property ‘version’: <Which should be 1.0.0>
Define value for property ‘package’ <your own group id>: ear/war/jar
In our case at this point we stumbled upon a mistake, because we thought that the last line which asks for the package can be skipped, since the packaging is included within our archetype data. But this wasn´t the case. Instead, every line of code that contains the String “ear” will be replaced with the default value of your groupId.
A quick example could be a method that is named clearObject(). Skipping the last input line will lead to a method that will be named clde.triona.blogObject().
So simply avoid this mistake by being not as lazy as the author of this blog post has been 😀
Anyway in our example we create a new project with the groupId “de.blog.triona”, the artifactId “newProject” version 1.0.0 as an ear with the input.
Define value for property ‘groupId’: de.blog.triona
Define value for property ‘artifactId’: newProject
Define value for property ‘version’: 1.0.0
Define value for property ‘package’ <your own group id>: ear
This new project can be imported into your workspace as existing maven project and finally be used to develop new programs.
—————————————————————————————————————————-
Und zur Verständlichkeit noch einmal auf Deutsch 😊
Ein MavenArchetyp stellt eine Projektvorlage dar, aus der man bei Bedarf neue Projekte erstellen kann. Obwohl es bereits eine Vielzahl verschiedener Archetypen gibt, werden Software-Entwickler an den Punkt gelangen, an dem sie eigene Archetyps benötigen, um die Anwendung umzusetzen, die sie sich vorstellen. Weitaus wichtiger können solche individuellen Archetypen Firmen als Vorlage zukünftiger Projekte dienen, in denen interne Standards und Architekturen bereits umgesetzt sind.
Ein geradliniger Weg, um solche Archetypen zu schaffen, ist, sie aus bestehenden Projekten zu generieren. Aber wie lässt sich dies bewerkstelligen?
Da wir in unserem Entwicklerteam mit dieser Aufgabe konfrontiert waren und wir dabei auf einige Schwierigkeiten und Komplikationen gestoßen sind, wollen wir gerne unsere Erfahrung mit Euch teilen: Im Folgenden werden wir Schritt für Schritt einen solchen Archetypen generieren und darauf aufbauend ein neues Projekt anlegen.
Um zu starten benötigen wir natürlich eine funktionierende Anwendung, die als Vorlage für unseren Archetyp und unsere zukünftigen Anwendungen dient. In unserem Beispiel benennen wir unsere Artefakt-Id „ReferenceProject“ und unsere Gruppen-Id „de.triona.blog“.
Zunächst navigieren wir in unserem Ordner bis zu der Stelle, an der unser Projekt zu finden ist. Dort öffnen wir die Kommandokonsole und stellen über den Befehl
mvn clean install
sicher, dass unser ReferenceProject korrekt installiert ist. Als nächstes begeben wir uns in die Hauptstruktur unseres Projektes, die in unserem Beispiel wie folgt aussieht:
ReferenceProject
src/main/java
src/main/recources
…
pom.xml
Dort generieren wir nun unseren Archetypen über das folgende Kommando
mvn archetype:create-from-project
Über das Kommando wird unser Archetyp im Ordner target/generated-sources anlegt. Der dort zu findende Archetyp-Ordner ist der Ausgangspunkt für all unsere zukünftigen Projekte, die auf unserer Referenz basieren.
Nun wollen wir, ausgehend von diesem Archetyp, ein neues Projekt anlegen. Zunächst müssen wir ihn installieren. Dazu navigieren wir in den Ordner des Archetypens und nutzen erneut das Kommando
mvn clean install
Dadurch haben wir in unserem Maven Repository den Archetyp installiert, was in unserem Beispiel unter
“C:\Users\user\.m2\repository\de\triona\blog\referenceproject”
zu finden ist. Im Anschluss legen wir einen Ordner an, in dem wir unser neues Projekt erstellen wollen und nutzen das folgende Kommando:
mvn archetype:generate -DarchetypeGroupId=de.triona.blog -DarchetypeArtifactId=referenceproject -DarchetypeVersion=1.0.0
Daraufhin startet ein interaktiver Installationsmodus, der uns nach dem folgenden Input fragt:
Define value for property ‘groupId’: <your own group id>
Define value for property ‘artifactId’: <name of your new application>
Define value for property ‘version’: <Which should be 1.0.0>
Define value for property ‘package’ <your own group id>: ear/war/jar
In unserem Fall stolperten wir an dieser Stelle über einen Fehler: Wir gingen fälschlicherweise davon aus, dass in der letzten Zeile, die uns nach dem Package des zukünftigen Projektes fragt, automatisch erkannt wird, dass es sich um ein „ear“ handelt. Diese Angabe ist ja bereits in der pom.xml des Archetyps vorhanden. Aber dies war nicht der Fall. So wurde bei der Installation jede Zeile Code, die den String „ear“ enthielt, durch einen String ersetzt, der den Wert der Gruppen-Id hatte. Ein Beispiel wäre eine Methode namens clearObject(), welche durch den Fehler clde.triona.blogObject() heißen würde.
Nach einiger Recherche wurde uns dieser Fehler bewusst, der sich schlicht durch die Angabe des korrekten Packages beheben lässt. In unserem Beispielkonnten wir also ein neues Projekt namens „newProject“ mit den Angaben
Define value for property ‘groupId’: de.blog.triona
Define value for property ‘artifactId’: newProject
Define value for property ‘version’: 1.0.0
Define value for property ‘package’ <your own group id>: ear
anlegen und in den Workspace als existierendes Maven-Projekt importieren.