Restful Protobuf Hands-On

Restful Beispiel, das auf JaxRS und Google Protocol Buffers (protobuf) basiert (+ Maven und Java 8)

GitHub Fork

Einfach https://github.com/sam6-de/RestfulProtobuf besuchen und den Anweisungen folgen.

Restful Java Api mit Protobuf

Dieser Artikel beschreibt einen Prototyp für ein Standalone war. Es bietet einen Restful-Service mit Jersey / JAX-RS (JSR 311) und Google Protocol Buffers (protobuf).
Dieses Projekt ist nur eine Machbarkeitsstudie und ist nicht Produktionsreif.

Vorbereitung

Das Projekt benötigt die folgenden Tools in den angegebenen Versionen:

• Maven 3.3.3
• Protoc 3.0.0-alpha-3
• Oracle JDK 1.8.0_45

Quickstart

Um sofort loslegen zu können, musst du nur drei Schritte ausführen:

1. Das Projekt von GitHub mittels
   git clone https://github.com/sam6-de/RestfulProtobuf.git clonen.
2. Das frisch geclonte Projekt über
   cd ./RestfulProtobuf/ && mvn clean install mit Maven bauen.
3. Den eingebetteten Jetty mittels
   cd ./RestWebapp/target/ && java -jar RestWebapp-1.0-SNAPSHOT.war starten.

Zack: Jetzt ist der Dienst über den Port 8080 aktiv.
Über einen Browser kannst du jetzt direkt darauf zugreifen. Das heißt, du rufst im Browser einfach die URL http://localhost:8080/rest/hello/world auf.

Jersey generiert automatisch eine WADL-Datei, die alle logischen Operationen beschreibt:
http://localhost:8080/rest/application.wadl.
Das erste Dokument ist eine vereinfachte WADL, die nur Benutzer- und Kernressourcen beschreibt.
Um eine vollständige WADL mit erweiterten Ressourcen zu erhalten, nutzt du einfach den Abfrageparameter detail:
http://localhost:8080/rest/application.wadl?Detail=true

Restful Protobuf API from Scratch

Um das Grundgerüst manuell über Maven Archetypes aufzubauen, geht man am einfachsten wie hier beschrieben vor.

Vorbereitung

Wir wollen das Maven-Projekt als Multi-Modul-Projekt einrichten. Dazu müssen wir zuerst eine root-Datei pom.xml erstellen.
Das klappt am schnellsten auf der Konsole, indem du folgenden Befehl ausführst:

mvn archetype:generate \
   -DarchetypeGroupId=org.codehaus.mojo.archetypes \
   -DarchetypeArtifactId=pom-root \
   -DarchetypeVersion=RELEASE \
   -DgroupId=de.sam6.demo \
   -DartifactId=RestfulProtobuf \
   -DinteractiveMode=false

Danach wollen wir ein neues, erstes Submodul im Projekt erstellen. Wechsel also in das neu erzeugte Verzeichnis. Innerhalb nutzen wir wieder einen Maven-Archetyp, diesmal vom Typ webapp. Er erstellt die (meisten) erforderlichen Ordner und Dateien:

cd RestfulProtobuf/
mvn archetype:generate \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DgroupId=de.sam6.demo \
   -DartifactId=RestWebapp \
   -DinteractiveMode=false

Da der java-Quellordner nicht automatisch erstellt wird, erstellst du ihn einfach manuell:

mkdir RestWebapp/src/main/java

Fertig! Jetzt kannst du das gesamte Multi-Modul-Projekt in die Lieblings-IDE importieren.

Abhängigkeiten

Damit alle Abhängigkeiten, die wir benötigen, korrekt aufgelöst werden können, fügen wir diese der pom.xml hinzu.

JAX-RS 2.0 Implementierung

Für den Restful-Service verwendete Abhängigkeiten sind:

        <dependency>
            <groupId>org.glassfish.jersey.core</groupId>
            <artifactId>jersey-server</artifactId>
            <version>2.18</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.containers</groupId>
            <artifactId>jersey-container-servlet</artifactId>
            <version>2.18</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.core</groupId>
            <artifactId>jersey-client</artifactId>
            <version>2.18</version>
        </dependency>

Google Protocol Buffers (protobuf)

Die Protobuf-Bibliothek unterstützt eine extrem schnelle (De-)Serialisierung, die von unserem Service als Austauschformat verwendet wird:

        <dependency>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protobuf-java</artifactId>
            <version>3.0.0-alpha-3</version>
        </dependency>

Standalone Restful Protobuf API

Damit die Applikation einfach so gestartet werden kann, gibt es hier einen weiteren Import:

        <dependency>
            <groupId>org.eclipse.jetty</groupId>
            <artifactId>jetty-webapp</artifactId>
            <version>9.3.0.v20150612</version>
            <scope>provided</scope>
        </dependency>

Das war es auch schon. Jetzt liegt es an dir, weitere Funktionen hinzu zu fügen. Viel Spaß dabei!

Weitere interessante Blog-Artikel gibt es im Chameleon Blog.