Java アダプター

概説

Java アダプターは、JAX-RS 2.0 仕様に基づいています。 言い換えれば、Java アダプターは、MobileFirst Server インスタンスに容易にデプロイでき、MobileFirst Server API およびその他のサード・パーティー API にアクセスできる JAX-RS 2.0 サービスです。

前提条件: 最初に必ず、Java アダプターおよび JavaScript アダプターの作成チュートリアルをお読みください。

ジャンプ先

• ファイル構造
• JAX-RS 2.0 アプリケーション・クラス
• JAX-RS 2.0 リソースの実装
• HTTP セッション
• サーバー・サイド API

ファイル構造

adapter-resources フォルダー

adapter-resources フォルダーには、XML 構成ファイル (adapter.xml) が含まれています。 この構成ファイルで、このアダプター用の JAX-RS 2.0 アプリケーションのクラス名を構成します。 例: com.sample.JavaAdapterApplication。

<?xml version="1.0" encoding="UTF-8"?>
<mfp:adapter name="JavaAdapter"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:mfp="http://www.ibm.com/mfp/integration"
	xmlns:http="http://www.ibm.com/mfp/integration/http">

	<displayName>JavaAdapter</displayName>
	<description>JavaAdapter</description>

	<JAXRSApplicationClass>com.sample.JavaAdapterApplication</JAXRSApplicationClass>

	<property name="DB_url" displayName="Database URL" defaultValue="jdbc:mysql://127.0.0.1:3306/mobilefirst_training"  />
	<property name="DB_username" displayName="Database username" defaultValue="mobilefirst"  />
	<property name="DB_password" displayName="Database password" defaultValue="mobilefirst"  />

	<securityCheckDefinition name="sample" class="com.sample.sampleSecurityCheck">
    	<property name="maxAttempts" defaultValue="3"/>
	</securityCheckDefinition>
</mfp:adapter>

カスタム・プロパティー

adapter.xml ファイルには、ユーザー定義のカスタム・プロパティーを含めることもできます。 開発者がアダプターの作成中にそれらのプロパティーに割り当てた値は、アダプターを再デプロイせずに、MobileFirst Operations Console → 「[ご使用のアダプター]」→ 「構成」タブでオーバーライドすることができます。 ユーザー定義プロパティーは、ConfigurationAPI インターフェースを使用して読み取り、実行時にさらにカスタマイズできます。

注: 構成プロパティー・エレメントは、JAXRSApplicationClass エレメントの下に配置する必要があります。
上の例では、デフォルト値を指定して接続設定を定義し、これらの接続設定を後で AdapterApplication クラスで使用できるようにしてあります。

<property> エレメントには以下の属性があります。

• name: 構成クラスで定義されている、プロパティーの名前。
• defaultValue: 構成クラスで定義されたデフォルト値をオーバーライドします。
• displayName: オプション。コンソールに表示される分かりやすい名前。
• description: オプション。コンソールに表示される説明。
• type: オプション。プロパティーが確実に、特定タイプ (integer、string、boolean など) または有効な値のリスト (例えば type="['1','2','3']") になるようにします。

構成のプルとプッシュ

カスタマイズしたアダプター・プロパティーは、「構成ファイル」タブに表示されるアダプター構成ファイルを使用して共有できます。
共有するためには、Maven または MobileFirst CLI を使用して、以下で説明する pull コマンドと push コマンドを使用します。 共有するプロパティーについては、そのプロパティーに対して指定されたデフォルト値を変更する 必要があります。

アダプター Maven プロジェクトのルート・フォルダーから以下のコマンドを実行します。

Maven

• 構成ファイルをプルする場合

  mvn adapter:configpull -DmfpfConfigFile=config.json
  

• 構成ファイルをプッシュする場合

  mvn adapter:configpush -DmfpfConfigFile=config.json
  

MobileFirst CLI

• 構成ファイルをプルする場合

  mfpdev adapter pull
  

• 構成ファイルをプッシュする場合

  mfpdev adapter push
  

複数のサーバーへの構成のプッシュ

pull コマンドと push コマンドは、使用している環境 (DEV、QA、UAT、PRODUCTION) に応じてアダプターで異なる値が必要となる各種の DevOps フローを作成する場合に役立ちます。

Maven
上記の説明で、デフォルトでの config.json ファイルの指定方法を確認してください。 異なるターゲットを処理するには、異なる名前のファイルを作成します。

MobileFirst CLI
デフォルトとは異なる構成ファイルを指定するには、–configFile フラグまたは -c フラグを使用します。

mfpdev adapter pull -c [adapterProject]/alternate_config.json

mfpdev help adapter pull/push を使用して、詳細を参照してください。

java フォルダー

JAX-RS 2.0 サービスの Java ソースは、このフォルダーに入っています。 JAX-RS 2.0 サービスは、アプリケーション・クラス (これで com.ibm.mfp.adapter.api.MFPJAXRSApplication を拡張します) とリソース・クラスで構成されます。

JAX-RS 2.0 のアプリケーション・クラスおよびリソース・クラスは、Java メソッドおよび URL に対するそれらのメソッドのマッピングを定義します。
com.sample.JavaAdapterApplication が JAX-RS 2.0 アプリケーション・クラスで、com.sample.JavaAdapterResource がアプリケーション内に含まれる JAX-RS 2.0 リソースです。

JAX-RS 2.0 アプリケーション・クラス

JAX-RS 2.0 アプリケーション・クラスは、そのアプリケーションに含まれるリソースを JAX-RS 2.0 フレームワークに通知します。

package com.sample.adapter;

import java.util.logging.Logger;
import com.ibm.mfp.adapter.api.MFPJAXRSApplication;

public class JavaAdapterApplication extends MFPJAXRSApplication{

    static Logger logger = Logger.getLogger(JavaAdapterApplication.class.getName());

    @Override
    protected void init() throws Exception {
        logger.info("Adapter initialized!");
    }

    @Override
    protected String getPackageToScan() {
        //The package of this class will be scanned (recursively) to find JAX-RS 2.0 resources.
        return getClass().getPackage().getName();
    }
}

MFPJAXRSApplication クラスは、パッケージをスキャンして JAX-RS 2.0 リソースを見つけ、自動的にリストを作成します。 さらに、アダプターがデプロイされるとすぐ (サービスを開始する前) に、Mobile Foundation ランタイムの開始時に、MobileFirst Server によってこのクラスの init メソッドが呼び出されます。

JAX-RS 2.0 リソースの実装

JAX-RS 2.0 リソースは、ルート URL にマップされる POJO (Plain Old Java Object) です。このリソースには、このルート URL とその子 URL への要求にサービスを提供する Java メソッドが含まれています。 どのリソースも、別々の URL セットを持つことができます。

package com.sample.adapter;

import java.util.logging.Logger;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

@Path("/")
public class JavaAdapterResource {

    //Define logger (Standard java.util.Logger)
    static Logger logger = Logger.getLogger(JavaAdapterResource.class.getName());

    //Path for method: "<server address>/Adapters/adapters/JavaAdapter/{username}"
    @GET
    @Path("/{username}")
    public String helloUser(@PathParam("username") String name){
        return "Hello " + name;
    }
}

• クラス定義の前の @Path("/") は、このリソースのルート・パスを判別します。 複数のリソース・クラスがある場合は、各リソースに異なるパスを設定する必要があります。

  例えば、ブログのユーザーを管理するために @Path("/users") が指定された UserResource がある場合、そのリソースには http(s)://host:port/ProjectName/adapters/AdapterName/users/ を介してアクセスできます。

  同じアダプターに、ブログの投稿を管理するための、@Path("/posts") が指定された別のリソース PostResource を含めることもできます。 これには、http(s)://host:port/ProjectName/adapters/AdapterName/posts/ という URL を介してアクセスできます。

  上の例ではリソース・クラスは 1 つのみであるため、http(s)://host:port/Adapters/adapters/JavaAdapter/ を介してアクセスできるように、@Path("/") に設定されます。

• 各メソッドの前には 1 つ以上の JAX-RS 2.0 アノテーション (例えば、@GET、@PUT、@POST、@DELETE、または@HEAD などの「HTTP 要求」タイプのアノテーション) を指定します。 これらのアノテーションは、そのメソッドにアクセス可能な方法を定義します。

• もう 1 つの例 @Path("/{username}") は、(リソース・レベルのパスに加えて) このプロシージャーにアクセスするためのパスを定義しています。 見ると分かるとおり、このパスには変数部分が含まれています。 この変数は、後で、@PathParam("username") String name のように定義して、メソッドのパラメーターとして使用されます。

その他のさまざまなアノテーションを使用できます。 以下で、『Annotation Types Summary』 を参照してください。 https://jax-rs-spec.java.net/nonav/2.0-rev-a/apidocs/javax/ws/rs/package-summary.html

重要: アダプター実装内で javax.ws.rs.* または javax.servlet.* からクラスへの静的参照を使用する場合、以下のいずれかのオプションを使用して必ず RuntimeDelegate を構成する必要があります。

• Liberty jvm.options で -Djavax.ws.rs.ext.RuntimeDelegate=org.apache.cxf.jaxrs.impl.RuntimeDelegateImpl を設定します または
• システム・プロパティーまたは JVM カスタム・プロパティー javax.ws.rs.ext.RuntimeDelegate=org.apache.cxf.jaxrs.impl.RuntimeDelegateImpl を設定します

HTTP セッション

MobileFirst Server は HTTP セッションに依存しないため、各要求が異なるノードに到達する可能性があります。 データをある要求から次の要求へと保持するためには、HTTP セッションに依存しないようにする必要があります。

サーバー・サイド API

Java アダプターは、サーバー・サイド Java API を使用して、MobileFirst Serverに関連する操作 (他のアダプターの呼び出し、サーバー・ログへの記録、構成プロパティーの値の取得、Analytics へのアクティビティーの報告、要求の発行者の ID の取得など) を実行できます。

構成 API

ConfigurationAPI クラスは、adapter.xml または MobileFirst Operations Console で定義されているプロパティーを取得するための API を提供します。

Java クラス内に、クラス・レベルで以下を追加します。

@Context
ConfigurationAPI configurationAPI;

その後、configurationAPI インスタンスを使用してプロパティーを取得できます。

configurationAPI.getPropertyValue("DB_url");

アダプター構成が MobileFirst Operations Console から変更されると、JAX-RS アプリケーション・クラスが再ロードされ、その init メソッドが再び呼び出されます。

getServerJNDIProperty メソッドを使用して、サーバー構成の JNDI プロパティーを取得することも可能です。

Java SQL アダプターチュートリアルで使用例を参照できます。

アダプター API

AdaptersAPI クラスは、現行アダプターに関する情報を取得し、他のアダプターに REST 要求を送信するための API を提供します。

Java クラス内に、クラス・レベルで以下を追加します。

@Context
AdaptersAPI adaptersAPI;

拡張アダプターの使用法とマッシュアップチュートリアルで使用例を参照できます。

Analytics API

AnalyticsAPI クラスは、Analytics に情報を報告するための API を提供します。

Java クラス内に、クラス・レベルで以下を追加します。

@Context
AnalyticsAPI analyticsAPI;

Analytics API チュートリアルで使用例を参照できます。

セキュリティー API

AdapterSecurityContext クラスは、アダプター REST 呼び出しのセキュリティー・コンテキストを提供します。

Java クラス内に、クラス・レベルで以下を追加します。

@Context
AdapterSecurityContext securityContext;

その後、例えば、以下を使用して現行の AuthenticatedUser を取得することができます。

AuthenticatedUser currentUser = securityContext.getAuthenticatedUser();

Java アダプターの例

HTTP または SQL のバックエンドと通信する Java アダプターの例については、以下を参照してください。

• Java HTTP アダプター
• Java SQL アダプター