• 1.概要
• 2. ドキュメント規約
• 3. インスタンスの起動
  • 3.1 コマンドラインからのインスタンスの起動
  • 3.2 プログラムからのインスタンスの起動
• 4. アプリケーションのデプロイ
  • 4.1 コマンドラインからのアプリケーションのデプロイ
    • 4.1.1 コマンドラインからの複数アプリケーションのデプロイ
  • 4.2 プログラムからのアプリケーションのデプロイ
    • 4.2.1 プログラムからのアプリケーションのデプロイ
• 5. インスタンスの構成
  • 5.1 コマンドラインからのインスタンスの構成
  • 5.2 プログラムからのインスタンスの構成
• 6. インスタンスの停止
  • 6.1 コマンドラインからのインスタンスの停止
  • 6.2 プログラムからのインスタンスの停止
• 7. Payara Micro の自動クラスタリング
• 8. 付録
  • 8.1 Payara Micro のコマンドライン・オプション
  • 8.2 Payara Micro API
    • 8.2.1 構成メソッド
    • 8.2.2 操作メソッド
      • 8.2.2.1 デプロイメソッド
      • 8.2.2.2 起動・停止メソッド

このページでは Payara Micro 4.1.152 の使い方について説明します。

Payara Micro は Payara の埋め込み Web サーバーからビルドした新しい埋め込みリリースです。Payara Micro は WAR ファイルのデプロイと実行を単一のコマンドで実行し、Hazelcast による動的なクラスタ構成をも自動的に提供します。

例示する各コマンドは、Payara Micro の JAR ファイルが同一ディレクトリで動作することを前提とします。

例示する各コマンドはまた、環境変数に Java のシステムパスが設定されていることも前提とします。

このドキュメントで示すパスはすべて、Unix/Linux ファイル・パス構造 (スラッシュ前置) で表現します。

このセクションではインスタンスを起動する最も基本的な事柄について説明します。

Payara Micro のインスタンスをコマンドラインから起動する場合には、単純に以下のように JAR を実行します:

java -jar payara-micro.jar

この単一のコマンドは Payara Micro のインスタンスを起動するのに必ず必要です。その他の構成オプションはいずれもこのコマンドの一部に過ぎません。

コードには fish.payara.micro パッケージの 2 つのクラスをインポートする必要があります (これらは Payara Micro の JAR に含まれます):

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

インスタンスを起動するには getInstance() および bootstrap() メソッドを PayaraMicro class から呼び出す必要があります。 この初期化処理は BootstrapException 例外をスローするため、try-catch 節で囲むか、呼び出し元に処理を委ねる必要があります。

簡単な例を以下に示します:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{ 
    public static void main(String[] args) throws BootstrapException
    {   
        PayaraMicro.getInstance().bootStrap();
    }    
}

このセクションではアプリケーションをデプロイする方法について説明します。

セクション 3.1 に記したように、すべてのコマンドに対する Payara Micro の動作は一回の Payara Micro JAR 呼び出しによって実行されます。例えば Payara Micro のインスタンスをコマンドで起動し、後からアプリケーションをデプロイするようなことはできないようになっています。

インスタンスにおける起動、構成、アプリケーションのデプロイに関する一般的な構成は以下の通りとなります:

java -jar payara-micro.jar _--option1_ _--option2_ ...

WAR ファイルをインスタンスにデプロイする場合、--deploy オプションを使用する必要があります。このオプションの値にはデプロイするアプリケーションのパスを指定します。 Payara Micro インスタンスの起動と WAR ファイルのデプロイの例を以下に示します:

java -jar payara-micro.jar --deploy /home/user/example.war

もし複数のアプリケーションをデプロイする必要がある場合には、--deploy オプションをデプロイするアプリケーションごとに複数回使用します。--deploy オプションでは複数の WAR ファイルのパスを認識できませんので注意してください。

以下に 2 つのアプリケーションをデプロイする例を示します:

java -jar payara-micro.jar --deploy /home/user/example.war --deploy /home/user/test.war

もうひとつの方法として、--deploymentDir オプションを指定することもできます。このオプションは指定されてディレクトリ内にあるすべてのアプリケーションをデプロイ対象とします。

java -jar payara-micro.jar --deploymentDir /home/user/deployments

コードからアプリケーションをデプロイするには 2 種類のメソッドがあります: addDeployment(String pathToWar) と addDeploymentFile(File file) がそれです。 まず、 addDeployment(String pathToWar) ですが、デプロイ対象のファイルのパスを文字列で受け取ります。以下に例を示します:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro.getInstance().addDeployment("/home/user/example.war").bootStrap();
    }
}

2 つ目のメソッドである addDeploymentFile(File file) は、機能的には addDeployment(String pathToWar) メソッドと同等です。ただし、引数として File オブジェクトを取る点が異なります:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;
import java.io.File;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        File file = new File("/home/user/example.war");
        PayaraMicro.getInstance().addDeploymentFile(file).bootStrap();
    }
}

Payara Micro をコマンドラインからコントロールする場合と異なり、初期化や構成を複数行のメソッドに分けて実行することが可能です。例えば、1 行目でアプリケーションをデプロイして、その後インスタンスを別の行で起動することができます。

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro micro = PayaraMicro.getInstance();
        micro.addDeployment("/home/user/example.war");
        micro.bootStrap();
    }
}

一度 Payara Micro のインスタンスを起動 (bootstrap() メソッドを呼び出した) した後は、インスタンスの構成などは一切変更できないことに注意してください。

コマンドライン上での操作とよく似ています。アプリケーションのデプロイには addDeployment または addDeploymentFile メソッドを使用する必要があります。

例として、3 つのアプリケーションをデプロイする例を挙げます:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro micro = PayaraMicro.getInstance();
        
        micro.addDeployment("/home/user/example.war");
        micro.addDeployment("/home/user/test.war");
        micro.addDeployment("/home/user/three.war");
        
        micro.bootStrap();
    }
}

代わりに --deploymentDir コマンドライン・オプション (詳細は セクション 4.1.1) に相当する setDeploymentDir(File deploymentRoot) メソッドが使用できます:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;
import java.io.File;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        File deployments = new File("/home/user/deployments/");
        PayaraMicro micro = PayaraMicro.getInstance();
        micro.setDeploymentDir(deployments);
        micro.bootStrap();
    }
}

このセクションでは Payara Micro インスタンスの構成方法に付いてみてゆきます。

利用可能なオプションについては、JAR を --help オプション付きで実行することで参照することが可能です。あるいは、付録 の Payara Micro Command Line Options にも情報があります。

インスタンスに対する一般的な起動、構成、アプリケーションのデプロイについては以下のようになります:

java -jar payara-micro.jar _--option1_ _--option2_ ...

以下の例では、デフォルト以外の HTTP ポートでインスタンスを起動しています:

java -jar payara-micro.jar --port 2468

Payara Micro インスタンスをプログラムから構成する場合には様々なメソッドを利用することが可能です。

利用可能な構成メソッドは IDE によって見つけられるはずで、主な IDE が搭載しているオート・コンプリート機能を使用することでそれらを見ることができるでしょう。その他の方法としては 付録 セクションの 構成メソッド で調べることもできます。

4.2 プログラムからのアプリケーションのデプロイ セクションでも注記したように、 you can either call the desired configuration commands on one line during instance initialisation, or on separate lines after creating a PayaraMicro variable.

同じセクションでこちらも追記しましたが: インスタンスの構成は一旦 Payara Micro を起動したら (Bootstrap が呼び出されたら) 変更することができません。

ここで、異なる HTTP とクラスタ・ポートをワンライナーで指定した例を以下に示します:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro.getInstance().setHttpPort(2468).setClusterStartPort(5902).bootStrap();
    }
}

同じ例ですが、複数行に分けたものを以下に示します:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro micro = PayaraMicro.getInstance();
        micro.setHttpPort(2468);
        micro.setClusterStartPort(5902);
        micro.bootStrap();
    }
}

このセクションでは、Payara Micro インスタンスをシャットダウンする方法について説明します。

Payara Micro のインスタンスをシャットダウンするには特別なオプションは不要です。 Payara Micro のインスタンスをシャットダウンする唯一の方法は、稼働中の Payara Micro の Process ID を調べて、それに対して kill シグナルを送信することです。

訳注: Payara Micro はシャットダウン・フックを実装しており、そこで自身のシャットダウン処理を実行するようになっています。

プログラム上から Payara Micro のインスタンスをシャットダウンする場合、PayaraMicro クラスの shutdown() メソッドを呼び出します。 You must call this method specifically on the instance of Payara Micro that you want to shut down, so will realistically only be used on a PayaraMicro instance variable: Payara Micro のインスタンスに対してこのメソッドをしなければならない場合、PayaraMicro のインスタンス変数を保持しておく必要があります。

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro micro = PayaraMicro.getInstance();
        micro.bootStrap();
        
        micro.shutdown();
    }
}

このセクションでは、Payara Micro の自動クラスタリングの働きについて説明します。

Payara Micro の Hazelcast 連携は自動的かつ動的に有効となっており、互いにクラスタを構成することができるようになっています。例えば、2 つのインスタンスが同じマルチキャストアドレスとポートを参照していた場合、これらは自動的にクラスタを構成します。

2 つのインスタンスが自動的にクラスタリングを行ったことを確かめるのは容易で (異なる HTTP ポートが構成されているものとします)、以下のログ出力を確認すれば良いのです。

Members [2] {
        Member [192.168.174.130]:5900 this
        Member [192.168.174.130]:5901

--startPort オプションは Payara Micro インスタンスがポートを決定する際最初にバインドを試みるポートで、もしこのポートが既に使用されていたら (他の Payara Micro インスタンスなどによって)、Payara Micro インスタンスはバインドに成功するまで単純に startPort をインクリメントします。

例えば、2 つの Payara Micro インスタンスがポート 5900 および 5901 で動作しているとして、3 番目のインスタンスを起動する際には startPort (5900) から開始して最初に 5900、次に 5901 へのバインドを試み (ともに失敗する)、最終的に 5902 にバインドされます。

もし、複数のクラスタを構築する場合には、--mcAddress および mcPort オプションに異なるマルチキャスト・アドレスとポートを定義する必要があります。異なるクラスタに属するインスタンスには異なるアドレスとポートを割り当てることになります。異なるクラスタについては新しいマルチキャスト・アドレスとポートをもとに新しいクラスタが自動的に構築されます。

このセクションには Payara Micro API に関するドキュメントが含まれます。

このセクションでは Payara Micro API のインスタンス構成メソッドについて解説します。

このセクションでは Payara Micro インスタンスを操作するその他の Payara Micro API のメソッドについて解説します。

このセクションでは Payara Micro インスタンスにアプリケーションをデプロイするためのメソッドについて解説します。

このセクションでは Payara Micro インスタンスの設定メソッドについて解説します。