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 命令能够帮助创建各种 DevOps 流，根据您所处环境（DEV、QA、UAT 或 PRODUCTION），适配器中需要不同的值。

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 适配器中只可以有一个 JavaScript 文件。 还包含零个、一个或多个 XSL 文件，此类文件中包含用于检索到的原始 XML 数据的转换方案。 适配器检索到的数据可以按原始格式返回或由适配器本身进行预处理。 不论哪种，都会作为 JSON 对象提供给应用程序。

JavaScript 适配器过程

出于以下目的，已在 XML 中声明并通过服务器端 JavaScript 实施这些过程：

• 向应用程序提供适配器功能
• 调用后端服务以检索数据或执行操作

在 adapter.xml 文件中声明的每个过程都必须在 JavaScript 文件中具有相应的函数。

通过使用服务器端 JavaScript，过程可以在其调用服务之前或之后处理数据。 通过使用简单的 XSLT 代码，您可以针对检索到的数据应用更多过滤。
JavaScript 适配器过程是在 JavaScript 中实施的。 但是，由于适配器是服务器端实体，因此可以在适配器代码中使用 Java。

使用全局变量

MobileFirst Server 不依赖于 HTTP 会话，且每个请求都可到达不同的节点。 不应依赖于全局变量来传输请求的数据。

适配器响应阈值

适配器调用不是为了返回巨大的数据块，因为适配器响应作为字符串存储在 MobileFirst Server 内存中。 因此，超出可用内存量的数据可能会导致内存不足异常，适配器调用将失败。 为防止此类调用失败，您可以配置一个阈值，使 MobileFirst Server 根据此阈值返回 gzip 压缩的 HTTP 响应。 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 报告活动以及获取请求发出者的身份。

getPropertyValue

MFP.Server.getPropertyValue(propertyName) API 用于检索在 adapter.xml 或 MobileFirst Operations Console 中定义的属性：

MFP.Server.getPropertyValue("name");

getTokenIntrospectionData

使用 MFP.Server.getTokenIntrospectionData() API

要获取当前的用户标识，使用：

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) 和 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 类提供日志记录功能。 它包含对应于四个标准日志记录级别的四个函数。
您可以参考服务器端日志集合教程，以了解更多信息。

JavaScript 适配器示例

• JavaScript HTTP 适配器
  • 在 JavaScript HTTP 适配器中使用 SSL
• JavaScript SQL 适配器
• 在 JavaScript 适配器中使用 Java