Schnittstellendefinition_1.md

<style>
.opt {
    color: #ed767e;
    font-style: italic;
}
</style>

# Schnittstellendefinition
## Versionsübersicht
1. ### [**API-Definition Version 1**](#v1)
## Allgemeines
### Verwendete Netzwerktechnologie:
- java.net.Socket
- java.net.ServerSocket

### Art des Datentransfers:
- Plaintext

### Standardport
* 42069

### Andere Festlegungen:
- Für den Host ist es uninteressant, ob der Client berechtigt ist auf einem Semester zu spielen. Es existiert demnach keine zentrale "Registry", welche den Fortschritt aller Nutzer trackt. Diese Aufgabe übernimmt jeder Host/Client für sich selbst intern.
- Schiffe mit der Größe `8-Credits <= 0` werden aufgeteilt in einzelne Schiffe der Größe `8-Credits/2`
>    - <span style="color:orange">***ACHTUNG*** Eine Größe von `1` ist für eine sinnvolle implementierung einer KI ungeeignet. Es ist sinnvoller die Formel `max(8-Credits, 2)` zu verwenden.*



### **Schiffsgrößen nach Semester**

| Semester | Schiffe & Größen |
| -------- | -------- |
| 1         | {2, 2, 2, 2, 4, 6} |
| 2         | {2, 2, 2, 2, 2}    |
| 3         | {2, 2, 2, 2, 4, 6} |
| 4         | {2, 2, 2, 2, 4, 6} |
| 5         | {2, 2, 2, 3, 3, 6} |
| 6         | {2, 1, 1, 1, 6}   |


# [**API-Definition Version 1**](#v1)<a id="v1"></a>
### Übersicht
1. [Allgemeine Beschreibung der Kommunikation](#v1/general)
    1. [Struktur einer Nachricht](#v1/general/msg_structure)
    2. [Ablauf der Verbindung](#v1/general/connection_timeline)
2. [Schnittstellenendpunkte](#v1/api)
    * [HELLO](#v1/api/hello)
    * [HELLO_ACK](#v1/api/hello_ack)
    * [START](#v1/api/start)
    * [START_ack](#v1/api/start_ack)
    * [READY_PING](#v1/api/ready_ping)
    * [READY_CHK](#ready_chk)
    * [BEGIN](#v1/api/begin)
    * [BEGIN_ACK](#v1/api/begin_ack)
    * [FIRE](#v1/api/fire)
    * [FIRE_ACK](#v1/api/fire_ack)
    * [END](#v1/api/end)
    * [END_ACK](#v1/api/end_ack)
    * [BYE](#v1/api/bye)
    * [ERR](#v1/api/err)


## [Allgemeine Beschreibung der Kommunikation](#v1/general)<a id="v1/general"></a>
### [Struktur einer Nachricht](#v1/general/msg_structure)<a id="v1/general/msg_structure"></a>
Nachrichten sind aufgebaut nach dem Schema:
```
COMMAND;<ARGUMENT>[;[<OPTIONAL_ARG1>][;OPTIONAL_ARG2]]
```
Jeder Teil der Nachricht ist mit einem `;` getrennt. 
Die Daten können in Java mithilfe von `String.split(";");` ausgelesen werden.

*COMMAND:* 

Am Anfang steht immer der auszührende Befehl (*COMMAND*). Dieser gibt an, was ein Netzwerkteilnehmer tun soll.

*\<ARGUMENT\>:*
Auf den *COMMAND* folgen jegliche Argumente, die zwingend erforderlich sind.
```
COMMAND;ARGUMENT1;ARGUMENT2;...
```
    
*[OPTIONAL_ARG]:*

Auf das letzte *ARGUMENT* folgen alle optionalen Argumente.
Sollte bspw. nur *OPTIONAL_ARG2* übergeben werden kann die Nachricht wie folgt übermittelt werden:
```
COMMAND;ARGUMENT;;OPTIONAL_ARG2
```

### [Ablauf der Verbindung](#v1/general/connection_timeline)<a id="v1/general/connection_timeline"></a>
![](Ablauf_Sequenzdiagramm.svg)



## [Schnittstellenendpunkte](#v1/api)<a id="v1/api"></a>
### [HELLO](#v1/api/hello)<a id="v1/api/hello"></a>
**Synopsis:**
```
HELLO;<VERSION>;<MAX_SEMESTER>;<USERNAME>
```

**Beschreibung:**
Die erste Nachricht der Verbindung und wird nach Herstellung der SocketVerbindung von dem Host an den Client gesendet.

**Argumente:**
* *VERSION:* Versionsnummer des Programms
    * int: API_VERSION
* *MAX_SEMESTER:* Höchstes spielbares Semester des Client
    * int: Ganzzahl $\in$ [1,6]
* *USERNAME:* Spielername des *Client*
    * String (UTF-8)
    * Maximale Länge: 255 Zeichen
    
**Antwort:**
* [HELLO_ACK](#v1/api/hello_ack): Bestätigung der Verbindung durch den *Client*


----
### [HELLO_ACK](#v1/api/hello_ack)<a id="v1/api/start"></a>

**Synopsis:**
```
HELLO_ACK;<VERSION>;<USERNAME>;<SEMESTER>
```
**Beschreibung:**
Signalisiert de Start einer Session durch den *Host* an den *Client*.
    
*Diese Nachricht wird als Antwort auf eine [HELLO](#v1/api/hello)-Nachricht gesendet.*

**Argumente:**
* *VERSION:* Versionsnummer des Programms
    * int: API_VERSION
* *SEMESTER:* Das Semester auf dem die Session gespielt werden wird
    * **int**: Ganzzahl $\in$ [1,6]
    * berechnet mit `min(hostSemester, clientSemester)`
* *USERNAME:* Spielername des *Host*
    * **String**: 
        * Encoding Format: UTF-8
        * Maximale Länge 255 Zeichen

----
### [START](#v1/api/start)<a id="v1/api/start"></a>
**Synopsis:**
```
START
```
**Beschreibung:**
Infomiert den Client durch den Host dass das die Partie gestartet wird.

**Antwort:**
* [START_ACK](#v1/api/start_ack): Bestätigung des Partiebeginns durch den *Client*
    
----
### [START_ACK](#v1/api/start_ack)<a id="v1/api/start_ack"></a>
**Synopsis:**
```
START_ACK
```
**Beschreibung:**
Bestätigt dem Host durch den Client, dass das die Partie gestartet wird.
    
*Diese Nachricht wird als Antwort auf eine [START](#v1/api/start)-Nachricht gesendet.*
    
----
### [READY_PING](#v1/api/ready_ping)<a id="v1/api/ready_ping"></a>
**Synopsis:**
```
READY_PING;<SHIPS_PLACED>
```
**Beschreibung:**
Stellt eine Anfrage an den Client während der Vorbereitungsphase, wie viele Schiffe dieser Bereits plaziert hat.
Sind alle Schiffe plaziert, wird stattdessen eine [READY_CHK](#v1/api/ready_chk)-Antwort vom Client gesendet.

**Argumente:**
* *SHIPS_PLACED:* Anzahl der noch nicht platzierten Schiffe
    * **int**: Ganzzahl $\in$ (0, Anzahl der Schiffe]
    
**Antwort:**
* [READY_PING](#v1/api/ready_ping): Nicht alle Schiffe wurden plaziert oder der Client ist nicht bereit fortzufahren
* [READY_CHK](#v1/api/ready_chk): Alle Schiffe wurden plaziert und der Client ist bereit fortzufahren
    
----
### [READY_CHK](#v1/api/ready_chk)<a id="v1/api/ready_chk"></a>
**Synopsis:**
```
READY_CHK
```
**Beschreibung:**
Bestätigt das Platzieren sämtlicher Schiffe des Clients und dessen Bereitschaft mit der Partie zu beginnen.
Das Senden einer extra Nachricht ermöglicht es dem Benutzer des Client ggfs. Änderungen seiner Schiffplatzierung vorzunehmen, auch wenn alle Schiffe platziert sind

----
### [BEGIN](#v1/api/begin)<a id="v1/api/begin"></a>
**Synopsis:**
```
BEGIN;<WHO>
```
**Beschreibung:**
Signalisiert dem Client durch den Host, dass die Vorbereitungsphase beendet und das Spiel begonnen wird. Der Host entscheidet durch einen Münzwurf (Zufall), welche Seite beginnt.

**Argumente:**
* *WHO*: Der beginnende Spieler
    * String ∈ { "host", "client" }

**Antwort**
* [FIRE_ACK](#v1/api/fire_ack): Die Nachricht vom Gegenspieler, dass der Spielzug akzeptiert wurde
* [ERR](#v1/api/err): Die Nachricht konnte nicht vom Gegenspieler verarbeitet werden
    * *ILLEGAL_STATE*: Der Sendende ist nicht am Zug    

----
### [BEGIN_ACK](#v1/api/begin_ack)<a id="v1/api/begin_ack"></a>
**Synopsis:**
```
BEGIN_ACK;<WHO>
```
**Beschreibung:**
Signalisiert dem Host durch den Client, dass die Beendigung der Vorbereitungsphase und der Beginn des Spiels akzeptiert wurde.

*Diese Nachricht wird als Antwort auf eine [BEGIN](#v1/api/begin)-Nachricht gesendet.*
    
----
### [FIRE](#v1/api/fire)<a id="v1/api/fire"></a>
**Synopsis:**
```
FIRE;<ROW>;<COLUMN>
```
**Beschreibung:**
Greift den Gegenspieler auf einer Koordinate an. Die 

**Argumente:**
* *ROW:* Das Feld im Spielfeld welches beschossen wird
    * **int**: im Intervall [0, Spielfeldgröße-1]
* *COLUMN:* Das Feld im Spielfeld welches beschossen wird
    * **int**: im Intervall [0, Spielfeldgröße-1]

**Antwort**
* [FIRE_ACK](#v1/api/fire_ack): Die Nachricht vom Gegenspieler, dass der Spielzug akzeptiert wurde
* [ERR](#v1/api/err): Die Nachricht konnte nicht vom Gegenspieler verarbeitet werden
    * *ILLEGAL_STATE*: Der Sendende ist nicht am Zug
    
----
### [FIRE_ACK](#v1/api/fire_ack)<a id="v1/api/fire_ack"></a>
**Synopsis:**
```
FIRE_ACK;<TYPE>[;<GAME_OVER>]
```
**Beschreibung:**
Gibt dem Gegenspieler eine Rückmeldung, ob der Angriff auf ein spezifisches Feld getroffen hat. Bei einem Treffer (oder Zerstörung) eines Schiffes durch den Gegner erhält dieser einen weiteren Angriff. 
    
*Diese Nachricht wird als Antwort auf eine [FIRE](#v1/api/fire)-Nachricht gesendet.*

**Argumente:**
* *TYPE:* Das Ergebnis des Angriffs
    * **String** ∈ {"HIT", "MISS", "SUNK"}
* *GAME_OVER:* Letztes Schiff des Sendenden versenkt
    * **String** $\in$ {"true"}

----
### [END](#v1/api/end)<a id="v1/api/end"></a>
**Synopsis:**
```
END;<WINNER>
```
**Beschreibung:**
Bestätigt dem Client das Ende der Partie und teilt diesem das Ergebnis mit.

**Argumente:**
* *WINNER:* Das Ergebnis des Angriffs
    * **String** $\in$ {"host", "client"}

**Antwort**
* [END_ACK](#v1/api/end_ack): Das Spielergebnis wurde akzeptiert
* [ERR](#v1/api/err): Die Nachricht konnte nicht vom Client verarbeitet werden
    * *ILLEGAL_STATE*: Der interne Gewinner stimmt nicht mit dem Argument <WINNER>
    
----
### [END_ACK](#v1/api/end_ack)<a id="v1/api/end_ack"></a>
**Synopsis:**
```
END_ACK
```
**Beschreibung:**
Bestätigt dem Host das Empfangen und die Akzeptanz des Spielergebnisses.
    
*Diese Nachricht wird als Antwort auf eine [END](#v1/api/end)-Nachricht gesendet.*

----
### [BYE](#v1/api/bye)<a id="v1/api/bye"></a>
**Synopsis:**
```
BYE;[<CODE>;<REASON>]
```
**Beschreibung:**
Informiert den Gegenspieler von einer gewollten (graceful) Beendigung der Verbindung.

**Argumente:**
* *CODE (optional):* Eine Zahl die ein konkretes Ergebnis (keinen Fehler) repräsentiert
    * **int**: Eine positive Ganzzahl 
* *REASON (optional):* Eine Beschreibung warum die Verbindung beendet wurde
    * **String**: 
        * Encoding Format: UTF-8
        * Maximale Länge 255 Zeichen

----
### [ERR](#v1/api/err)<a id="v1/api/err"></a>
**Synopsis:**
```
ERR;<CODE>;<REASON>
```
**Beschreibung:**
Informiert den Gegenspieler von einer unerwarteten Beendigung der Verbindung.

**Argumente:**
* *CODE:* Eine Zahl die ein konkretes Ergebnis (keinen Fehler) repräsentiert
    * **int**: Eine negative Ganzzahl (siehe *Error Codes*)
* *REASON:* Eine Beschreibung warum die Verbindung beendet wurde
    * **String**: 
        * Encoding Format: UTF-8
        * Maximale Länge 255 Zeichen
    
**Error Codes**
1. *UNEXPECTED_MESSAGE*: Die empfangene Nachricht wurde nicht erwartet
2. *ILLEGAL_STATE*: Die empfangene Nachricht wurde erwartet, der Nachrichteninhalt entspricht jedoch nicht den Erwartungen 
3. *ILLEGAL_ARGUMENT*: Ein oder mehrere Argumente der empfangenen Nachricht sind nicht korrekt