The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Quarkusによるスクリプティング

Quarkusは jbang との統合を提供しており、MavenもGradleも必要としないJavaスクリプト/アプリケーションを書くことができます。

このガイドでは、1つのJavaファイルだけを使ってRESTアプリケーションを書く方法を見ていきます。

この技術は、previewと考えられています。

preview では、下位互換性やエコシステムでの存在は保証されていません。具体的な改善には設定や API の変更が必要になるかもしれませんが、 stable になるための計画は現在進行中です。フィードバックは メーリングリストGitHub の課題管理 で受け付けています。

For a full list of possible statuses, check our FAQ entry.

前提条件

このガイドを完成させるには、以下が必要です:

  • ざっと 5 minutes

  • IDE

  • JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

  • JBang

ソリューション

通常はGitリポジトリにリンクしてクローンするのですが、今回は以下のみで追加ファイルはありません。

//usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS io.quarkus.platform:quarkus-bom:2.11.1.Final@pom
//DEPS io.quarkus:quarkus-resteasy-reactive
//JAVAC_OPTIONS -parameters
//JAVA_OPTIONS -Djava.util.logging.manager=org.jboss.logmanager.LogManager

import io.quarkus.runtime.Quarkus;
import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.jboss.logging.Logger;

@Path("/hello")
@ApplicationScoped
public class quarkusapp {

    @GET
    public String sayHello() {
        return "hello";
    }

    public static void main(String[] args) {
        Quarkus.run(args);
    }

    @Inject
    GreetingService service;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("/greeting/{name}")
    public String greeting(String name) {
        return service.greeting(name);
    }

    @ApplicationScoped
    static public class GreetingService {

        public String greeting(String name) {
            return "hello " + name;
        }
    }
}

アーキテクチャ

このガイドでは、 hello エンドポイントを提供する簡単なアプリケーションを、 pom.xmlbuild.gradle のような追加のビルドファイルを必要とせず、単一のソースファイルで作成します。依存関係の注入を実証するために、このエンドポイントは greeting Beanを使用します。

アーキテクチャ

初期ファイルの作成

まず、Javaファイルが必要です。jbangを使うと次のように初期バージョンを作成できます:

jbang init scripting/quarkusapp.java
cd scripting

jbang quarkusapp.java このコマンドは.javaファイルを生成し、LinuxやmacOS、つまり ./quarkusapp.java で直接実行できるようにします。

この初期バージョンは、実行すると Hello World が表示されます。

生成されたら、 quarkusapp.java ファイルを見てみましょう。

一番上にこんな感じの行があります。

//usr/bin/env jbang "$0" "$@" ; exit $?

この行は、LinuxやmacOSでスクリプトとして実行できるようにするためのものです。Windowsではこの行は無視されます。

The next lines

// //DEPS <dependency1> <dependency2>

illustrate how you add dependencies to this script. This is a feature of JBang.

Go ahead and update this line to include the quarkus-bom and the quarkus-resteasy-reactive dependency like so:

//DEPS io.quarkus.platform:quarkus-bom:2.11.1.Final@pom
//DEPS io.quarkus:quarkus-resteasy-reactive

Now, run jbang quarkusapp.java and you will see JBang resolving this dependency and building the jar with help from Quarkus' JBang integration.

$ jbang quarkusapp.java

[jbang] Resolving dependencies...
[jbang]     Resolving io.quarkus:quarkus-resteasy:2.11.1.Final...Done
[jbang] Dependencies resolved
[jbang] Building jar...
[jbang] Post build with io.quarkus.launcher.JBangIntegration
Aug 30, 2020 5:40:55 AM org.jboss.threads.Version <clinit>
INFO: JBoss Threads version 3.1.1.Final
Aug 30, 2020 5:40:56 AM io.quarkus.deployment.QuarkusAugmentor run
INFO: Quarkus augmentation completed in 722ms
Hello World

今のところ、アプリケーションは何も新しいことをしていません。

このファイルを編集してコンテンツアシストを受けるにはどうすればいいですか?

.java ファイルしかないので、ほとんどの IDE はコンテンツアシストをうまく処理できません。これを回避するには、 jbang edit quarkusapp.java を実行すると、IDE で使用できる一時的なプロジェクトの設定があるディレクトリーが出力されます。

Linux/macOSでは、 <idecommand> `jbang edit quarkusapp.java` で実行できます。

If you add dependencies while editing, you can get JBang to automatically refresh the IDE project using jbang edit --live=<idecommand> quarkusapp.java.

JAX-RSリソース

ここで、Quarkusの機能を使用するクラスに置き換えてみましょう。

import io.quarkus.runtime.Quarkus;
import javax.enterprise.context.ApplicationScoped;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/hello")
@ApplicationScoped
public class quarkusapp {

    @GET
    public String sayHello() {
        return "hello";
    }

    public static void main(String[] args) {
        Quarkus.run(args);
    }
}

RESTエンドポイントでQuarkusを起動し、「/hello」上のリクエストに「hello」を返すメインメソッドを持つ非常にシンプルなクラスです。

なぜそこに main メソッドがあるのか?

A main method is currently needed for the JBang integration to work - we might remove this requirement in the future.

アプリケーションの実行

これでアプリケーションを実行すると、Quarkusが起動するのがわかります。

使用方法: jbang quarkusapp.java

$ jbang quarkusapp.java

[jbang] Building jar...
[jbang] Post build with io.quarkus.launcher.JBangIntegration
Aug 30, 2020 5:49:01 AM org.jboss.threads.Version <clinit>
INFO: JBoss Threads version 3.1.1.Final
Aug 30, 2020 5:49:02 AM io.quarkus.deployment.QuarkusAugmentor run
INFO: Quarkus augmentation completed in 681ms
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2020-08-30 05:49:03,255 INFO  [io.quarkus] (main) Quarkus 2.11.1.Final on JVM started in 0.638s. Listening on: http://0.0.0.0:8080
2020-08-30 05:49:03,272 INFO  [io.quarkus] (main) Profile prod activated.
2020-08-30 05:49:03,272 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy-reactive]

起動したら、提供されたエンドポイントにリクエストすることができます。

$ curl -w "\n" http://localhost:8080/hello
hello

その後、 CTRL+C を叩いてアプリケーションを停止させます。

curl -w "\n" で自動的に改行を追加します。

例では、 curl -w "\n" を使用して、結果と次のコマンドプロンプトが同じ行に表示されるのを防止しています。

quarkus-resteasy-reactive が解決されないのはなぜですか?

In this second run you should not see a line saying it is resolving quarkus-resteasy-reactive as JBang caches the dependency resolution between runs. If you want to clear the caches to force resolution use jbang cache clear.

インジェクションの使用

Quarkusの依存性インジェクションは、Quarkusのアーキテクチャに合わせて調整されたCDIベースの依存性インジェクションソリューションであるArCをベースにしています。ArCの詳細については、 コンテキストと依存性注入ガイド を参照してください。

ArCは quarkus-resteasy の依存関係として提供されているので、すでに追加済です。

アプリケーションを修正してコンパニオンBeanを追加してみましょう。

通常は別のクラスを追加しますが、一つのファイルにまとめようとしているので、入れ子クラスを追加します。

quarkusapp クラスのボディ 内に 以下を追加します。

@ApplicationScoped
static public class GreetingService {

    public String greeting(String name) {
        return "hello " + name;
    }

}
ネストされた静的パブリッククラスの使用

トップレベルのクラスではなく、ネストされた静的パブリッククラスを使用しているのには、2つの理由があります。

  1. JBang currently does not support multiple source files.

  2. イントロスペクションに依存するすべてのJavaフレームワークは、トップレベルのクラスを使用することに課題があります。

quarksapp クラスを編集して GreetingService を注入し、それを使って新しいエンドポイントを作成します。

//usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS io.quarkus:quarkus-resteasy-reactive:2.11.1.Final

import io.quarkus.runtime.Quarkus;
import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/hello")
@ApplicationScoped
public class quarkusapp {

    @GET
    public String sayHello() {
        return "hello from Quarkus with jbang.dev";
    }

    public static void main(String[] args) {
        Quarkus.run(args);
    }

    @Inject
    GreetingService service;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("/greeting/{name}")
    public String greeting(String name) {
        return service.greeting(name);
    }

    @ApplicationScoped
    static public class GreetingService {

        public String greeting(String name) {
            return "hello " + name;
        }
    }
}

これで、 jbang quarkusapp.java を実行すると、新しいエンドポイントが何を返すかを確認することができます。

$ curl -w "\n" http://localhost:8080/hello/greeting/quarkus
hello null

さて、予想に反して、なぜそれは hello quarkus ではなく hello null を返しているのでしょうか?

The reason is that RESTEasy Reactive relies on the -parameters compiler flag to be set to be able to map {name} to the name parameter.

ファイルに以下のコメント命令を追加することで修正しています。

//JAVAC_OPTIONS -parameters

これで、 jbang quarkusapp.java で実行すると、エンドポイントは期待通りの値を返すようになりました。

$ curl -w "\n" http://localhost:8080/hello/greeting/quarkus
hello quarkus

デバッグ

jbang --debug=5005 quarkusapp.java アプリケーションのデバッグには jbang --debug quarkusapp.java を使用し、IDEを使用してポート4004で接続することができます。

Note: JBang debugging always suspends thus you need to connect the debugger to have the application run.

ロギング

jbangによるQuarkusスクリプトでロギングを使用するには、通常通りロガーを設定します。

public static final Logger LOG = Logger.getLogger(quarkusapp.class);

これを動作させるには、ロギングが適切に初期化されるように Java オプションを追加する必要があります。

//JAVA_OPTIONS -Djava.util.logging.manager=org.jboss.logmanager.LogManager

これで jbang quarkusapp.java を実行すると、期待通りにログが記録され、レンダリングされます。

アプリケーションの設定

//Q:CONFIG <property>=<value> を使用して、アプリケーションの静的設定を設定することができます。

例えば、 smallrye-openapiswagger-ui のエクステンションを追加して Swagger UI を常に表示させたい場合は、以下のように追加します。

//DEPS io.quarkus:quarkus-smallrye-openapi:2.11.1.Final
//DEPS io.quarkus:quarkus-swagger-ui:2.11.1.Final
//Q:CONFIG quarkus.swagger-ui.always-include=true

これでビルド中に quarkus.swagger-ui.always-include が生成され、結果の jar と実行時に http://0.0.0.0:8080/q/swagger-ui が利用可能になります。

ネイティブアプリケーションとしての実行

native-image バイナリーがインストールされていて GRAALVM_HOME が設定されている場合は、 jbang --native quarkusapp.java を使用してネイティブ実行可能ファイルをビルドして実行することができます。

$ jbang --native quarkusapp.java

[jbang] Building jar...
[jbang] Post build with io.quarkus.launcher.JBangIntegration
Aug 30, 2020 6:21:15 AM org.jboss.threads.Version <clinit>
INFO: JBoss Threads version 3.1.1.Final
Aug 30, 2020 6:21:16 AM io.quarkus.deployment.pkg.steps.JarResultBuildStep buildNativeImageThinJar
INFO: Building native image source jar: /var/folders/yb/sytszfld4sg8vwr1h0w20jlw0000gn/T/quarkus-jbang3291688251685023074/quarkus-application-native-image-source-jar/quarkus-application-runner.jar
Aug 30, 2020 6:21:16 AM io.quarkus.deployment.pkg.steps.NativeImageBuildStep build
INFO: Building native image from /var/folders/yb/sytszfld4sg8vwr1h0w20jlw0000gn/T/quarkus-jbang3291688251685023074/quarkus-application-native-image-source-jar/quarkus-application-runner.jar
Aug 30, 2020 6:21:16 AM io.quarkus.deployment.pkg.steps.NativeImageBuildStep checkGraalVMVersion
INFO: Running Quarkus native-image plugin on GraalVM Version 20.1.0 (Java Version 11.0.7)
Aug 30, 2020 6:21:16 AM io.quarkus.deployment.pkg.steps.NativeImageBuildStep build
INFO: /Users/max/.sdkman/candidates/java/20.1.0.r11-grl/bin/native-image -J-Djava.util.logging.manager=org.jboss.logmanager.LogManager -J-Dsun.nio.ch.maxUpdateArraySize=100 -J-Dvertx.logger-delegate-factory-class-name=io.quarkus.vertx.core.runtime.VertxLogDelegateFactory -J-Dvertx.disableDnsResolver=true -J-Dio.netty.leakDetection.level=DISABLED -J-Dio.netty.allocator.maxOrder=1 -J-Duser.language=en -J-Dfile.encoding=UTF-8 --initialize-at-build-time= -H:InitialCollectionPolicy=com.oracle.svm.core.genscavenge.CollectionPolicy\$BySpaceAndTime -H:+JNI -jar quarkus-application-runner.jar -H:FallbackThreshold=0 -H:+ReportExceptionStackTraces -H:-AddAllCharsets -H:EnableURLProtocols=http --no-server -H:-UseServiceLoaderFeature -H:+StackTrace quarkus-application-runner

Aug 30, 2020 6:22:31 AM io.quarkus.deployment.QuarkusAugmentor run
INFO: Quarkus augmentation completed in 76010ms
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2020-08-30 06:22:32,012 INFO  [io.quarkus] (main) Quarkus 2.11.1.Final native started in 0.017s. Listening on: http://0.0.0.0:8080
2020-08-30 06:22:32,013 INFO  [io.quarkus] (main) Profile prod activated.
2020-08-30 06:22:32,013 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy-reactive]

This native build will take some time on first run but any subsequent runs (without changing quarkusapp.java) will be close to instant thanks to JBang cache:

$ jbang --native quarkusapp.java
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2020-08-30 06:23:36,846 INFO  [io.quarkus] (main) Quarkus 2.11.1.Final native started in 0.015s. Listening on: http://0.0.0.0:8080
2020-08-30 06:23:36,846 INFO  [io.quarkus] (main) Profile prod activated.
2020-08-30 06:23:36,846 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy-reactive]

まとめ

If you want to get started with Quarkus or write something quickly, Quarkus Scripting with jbang lets you do that. No Maven, no Gradle - just a Java file. In this guide we outlined the very basics on using Quarkus with JBang; if you want to learn more about what JBang can do, go see https://jbang.dev.