JavaScript アダプター

概説

JavaScript アダプターは、HTTP および SQL のバックエンドに接続するためのテンプレートを提供します。 このアダプターは、プロシージャーと呼ばれるサービスのセットを提供します。モバイル・アプリケーションで AJAX 要求を発行することで、これらのプロシージャーを呼び出すことができます。

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

ファイル構造

adapter-resources フォルダー

adapter-resources フォルダーには、XML 構成ファイルが含まれています。 この構成ファイルでは、接続オプションが記述され、アプリケーションまたは他のアダプターに公開されるプロシージャーがリストされています。

<?xml version="1.0" encoding="UTF-8"?>
<mfp:adapter name="JavaScriptAdapter">
    <displayName>JavaScriptAdapter</displayName>
    <description>JavaScriptAdapter</description>

    <connectivity>
        <connectionPolicy>
        ...
        </connectionPolicy>
    </connectivity>

    <procedure name="procedure1"></procedure>
    <procedure name="procedure2"></procedure>

    <property name="name" displayName="username" defaultValue="John"  />
</mfp:adapter>

カスタム・プロパティー

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

注: 構成プロパティー・エレメントは、必ず <procedure> エレメントの下に 配置する必要があります。 上の例では、デフォルト値を使用して <displayName> プロパティーを定義し、このプロパティーを後で使用できるようにしてあります。

<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 を使用して、詳細を参照してください。

js フォルダー

このフォルダーには、adapter.xml ファイルで宣言されているすべてのプロシージャーの JavaScript 実装ファイルが含まれており、JavaScript アダプターには 1 つの JavaScript ファイルしか存在できません。 また、取得した生の XML データの変換スキームを含む、ゼロまたは 1 つ以上の XSL ファイルも含まれています。 アダプターによって取得したデータは、生データとして返すことも、アダプター自体で前処理することもできます。 いずれの場合も、JSON オブジェクトとしてアプリケーションに提示されます。

JavaScript アダプター・プロシージャー

プロシージャーは、XML で宣言され、サーバー・サイド JavaScript を使用して以下の目的で実装されます。

• アダプター関数をアプリケーションに提供する
• データを取得するため、またはアクションを実行するために、バックエンド・サービスを呼び出す

adapter.xml ファイルで宣言される各プロシージャーに対応する関数を JavaScript ファイルで指定する必要があります。

サービスを呼び出す前または後に、サーバー・サイド JavaScript を使用してデータを処理することができます。 簡単な XSLT コードを使用して、取得したデータにさらにフィルタリングを適用することができます。
JavaScript アダプター・プロシージャーは、JavaScript で実装されます。 しかし、アダプターはサーバー・サイド・エンティティーであるため、アダプター・コードで Java を使用することが可能です。

グローバル変数の使用

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

アダプター応答しきい値

アダプター応答は MobileFirst Server メモリーにストリングとして保管されるため、アダプター呼び出しは、大容量データを返すようには設計されていません。 したがって、使用可能メモリー量を超えるデータの場合、メモリー不足例外が発生してアダプター呼び出しが失敗することがあります。 そういった失敗を防止するため、しきい値を構成して、それを超えると MobileFirst Server が HTTP 応答を gzip して返すようにします。 HTTP プロトコルには、gzip 圧縮をサポートするための標準ヘッダーがあります。 クライアント・アプリケーションでも HTTP の gzip コンテンツをサポートできる必要があります。

サーバー・サイド

MobileFirst Operations Console で、「ランタイム」>「設定」>「アダプター応答の GZIP 圧縮しきい値」の下で、適切なしきい値を設定します。 デフォルト値は 20 KB です。
注: MobileFirst Operations Console で変更を保存すると、変更はすぐにランタイムで有効になります。

クライアント・サイド

すべてのクライアント要求で Accept-Encoding ヘッダーの値を gzip に設定することで、クライアントが gzip 応答を構文解析できるようにします。 要求変数を指定した addHeader メソッドを使用します。例えば、次のようにします。request.addHeader("Accept-Encoding","gzip");

サーバー・サイド API

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

getPropertyValue

MFP.Server.getPropertyValue(propertyName) API を使用して、adapter.xml または MobileFirst Operations Console で定義されているプロパティーを取得します。

MFP.Server.getPropertyValue("name");

getTokenIntrospectionData

MFP.Server.getTokenIntrospectionData() API を使用して、以下のことを実行します。

現行のユーザー ID を取得するには、以下を使用します。

function getAuthUserId(){
   var securityContext = MFP.Server.getTokenIntrospectionData();
   var user = securityContext.getAuthenticatedUser();

   return "User ID: " + user.getId;
}

getAdapterName

getAdapterName() API を使用してアダプター名を取得します。

invokeHttp

HTTP アダプターで MFP.Server.invokeHttp(options) API を使用します。
JavaScript HTTP アダプターチュートリアルで使用例を参照できます。

invokeSQL

SQL アダプターで MFP.Server.invokeSQLStatement(options) API および MFP.Server.invokeSQLStoredProcedure(options) API を使用します。
JavaScript SQL アダプターチュートリアルで使用例を参照できます。

addResponseHeader

MFP.Server.addResponseHeader(name,value) API を使用して、新規ヘッダーを応答に追加します。

MFP.Server.addResponseHeader("Expires","Sun, 5 October 2014 18:00:00 GMT");

getClientRequest

MFP.Server.getClientRequest() API を使用して、アダプター・プロシージャーの呼び出しに使用した Java HttpServletRequest オブジェクトへの参照を取得します。

var request = MFP.Server.getClientRequest();
var userAgent = request.getHeader("User-Agent");

invokeProcedure

MFP.Server.invokeProcedure(invocationData) を使用して、その他の JavaScript アダプターを呼び出します。
拡張アダプターの使用法とマッシュアップチュートリアルで使用例を参照できます。

ロギング

JavaScript API は、MFP.Logger クラスによってロギング機能を提供します。 これには、4 つの標準ロギング・レベルに対応した 4 つの関数が含まれています。
詳細については、サーバー・サイドのログ収集チュートリアルを参照してください。

JavaScript アダプターの例

• JavaScript HTTP アダプター
  • JavaScript HTTP アダプターでの SSL の使用
• JavaScript SQL アダプター
• JavaScript アダプターでの Java の使用