Skip to content

Payara Micro (Payara 4.1.152.1)

Jump to bottom Edit New page
HASUNUMA Kenji edited this page Aug 3, 2015 · 5 revisions

目次

1. 概要

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

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

2. ドキュメント規約

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

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

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

3. インスタンスの起動

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

3.1 コマンドラインからのインスタンスの起動

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

java -jar payara-micro.jar

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

3.2 プログラムからのインスタンスの起動

コードには 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.getInstance().bootStrap();
    }    
}

4. アプリケーションのデプロイ

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

4.1 コマンドラインからのアプリケーションのデプロイ

セクション 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

4.1.1 コマンドラインからの複数アプリケーションのデプロイ

もし複数のアプリケーションをデプロイする必要がある場合には、--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

4.2 プログラムからのアプリケーションのデプロイ

コードからアプリケーションをデプロイするには 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() メソッドを呼び出した) した後は、インスタンスの構成などは一切変更できないことに注意してください。

4.2.1 プログラムからのアプリケーションのデプロイ

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

5. インスタンスの構成

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

5.1 コマンドラインからのインスタンスの構成

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

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

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

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

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

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

5.2 プログラムからのインスタンスの構成

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

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

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

同じセクションでこちらも追記しましたが、インスタンスの構成は一旦 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();
    }
}

6. インスタンスの停止

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

6.1 コマンドラインからのインスタンスの停止

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

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

6.2 プログラムからのインスタンスの停止

プログラムから 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();
    }
}

7. Payara Micro の自動クラスタリング

このセクションでは、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 オプションに異なるマルチキャスト・アドレスとポートを定義する必要があります。異なるクラスタに属するインスタンスには異なるアドレスとポートを割り当てることになります。異なるクラスタについては新しいマルチキャスト・アドレスとポートをもとに新しいクラスタが自動的に構築されます。

8. Payara Micro and Maven

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

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

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

9. 付録

9.1 Payara Micro のコマンドライン・オプション

構成オプション 説明 既定値
--noCluster このインスタンスでクラスタリングを無効にする。 false
--port このインスタンスがバインドする HTTP ポート を指定する。 8080
--sslPort このインスタンスがバインドする HTTPS ポート を指定する。 設定されない場合、HTTPS は無効。
--mcAddress このインスタンスが属する Hazelcast クラスタのマルチキャスト・グループを指定する 224.2.2.4
--mcPort クラスタのマルチキャスト・ポートを指定する。 2904
--startPort クラスタのリスン開始ポート番号を指定する。 5900
--name インスタンス名を指定する。 生成された UUID。
--rootDir 構成ディレクトリのルートを指定する。再起動時に構成情報を保存する。 設定されない場合は値が設定されず、一時ディレクトリが使用される。
--deploymentDir Sets a directory which will be scanned for WAR files for auto-deployment. 設定されない場合は値が設定されず、使用されることもない。
--deploy デプロイする WAR ファイル (パス文字列) を指定する。 設定されない場合は値が設定されず、使用されることもない。
--domainConfig 代替の domain.xml ファイルでサーバー構成を上書きする。 設定されない場合は Payara Micro に含まれる domain.xml が使用される。
--minHttpThreads HTTP スレッド・プールのスレッド最小値を設定する。 10
--maxHttpThreads HTTP スレッド・プールのスレッド最大値を設定する。 10
--help 構成オプションを表示する。 設定されない場合はこのオプションは使用されない (訳注: ヘルプは表示されない)

9.2 Payara Micro API

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

9.2.1 構成メソッド

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

構成オペランド 説明 取得メソッド 設定メソッド 既定値 対応するコマンドライン
Alternate Domain XML 既定のサーバー構成をオーバーライドする domain.xml を取得または設定する。 File getAlternateDomainXML() PayaraMicro setAlternateDomainXML(File alternateDomainXML) null --domainConfig
Cluster Multicast Group このインスタンスが属するクラスタのマルチキャスト・グループを取得または設定する。 String getClusterMulticastGroup() Payara Micro setClusterMulticastGroup(String hzMulticastGroup) null (インスタンスから既定の domain.xml の値を読み出せない場合は既定値 224.2.2.4 が設定される) --mcAddress
Cluster Port クラスタのマルチキャスト・ポートを取得または設定する。 int getClusterPort() Payara Micro setClusterPort(int hzPort) -2147483648 (MIN_VALUE) (インスタンスから既定の domain.xml の値を読み出せない場合は既定値 2904 が設定される) --mcPort
Cluster Start Port Payara Micro インスタンスがクラスタ接続を開始するときのポート番号を取得または設定する。 int getClusterStartPort() Payara Micro setClusterStartPort(int hzStartPort) -2147483648 (MIN_VALUE) (インスタンスから読み出せない場合は既定値の 5900 が設定される) --startPort
Deployment Directory デプロイするアーカイブをスキャンするディレクトリを取得または設定する。 File getDeploymentDir() Payara Micro setDeploymentDir(File deploymentRoot) null --deploymentDir
HTTP Port インスタンスがバインドする HTTP ポートを取得または設定する。 int getHttpPort() Payara Micro setHttpPort(int httpPort) -2147483648 (MIN_VALUE) (インスタンスから既定の domain.xml の値を読み出せない場合は既定値 8080 が設定される) --port
Instance Name インスタンス名を取得または設定する。 String getInstanceName() PayaraMicro setInstanceName(String instanceName) Generated Universally Unique Identifier. --name
Maximum HTTP Threads HTTP スレッド・プールのスレッド最大値を取得または設定する。 int getMaxHttpThreads() Payara Micro setMaxHttpThreads(int maxHttpThreads) -2147483648 (MIN_VALUE) (インスタンスから既定の domain.xml の値を読み出せない場合は既定値 10 が設定される) --maxHttpThreads
Minimum HTTP Threads HTTP スレッド・プールのスレッド最小値を取得または設定する。 int getMinHttpThreads() Payara Micro setMinHttpThreads(int minHttpThreads) -2147483648 (MIN_VALUE) (インスタンスから既定の domain.xml の値を読み出せない場合は既定値 10 が設定される) --minHttpThreads
Root Directory 構成ディレクトリのルートを取得または設定する。 File getRootDir() Payara Micro setRootDir(File rootDir) null --rootDir
HTTPS Port インスタンスがバインドする HTTPS ポートを取得または設定する。手動で設定しない場合、HTTPS ポートはバインドされない。 int getSslPort() PayaraMicro setSslPort(int sslPort) -2147483648 (MIN_VALUE) (インスタンスから既定の domain.xml の値を読み出せない場合は既定値 8443 が設定される) --sslPort
No Clustering インスタンスが属するクラスタが有効かどうかを取得または設定する。 boolean isNoCluster() PayaraMicro setNoCluster(boolean noCluster) false

9.2.2 操作メソッド

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

9.2.2.1 デプロイメソッド

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

メソッド 説明 既定値 対応するコマンドライン
PayaraMicro addDeployment(String pathToWar) pathToWar パラメータで示されたファイルを見つけ、インスタンス起動時にデプロイするファイルの一覧に追加する。 N/A --deploy
PayaraMicro addDeploymentFile(File file) file パラメータで示されたファイル (複数の場合あり) を見つけ、インスタンス起動時にデプロイするファイルとする。 N/A --deploy

9.2.2.2 起動・停止メソッド

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

メソッド 説明
void bootStrap() throws BootstrapException 設定された構成パラメータをチェックし、Payara Micro インスタンスを起動する。
PayaraMicro getInstance() Payara Micro サーバーのシングルトン・インスタンスを取得する。インスタンスが作成されていない場合には新規作成する。
PayaraMicro getInstance(boolean create) Payara Micro サーバーのシングルトン・インスタンスを取得する。インスタンスが作成されておらず、かつ create が true に設定されていた場合には新規作成し、それ以外は null を返す。
void shutdown() throws BootstrapException Payara Micro インスタンスを停止・シャットダウンする。
Add a custom footer

Home > Documentation > Previous Releases > Payara 4.1.152.1 > Payara Micro

Payara 4.1.152.1
Patch Notes
Hazelcast
JBatch
JCache
Payara Micro

Clone this wiki locally