Gruppe-02-clone/Projekte/README.md

# Beispielprogramme des Programmierprojekts

Hier ist der Quellcode für das in der Einarbeitungsphase genutzte Spiel
_Battleships_ zu finden. Die Quellen bestehen aus den folgenden
Gradle-Unterprojekten:

* _:battleship:server_
* _:battleship:client_
* _:battleship:model_
* _:battleship:converter_
* _:common_
* _:jme-common_

_Battleships_ ist ein netzwerkbasiertes Spiel und besteht aus einem Server- und
einem Clientanteil, die in den Unterprojekten _:battleship:server_ und
_:battleship:client_ realisiert sind. Beide nutzen das Unterprojekt
_:battleship:model_, das den gemeinsamen Modellanteil enthält.

Die Unterprojekte _:common_ und _:jme-common_ enthalten Hilfsklassen.

Das Unterprojekt _:battleship:converter_ wird für _Battleships_ selbst nicht
benötigt, sondern enthält lediglich den Code, um ein im Spiel verwendetes
3d-Modell eines Schlachtschiffs in eine _J3O_-Datei umzuwandeln, die von jME
einfacher geladen werden kann.

## 1 Vorbereitung

Für das Programmierprojekt empfehlen wir die Verwendung von Java 20. Unter Linux
sollte [_Eclipse Temurin_](https://adoptium.net/temurin/releases/?version=20)
als JDK verwendet werden, andere JDKs können unter Linux Probleme verursachen.
Auf anderen Betriebssystemen empfehlen wir aber ebenfalls Temurin. Im Folgenden
ist beschrieben, wie Sie Temurin installieren und die Umgebungsvariable
**JAVA_HOME** richtig setzen, damit Sie Gradle (siehe unten) verwenden können.

### 1.1 Installation von Temurin

Laden Sie [_Eclipse Temurin_](https://adoptium.net/temurin/releases/?version=20)
entsprechend Ihrem Betriebssystem und Ihrer Prozessorarchitektur herunter und
entpacken Sie das Archiv in einem Verzeichnis Ihrer Wahl auf Ihrem Rechner.

### 1.2 Setzen von JAVA_HOME

Zur Verwendung mit Gradle muss die Umgebungsvariable **JAVA_HOME** richtig
gesetzt werden. Folgen Sie dazu den nachfolgenden Anweisungen entsprechend Ihrem
Betriebssystem:

* **Windows:**

  Öffnen Sie ihre Powershell (Core) bzw. ihr Windows Terminal mit Powershell
  (Core). Überprüfen Sie, ob die Umgebungsvariable korrekt gesetzt ist:  
  `Get-ChildItem -Path Env:JAVA_HOME`  
  Falls kein oder ein falscher Pfad gesetzt ist, setzen Sie diesen mit dem
  folgenden Kommando (in einer Zeile):  
  `[System.Environment]::SetEnvironmentVariable('JAVA_HOME','<Pfad zum SDK>',[System.EnvironmentVariableTarget]::User)`

  Alternativ können Sie die GUI verwenden. Unter Windows 10 klicken Sie die
  Windows-Taste und dann das Zahnrad um die Einstellungen zu öffnen. Dort wählen
  Sie "System", dann "Info" (links unten) und nun
  "Erweiterte Systemeinstellungen" (rechts) um den Dialog "Systemeigenschaften"
  zu starten. Im Reiter "Erweitert" klicken Sie
  "Umgebungsvariablen..." und klicken dann unter "Benutzervariablen" den Knopf
  "Neu..." um JAVA_HOME anzulegen oder "Bearbeiten" um ihn zu ändern. Geben Sie
  als Name `JAVA_HOME` und als Wert den Pfad ein. Schließen Sie mit "OK".

  > **(!) Beachten Sie, dass Sie die jeweilige Applikation neu starten müssen**,
  > um von der gesetzten Umgebungsvariablen Notiz zu nehmen.
  > Dies betrifft auch die Shell, die Sie gerade verwenden.

* **UNIX (Linux/MacOS):**

  Öffnen oder erstellen Sie die Datei `~/.profile` (wenn Sie die Bash verwenden;
  bei anderen Shells sind es andere Dateien) und ergänzen Sie am Ende der Datei
  die Zeile:

  `export JAVA_HOME="<Pfad zum entpackten Archiv>"`
cd  Ersetzen Sie dabei `<Pfad zum entpackten Archiv>` mit dem entsprechenden Pfad.
  Zum Beispiel:

  `export JAVA_HOME="/home/user/jdk-20.0.2"`

  Fügen Sie dann die folgende Zeile hinzu:

  `export PATH="$JAVA_HOME/bin:$PATH"`

## 2 Programmstart

Grundsätzlich kann man das gesamte Projekt einfach in IntelliJ öffnen. Details
dazu sind im Aufgabenblatt zur Einarbeitungsaufgabe zu finden. Im Folgenden ist
beschrieben, wie die _Batttleships_ unmittelbar von der Kommandozeile gestartet
werden können.

Um _Battleships_ spielen zu können, muss man zuerst das Server-Programm auf
einem Rechner und dann zweimal das Client-Programm auf beliebigen Rechnern
starten, die TCP/IP-Verbindungen zum Server erlauben. Natürlich ist es auch
möglich, alle drei Programme auf demselben Rechner zu starten.

Es empfiehlt sich der Start von der Kommandozeile. Will man alle drei Programme
auf demselben Rechner starten, sollte man dazu drei Shell-Instanzen öffnen und
in jeder eines der Programme starten. Auf diese Weise können die
Logging-Ausgaben der drei Programme voneinander unterschieden werden.

Das Server-Programm startet man unmittelbar mit Gradle mit

`./gradlew :battleship:server:run`

Unter Windows kann es je nach Shell (Eingabeaufforderung cmd) erforderlich sein,
`/` jeweils durch `\ ` zu ersetzen.

Im Verzeichnis `battleship/server` befindet sich die Datei `config.propeties`,
worüber sich der Server konfigurieren lässt. Mit der Zeile `port=1234` lässt
sich der verwendete Server-Port (hier 1234) einstellen. Außerdem befindet sich
dort die Datei `logging.properties`, womit das Logging des Servers konfiguriert
wird.

Das Client-Programm startet man unmittelbar mit Gradle mit

`./gradlew :battleship:client:run`

Die Datei `logging.properties` im Verzeichnis `battleship/client` konfiguriert
das Logging des Clients.

Alternativ kann man auch die Start-Skripte

* `./battleship/server/build/install/battleship-server/bin/battleship-server`
* `./battleship/client/build/install/battleship/bin/battleship`

direkt in der Kommandozeile starten. Allerdings müssen sie zuvor mittels

`./gradlew installDist`

erzeugt worden sein. Beachten Sie aber, dass nur im **aktuellen
Arbeitsverzeichnis** nach den Dateien `config.properties` und
`logging.properties` gesucht wird und diese geladen werden. Das heißt, dass die
vordefinierten Dateien in den Verzeichnissen `battleship/server` und
`battleship/client` nur dann gelesen werden, wenn Sie diese Verzeichnisse als
aktuelle Arbeitsverzeichnisse nutzen. Wie üblich müssen Sie dazu in der
Kommandozeile

`cd battleship/server`

bzw.

`cd battleship/client`

eingeben.

## 3 Hinweise zu _Battleships_

Der _Battleships_-Client hat ein Menü, in das man immer mit der
Esc-Taste kommt. Aus dem Menü heraus lässt sich das Programm auch schließen.
Beachte, dass sich beim Laden und Speichern eines Spiels kein Dateidialog
öffnet. Vielmehr muss man den Dateipfad in das Dialogfeld eingeben. Da
JSON-Dateien geschrieben werden, empfiehlt sich das Datei-Suffix _.json_.

## 4 Allgemeine Gradle-Tasks:

- `./gradlew clean`

  Entfernt alle `build`-Verzeichnisse und alle erzeugten Dateien.

- `./gradlew classes`

  Übersetzt den Quellcode und legt unter build den Bytecode sowie
  Ressourcen ab.

- `./gradlew javadoc`

  Erzeugt die Dokumentation aus den JavaDoc-Kommentaren im Verzeichnis
  `build/docs/javadoc` des jeweiligen Unterprojekts.

- `./gradlew test`

  Führt die JUnit-Tests durch. Ergebnisse sind im Verzeichnis
  `build/reports/tests` des jeweiligen Unterprojekts zu finden.

- `./gradlew build`

  Führt die JUnit-Tests durch und erstellt in `build/distributions`
  gepackte Distributionsdateien

- `./gradlew installDist`

  Erstellt unter `battleship/client/build/install` und
  `battleship/server/build/install` Verzeichnisse, die jeweils eine ausführbare
  Distribution samt Start-Skripten enthält (siehe oben).

---
Juli 2024