• 1. 概要
• 2. ドキュメント規約
• 3. インスタンスの起動
  • 3.1 コマンドラインからのインスタンスの起動
  • 3.2 プログラムからのインスタンスの起動
• 4. アプリケーションのデプロイ
  • 4.1 コマンドラインからのアプリケーションのデプロイ
    • 4.1.1 コマンドラインからの複数アプリケーションのデプロイ
  • 4.2 プログラムからのアプリケーションのデプロイ
    • 4.2.1 ブート時のアプリケーションのデプロイ
      • 4.2.1.1 ブート時の複数アプリケーションのデプロイ
    • 4.2.2 ブート済インスタンスへのアプリケーションのデプロイ
      • 4.2.2.1 ブート済インスタンスへのアプリケーションのデプロイ
• 5. インスタンスの構成
  • 5.1 コマンドラインからのインスタンスの構成
  • 5.2 プログラムからのインスタンスの構成
• 6. インスタンスの停止
  • 6.1 コマンドラインからのインスタンスの停止
  • 6.2 プログラムからのインスタンスの停止
• 7. Payara Micro の自動クラスタリング
• 8. Payara Micro と Maven
• 9. Payara Micro の HTTP/HTTPS 自動バインド
• 10. ブート済インスタンス上での asadmin コマンドの実行
• 11. ブート済インスタンス上での Callable オブジェクトの実行
• 12. CDI イベントの実行とリスン
• 13. 付録
  • 13.1 Payara Micro のコマンドライン・オプション
  • 13.2 Payara Micro API
    • 13.2.1 構成メソッド
    • 13.2.2 操作メソッド
      • 13.2.2.1 デプロイメソッド
        • 13.2.2.1.1 PayaraMicro クラスのメソッド
        • 13.2.2.1.2 PayaraMicroRuntime クラスのメソッド
      • 13.2.2.2 起動・停止メソッド
        • 13.2.2.2.1 PayaraMicro クラスのメソッド
        • 13.2.2.2.2 PayaraMicroRuntime クラスのメソッド
      • 13.2.2.3 CDI メソッド
      • 13.2.2.4 実行メソッド
      • 13.2.2.5 取得メソッド

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

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

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

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

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

Payara Micro インスタンスが起動しているかどうか明確でないと、API メソッドを持つクラスははっきりしないでしょう。Payara Micro インスタンスのブート前 (インスタンスがまだ起動していない状態) にこれを操作するメソッドはは Payara Micro クラスに含まれます。 それ以外の、インスタンスのブート後 (インスタンスが起動している) にこれを操作するメソッドは PayaraMicroRuntime クラスに含まれます。

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

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

java -jar payara-micro.jar

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

コードには fish.payara.micro パッケージの 2 つのクラスをインポートする必要があります (これらは Payara Micro の JAR に含まれます。JAR を Maven からインポートする手順については セクション 8 を参照してください):

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.bootStrap();
    }    
}

既定の設定以外 (起動時に設定を変更するかアプリケーションをデプロイする場合) でインスタンスを開始するには、bootstrap() メソッドを使用する前に getInstance() を呼び出す必要があります。これについての詳細は インスタンスの構成 を参照してください。 getInstance() メソッドを使用しても既定の設定が使用できなくなるわけではありません。bootstrap() メソッドの呼び出し (上記の例のような) は bootstrap() メソッドを getInstance() の後に直接呼び出す場合と機能的に等価です。以下に例を示します。

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

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

bootStrap() メソッドは PayaraMicroRuntime オブジェクトのインスタンスを返します。これはブート後にインスタンスとクラスタを制御するための様々なメソッドを提供します。この利点を享受するには、以下に示すように bootStrap メソッドの呼び出し前に PayaraMicroRuntime オブジェクトを初期化しておく必要があります。

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

public class EmbeddedPayara 
{ 
    public static void main(String[] args) throws BootstrapException
    {   
        PayaraMicroRuntime instance = PayaraMicro.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

--deploy の代わりに --deploymentDir オプションを使用することもできます。このオプションはデプロイ可能なアーカイブが格納されているディレクトリを指定し、ディレクトリ内にあるデプロイしたいすべてのアプリケーションをストアした上で、インスタンス起動時にそれらを自動的にデプロイします。

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

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

ブート時にコードからアプリケーションをデプロイするには 2 種類のメソッドがあります: addDeployment(String pathToWar), and 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();
    }
}

コマンドライン上での操作とよく似ています。アプリケーションのデプロイには 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();
    }
}

ブート済インスタンスへアプリケーションをデプロイするには 2 つのメソッド deploy(File war) と deploy(String name, InputStream is) を使用することができます。 最初のメソッドは セクション 4.2.1 で説明した addDeploymentFile と同じ働きをします。

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

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        File war = new File("/home/user/deployments/");
        PayaraMicroRuntime instance = PayaraMicro.bootstrap();
        instance.deploy(war);
    }
}

2 つ目のメソッドでは InputStream から WAR をデプロイすることが可能です。

import fish.payara.micro.PayaraMicro;
import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicroRuntime;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.logging.Level;
import java.util.logging.Logger;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicroRuntime instance = PayaraMicro.bootstrap();
        
        try (InputStream is = new FileInputStream("/home/user/test.war"))
        {        
            instance.deploy("test", is);
        }
        
        catch (IOException ex)
        {
            Logger.getLogger(EmbeddedPayara.class.getName()).log(Level.SEVERE, null, ex);
        }
    }
}

上記 2 つのメソッドの代わりとして、run(Collection<InstanceDescriptor> members, String command, String... args ) メソッドで asadmin の deploy コマンドを実行する方法もあります。単一のインスタンスにデプロイするために、単一のインスタンスのみに含まれる members コレクションを作成する必要があります。 実行コマンドを用いてローカル・インスタンスのみにアプリケーションをデプロイする例を挙げます。

import fish.payara.micro.PayaraMicro;
import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicroRuntime;
import fish.payara.micro.services.data.InstanceDescriptor;
import java.util.ArrayList;
import java.util.Collection;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicroRuntime runtime = PayaraMicro.getInstance().setHttpAutoBind(true).bootstrap();
        
        // Get a Collection with all running instances in the local runtime's cluster
        Collection<InstanceDescriptor> allInstances = runtime.getClusteredPayaras();       
        
        // Create a Collection to use as a subset
        Collection<InstanceDescriptor> subset = new ArrayList<>();
        
        // Loop through all instances
        for (InstanceDescriptor instance : allInstances)
        {
            // Only add the local instance
            if (instance == runtime.getLocalDescriptor())
            {
                subset.add(instance);
                break;
            }
        }

        // Run the deploy asadmin command on the subset Collection
        runtime.run(subset, "deploy", "/home/user/test.war");
    }
}

前のセクション で明記したように、run メソッドを使用することで asadmin コマンドの deploy による単一または複数のクラスタ・インスタンスへのデプロイが可能です。 asadmin コマンドを実行するために run メソッドは 2 種類が用意されています。1 つはクラスタ内のインスタンスのサブセットに対して asadmin コマンドを実行し、もう 1 つはクラスタのすべてのインスタンスに対して asadmin コマンドを実行します。より詳しい説明については 10. ブート済インスタンス上での asadmin コマンドの実行 のセクションを参照してください。

クラスタのすべてのインスタンスにアプリケーションをデプロイする例を以下に示します:

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

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicroRuntime runtime = PayaraMicro.getInstance().setHttpAutoBind(true).bootstrap();

        // Run the deploy asadmin command on all instances in the runtime's cluster
        runtime.run("deploy", "/home/user/test.war");
    }
}

run メソッドを使用してクラスタ内の一部のインスタンスに対して実行する例については 前のセクション を参照してください。

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

セクション 4.1 で示したように、インスタンスの構成と起動は１行で完結しなければなりません。

利用可能なオプションについては、JAR を --help オプション付きで実行するか、あるいは 付録 の Payara Micro のコマンドライン・オプション セクションで調べることができます。

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

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

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

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

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

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

既に ブート時のアプリケーションのデプロイ セクションで注記したように、インスタンスの初期化中に必要な構成コマンドを 1 行で呼び出すか、あるいは PayaraMicro 変数の作成後に行を分割して呼び出すことができます。

ここで、異なる 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 クラスまたは PayaraMicroRuntime クラスの shutdown() メソッドを呼び出します。

Payara Micro インスタンスを明示的にシャットダウンするには PayaraMicro クラスの shutdown() メソッドを呼び出す必要があり、その場合は対象となる 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();
    }
}

PayaraMicroRuntime クラスの shutdown() メソッドは単一の変数に関連付けられています。つまり、同じ方法としてよく使用されます:

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

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicroRuntime instance = PayaraMicro.bootstrap();

        instance.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 は Maven central にアップロードされていますので、POM の依存関係に追加することで使用することが可能です。これは Payara Micro をプログラムから利用する際に必要なクラスとメソッドを簡単に追加できる手段です。

プロジェクトの POM に以下の依存関係を追加してください:

<dependency>
    <groupId>fish.payara.extras</groupId>
    <artifactId>payara-micro</artifactId>
    <version>4.1.153</version>
</dependency>

Payara Micro は HTTP および HTTPS ポートの自動バインディング機能をサポートします。この機能を使用することにより Payara Micro は起動時に必要とされる空きの HTTP または HTTPS ポートを動的に探すことができるようになります。

この機能は 3 つのオプションによって制御されます:

• --autoBindHttp – HTTP ポートに対してオートバインド機能を有効にする
• --autoBindSsl – HTTPS ポートに対してオートバインド機能を有効にする
• --autoBindRange – オートバインド機能で利用する (訳注: ポートの) 範囲を設定する

自動バインドが有効な時、Payara Micro は --port または --sslPort オプションで指定されたポートに対して接続を試みます (これらのオプションが指定されない場合はポート 8080 と 8181 が指定されたものとみなします)。もし、これらのポートがビジーであれば、次のポートへの接続を試み、空きのポートが見つかるか、--autoBindRange で指定したリミットに達するまで処理を繰り返します。

例えば、ポート 8080、8081 および 8181 がビジーで、ポート 8082 および 8182 が空いているとして、Payara Micro を以下のコマンドで起動すると HTTP ポート 8082 および HTTPS ポート 8182 で接続します:

java -jar payara-micro.jar --autoBindHttp --sslPort 8181 --autoBindSsl

一方、同じ状況で以下のコマンドでは失敗します。--autoBindRange が十分な大きさでないためです (8080-8081 の間に空きのポートがありません):

java -jar payara-micro.jar --port 8080 --autoBindHttp --sslPort 8181 --autoBindSsl --autoBindRange 1

自動バインド機能は domain.xml ファイルに記述されたポートの値を読み込まないことに注意してください。もし --port および --sslPort オプションが使用されていないのであれば、--autoBindHttp および --autoBindSsl オプションは HTTP および HTTPS ポートがデフォルトの 8080 と 8181 であるとみなします。

asadmin コマンドを実行するには 2 つのメソッドが用意されており、ともに run というメソッド名となっています。

1 つは run(String command, String... args ) で、実行中のクラスタの全インスタンスで指定した asadmin コマンドを実行します。このメソッドは Map<InstanceDescriptor, Future<ClusterCommandResult>> を返します。詳細は 付録 を参照してください。

もう 1 つは run(Collection<InstanceDescriptor> members, String command, String... args ) で、実行中のクラスタの一部のインスタンスで asadmin コマンドを実行します。このメソッドはもう一方のメソッドと同じ形式の Map を返します。

2 つのメソッドの使用例がそれぞれ 4.2.2 と [4.2.2.1](#4221-deploying-an-application-to multiple-bootstrapped-instances-programmatically) にあります。最初の例は getClusteredPayara() メソッドを用いてクラスタ内で実行中のインスタンスの InstanceDescriptor 識別子のコレクションを作成する 1 つの方法です。

asadmin コマンドを実行するのと同様に、Callable オブジェクトを実行する 2 つのメソッドがあります。いずれの名前も run です。

2 つのメソッドは、2 つの asadmin コマンド実行メソッドの使い方とよく似ています。1 つは run(Callable<T> callable) で、実行中のクラスタの全インスタンスで指定した Callable オブジェクトを実行します。もう 1 つは run(Collection<InstanceDescriptor> members, Callable<T> callable) で、実行中のクラスタのインスタンスの一部で Callable オブジェクトを実行します。 いずれも <InstanceDescriptor, Future<T>> 形式のキー/値 の Map を返します。型変数 T はシリアライズ可能です。

Payara Micro は PayaraMicroRuntime インスタンスのクラスタに渡って CDI イベントの実行とリスンが可能です

CDI イベントと連携するためのメソッドについては 付録 を参照してください。

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

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

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

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

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

このセクションではインスタンス実行中に CDI イベントを起動するメソッドについて解説します。

このセクションではブート済のインスタンスで使用できる asadmin コマンドまたは Callable オブジェクトの実行メソッドについて解説します。

このセクションでは起動中の Payara Micro インスタンスの情報を取得するメソッドについて解説します。ブート前のインスタンスに対する Get メソッドについては、構成メソッドのセクション を参照してください。