Entwickeln der Grundlage

Der Einstieg in die Twasi-Plugin-Entwicklung ist einfach. Alles, was du benötigst sind Grundkenntnis der Java-Programmiersprache und einer IDE (Integrated Development Environment).

Wir empfehlen ausdrücklich IntelliJ IDEA für Java-Entwicklung zu verwenden, da es die intelligenteste verfügbare IDE ist und die Programmierung stark beschleunigt. Es gibt eine kostenlose Community-Version, die alles bietet, was du je brauchen wirst. Du kannt diese hier herunterladen.

Wir werden ein Beispiel-Plugin ohne weitere Funktionalität erstellen. Auf den nächsten Seiten werden wir Befehle, Variablen, Berechtigungen, Dienste, eine API und ein Datenbankarchiv dafür hinzufügen.

Um fortzufahren, stelle bitte sicher, dass du JDK 1.8 installiert hast. Du kannst auch eine OpenJDK Build, Version 1.8, von hier verwenden. Die Twasi Entwicklung funktioniert gut damit.

Erstellung eines Projekts

Zuerst musst du ein neues Maven-Projekt erstellen. Dafür verwende ich IntelliJ IDEA. Wenn du eine andere IDE verwenden möchtest, finde bitte heraus, wie du damit ein Maven-Projekt im Internet erstellen kannst.

Maven ein Dependency Injection System für Java. Es hilft dir, das Twasi-Plugin-Framework zu deinem Projekt hinzuzufügen. Bitte lass dich nicht abschrecken, wenn du Maven noch nicht benutzt hast. Es ist ganz einfach, loszulegen und dein Abhängigkeitsmanagement zu vereinfachen.

Klicke dazu auf "Neues Projekt erstellen", wähle Maven auf der linken Seite aus und wähle (oder konfiguriere) deine JDK 1.8. Danach musst du ein Paket und eine ArtifactID auswählen. Bitte verwende deinen eigenen Paketnamen (der normalerweise aus einem Domain-Namen besteht, den du im Gegenzug besitzt: merlinw.de > de.merlinw, twasi.net > net.twasi). Die ArtifactID ist der Name deines Plugins / Projektes.

Maven erstellt nun diese Dateistruktur für dich:

|
+-- src/
|   +-- main/
|   |   +-- java/
|   |   +-- resources/
|   |
|   +-- test/
|       +-- java/
|
+-- pom.xml
|

Hinzufügen des Frameworks mit Maven

Öffne die pom.xml Datei. Hier kannst du die Abhängigkeiten deines Plugins angeben. Es wird so ähnlich aussehen:

<?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>de.merlinw</groupId>
    <artifactId>ExamplePlugin</artifactId>
    <version>1.0-SNAPSHOT</version>

</project>

IntelliJ wird dich auffordern, den Autoimport in der unteren rechten Ecke zu aktivieren. Du solltest das tun, es ist sehr nützlich!

Jetzt müssen wir Twasi-Core in unser Projekt aufnehmen, um Zugang zum Plugin-Framework zu erhalten. Wir müssen auch Maven sagen, wo man nach ihm suchen soll. Dazu fügen wir die Twasi-Artifactory als Repository und den Twasi-Core als Abhängigkeit hinzu (direkt nach dem <** Version**>-Tag):

    <repositories>
        <repository>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <id>central</id>
            <name>libs-release</name>
            <url>https://artifactory.twasi.net/artifactory/libs-release</url>
        </repository>
        <repository>
            <snapshots/>
            <id>snapshots</id>
            <name>libs-snapshot</name>
            <url>https://artifactory.twasi.net/artifactory/libs-snapshot</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>net.twasi</groupId>
            <artifactId>TwasiCore</artifactId>
            <version>0.0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

Wenn du IntelliJ nicht verwendest oder Auto-Import deaktiviert hast, stelle sicher, dass maven die Abhängigkeiten importiert.

"<scope>provided</scope>" erklärt dem Maven Compiler, den Twasi-Core nicht in deine jar-Datei mit aufzunehmen, wenn du dein Plugin kompilierst. Da das Plugin direkt aus dem Core geladen wird, werden alle Klassen des Frameworks zur Laufzeit verfügbar sein.

Erstellen der Hauptklassen des Plugins

Die TwasiPlugin-Klasse

Der Einstieg eines jeden Twasi-Plugins ist die TwasiPlugin-Klasse. Um es hinzuzufügen, erstelle dein Paket im Ordner "/src/main/java/" und füge eine neue Klasse hinzu (du kannst jeden Klassennamen verwenden, ich nehme Example-Plugin) und erweitere es zu TwasiPlugin wie folgt:

package de.merlinw;

import net.twasi.core.logger.TwasiLogger;
import net.twasi.core.plugin.TwasiPlugin;
import net.twasi.core.plugin.api.TwasiUserPlugin;

public class ExamplePlugin extends TwasiPlugin {

    public Class<? extends TwasiUserPlugin> getUserPluginClass() {
        return null;
    }

    // To test if your plugin works, you can make it say hello on startup
    public void onActivate(){
        TwasiLogger.log.info("Hello! I'm the example plugin c:");
    }

}

Die TwasiUserPlugin-Klasse

Jedes Plugin muss eine TwasiUserPlugin-Klasse angeben. Diese Klasse wird für jeden Benutzer, der das Plugin installiert hat, instanziiert. Füge eine andere Klasse hinzu (ich werde es ExampleUserPlugin nennen) und erweitere es zu TwasiUserPlugin:

package de.merlinw;

import net.twasi.core.plugin.api.TwasiUserPlugin;

public class ExampleUserPlugin extends TwasiUserPlugin {    
}

Nun mache dein TwasiPlugin mit der UserPlugin Klasse bekannt, unter Verwendung der getUserPluginClass() Methode:

package de.merlinw;

import net.twasi.core.plugin.TwasiPlugin;
import net.twasi.core.plugin.api.TwasiUserPlugin;

public class ExamplePlugin extends TwasiPlugin {

    public Class<? extends TwasiUserPlugin> getUserPluginClass() {
        return ExampleUserPlugin.class;
    }

}

Plugin.yml-Datei erstellen

Jetzt musst du Twasi-Core mitteilen, wo deine TwasiPlugin TwasiPlugin-Klasse liegt. Um dies zu tun und den Core mehr Informationen über dein Plugin (wie beispielsweise der Name, Version etc.) zu geben, erstelle eine neue Datei namens "plugin.yml" im Verzeichnis "/src/main/resources" mit den folgenden Eigenschaften:

name: "ExamplePlugin" # This should be unique
author: "Merlin Westphal"
main: de.merlinw.ExamplePlugin # Specify the full name including the package
description: "Just an example plugin"

Du kannst alle verfügbaren Eigenschaften hier finden.

Plugin-Konfiguration hinzufügen

Wenn dein Plugin eine Konfiguration benötigt (für API-Anmeldedaten z.B.), kannst du eine Konfigurationsvorlage definieren und Twasi den Rest für dich erledigen lassen. Es wird automatisch für dich eine yml-Datei erstellen, die in deinem Code in kürzester Zeit verwendet werden kann.

Wenn dein Plugin keine weiteren Konfigurationseigenschaften benötigt, kannst du diesen Schritt einfach überspringen!

Die Template-Klasse

Du musst die Eigenschaften definieren, die deine Konfigurationsdatei in einer Klasse wie dieser enthalten sollte:

public class MyPluginConfiguration {

    public String API_KEY = "API_TOKEN";
    public String API_SECRET = "API_SECRET";
    public String[] SCOPES = {};

}

Template zuweisen und die Konfiguration zur Laufzeit laden

In deiner TwasiPluginKlasse kannst du diese Vorlage nun durch die Definition eines Typparameters an Twasi übergeben und die Konfiguration über die getConfiguration() Methode erhalten:

public class MyPlugin extends TwasiPlugin<MyPluginConfiguration> {

    public void onActivate(){
        MyPluginConfiguration config = this.getConfiguration();
        TwasiLogger.log.debug("API-Token: " + config.API_KEY);
    }

}

Wenn die Methode getConfiguration() erstmals aufgerufen wird, wird eine yaml-Datei mit allen Feldern deiner Vorlage im /plugins/config-Ordner erstellt (Plugin-Name.yml). Wenn du die Werte in der Vorlage definierst, werden sie als Standardwerte in die yaml-Datei gesetzt.

Nesting Eigenschaften

Du kannst auch Eigenschaften verschachteln, indem du eine Unterklasse wie diese definierst:

public class MyPluginConfiguration {

    public int property = 10;
    public APICredentials API = new APICredentials();

    public class APICredentials {
        public String API_KEY = "API_TOKEN";
        public String API_SECRET = "API_SECRET";
        public String[] SCOPES = {};
    }

}

Erstellung des Plugins

Um dein Plugin in einer lokalen Umgebung zu testen, musst du eine Twasi-Core-Instanz einrichten, wenn du das nicht bereits getan hast. Du kannst hier lernen, wie man das macht.

Deine Plugin-Basis ist fertig und Twasi-Core sollte es laden können. Alles, was du jetzt tun musst, ist, es zu erstellen, um eine.jar-Datei zu erhalten. In IntelliJ kannst du dafür eine Laufzeitkonfiguration erstellen. Klicke einfach auf "Konfiguration hinzufügen" in der oberen Leiste der IDE, klicke auf den Hinzufügen-Button, wähle Maven und gebe "clean compile package" in das Kommandozeilenfeld ein. Speichere die Konfiguration und klicken auf ausführen. Jetzt kompiliert Maven dein Plugin und setzt die .jar-Datei in einen neuen Ordner namens "target".

Wenn du IntelliJ nicht verwendest, installiere Maven global auf deinem System. Hier kannst du ein Tutorial dafür finden.

Nachdem du Maven installiert hast, öffne einfach ein Terminal im Stammverzeichnis deines Plugins (wo sich die pom.xml-Datei befindet) und starte "mvn clean compile package".

Fortfahren

Im nächsten Teil der "Getting started" Serie wirst du lernen, wie du Befehle zu deinem Plugin hinzufügen kannst!