1、通讯前置使用手册第一章通讯前置概述通讯前置系统是一个基于TCP/IP方式的通用通讯平台，它提供了丰富的通讯、报文转换和路由选择功能，能够整合各种杂乱无序的通讯需求，作为各类客户端和服务端的通讯枢纽，为其形成统一、平滑的通讯连接，为之提供统一、方便的管理。它是一个分布式，高度可配置的，组件化的运行、开发平台，提供二次开发的方式，有力的帮助客户方便、快捷的扩展新的业务。通信前置主要包括三个部分，下面先对这三部分分别加以简介，最后再介绍通讯前置的主要功能。一、通信前置服务器通信前置服务器是通讯前置系统的核心和主体，系统所有的对外的服务都由它提供。它主要包括控制器和监听线程，控制器读取配置文件，建立起
2、两个web端口来监听监控工具的管理请求，然后按照请求启动或者停止监听线程。监听线程负责监听某个具体的业务请求，在收到业务请求后，启动业务处理线程进行处理。二、通信前置服务监控工具监控工具负责对监听线程的状态进行控制。在这里可以设置监听线程的端口号，最大工作线程数等参数。可以启动和停止监听线程。管理员可以通过运行在字符终端的监控工具或者Web浏览器进行监控和管理工作。三、通信前置业务配置工具业务配置工具是用java开发的图形化用户界面，它用来收集用户的业务需求，将其转换为通讯前置服务器可读的配置文件，供通讯前置服务器读取。配置的主要内容是流程配置，报文格式配置及资源的配置等。上述三个部分相互独立
3、，它们可以分别安装在不同的机器上，但它们也是紧密联系的，缺一不可。它们的关系如图1-1所示:四、通讯前置服务器的主要功能1通讯模式转换随着业务的拓展，第三方的通讯模式越来越多样化，有同步的，有异步的，有长连接，也有短连接，而中间业务的通讯模式也可能有以上几种模式，通讯前置支持各种通讯模式的相互转换,为第三方和中间业务提供了统一、平滑的通讯连接。2报文格式转换第三方报文格式的定义更加是千差万别的，有定长报文、分隔符报文，8583报文，natp报文，xml报文等，甚至是同一种类型的报文，比如同样是8583报文，它们的定义也可以不相同。通讯前置服务器能够将第三方各种不同格式的报文转换成中间业务统一的
4、报文格式，这也为第三方和中间业务通讯提供了可靠的保证。3路由选择中间业务可以同时启动多个服务，路由选择的作用可以将交易按照负载均衡的原理或按照指定的要求分散到中间业务的各服务器上，这也保证了整个系统的稳定性。通讯前置服务器除了上述三大主要功能外，还有其它功能，比如通讯前置本身还具有集群功能，在后面章节我们介绍各种功能的实现方法。第二章 通讯前置服务器第一节概述 通讯前置服务器是整个通讯前置系统的核心，通讯前置的所有应用功能都是由它实现的，也是整个系统中最复杂的部分。图1-1是一个典型的通讯前置服务器内部的系统工作流程： 图1-1：通信前置系统流程从图1-1我们可以看出，通讯前置系统主要分为两部
5、分，处理客户端流程和处理服务端流程，以后我们都简称为客户端流程和服务端流程。在这里我们重点关心的是如何安装和使用通讯前置系统。通讯前置系统是跨平台的系统，由于通讯前置服务器是基于JAVA开发的，只要操作系统能够支持JAVA，那么就可以安装和使用通讯前置服务器。通讯前置服务器支持的最低JAVA运行环境是JRE1.3.1。接下来一节讲述通讯前置服务器的安装。第二节 安装通讯前置系统目前以压缩包的形式提供给用户，整个系统分为两个压缩包，Geronimo-test.zip和eciIDE.zip。其中Geronimo-test.zip为通信前置服务器安装包，ec.zipiIDE为通讯前置业务配置IDE环
6、境，目前暂不提供通信前置服务监控工具安装文件。安装步骤如下：一、 安装JRE(JDK)运行环境，通讯前置服务器支持的最低JAVA运行环境是JRE1.3.1，设置JAVA_HOME环境变量。二、解Geronimo-test.zip压缩包将Geronimo-test.zip解压缩到指定的安装目录下即可。转到安装目录下，输入java jar bin/server.jar&(java jar bin/server.jar) 或者运行startup.sh(startup.bat)即可启动通讯前置服务器。三、解eciIDE.zip压缩包 将eciIDE.zip解压缩到指定的目录下即可。双击eciIDE.e
7、xe，在弹出的对话框中输入通信前置服务器的IP，默认端口为3780，如下图所示。第三节 目录结构通讯前置服务器上目录结构如下，其中AFE_HOME是指安装目录，下面简要注明了每个目录存放的内容，以及每个目录下的主要配制文件的主要功能，至于它们详细使用后面会逐步介绍。AFE_HOME/(/Geronimo-test) |-bin / 启动前置和配制工具服务器的可执行文件 |-config / 通讯前置配置文件,有系统日志和activeMQ日志文件 |-config-store /序列化后的配置文件存放处 |-classes / 用户定义组件、报文、方法等(class文件)的存放目录 |-doc
8、/ 使用相关文档. |-lib / 这里放Geronimo服务器相关的Jar 文件 |-repository /系统所需的各种Jar文件 |-log / 存放启动通讯前置服务器信息的日志文件 |-skeleton / 存放服务器中的预定义报文格式, 组件等信息 |-var /Geronimo系统配置文件，包括权限、模块及日志 |-base /所有应用相关的信息都放在这个目录中 /业务数据按照管理节点/应用/交易”的层次组织 |-node.xml / 定义该目录所对应的节点信息 |-plan.pml /该节点对应的资源配置文件 |-test /管理节点目录（test只是作为示例，此处可以任意名称
9、） |-node.xml /test目录所对应的节点信息 |-client_demo / 业务应用目录（如公积金业务） |-node.xml / client_demo目录所对应的节点信息 |-plan.pml /公积金业务资源配置文件 |-log /该业务日志存放目录 |-config /该业务流水号文件所在目录 |-ser.bin /流水号文件 |-input /接入配置，适用于该业务的所有交易 |-workflow /工作流存放目录 |-input.cwf/输入工作流 |-message /报文格式 |-input.rcd |-varible (变量) /变量操作组件的配置文件存放目/录
10、，若该交易没有使用变量操作组/件，该目录不存在 |-var.xml /由用户命名，名称可能会不一样 |-script / 脚本目录 |-0001 /业务代码对应的目录 |-node.xml /0001目录对应的资源配置文件 |-workflow /工作流存放目录 |-input.cwf/输入工作流 |-message /报文格式 |-input.rcd |-varible (变量) /变量操作组件的配置文件存放目/录，若该交易没有使用变量操作组/件，该目录不存在 |-var.xml /由用户命名，名称可能会不一样 |-script / 脚本目录注：在base目录下，上述我们是以一个实际业务（公
11、积金业务）为例，说明了base的目录结构。所有的应用的配置都存放在base目录，该目录下可包含多个客户目录，上述只列出了一个客户目录（test），而每一个客户目录的结构都相同。下面再介绍一下geronimo-test目录下bin目录和config目录中每个文件的作用：Bin目录：startup.sh (startup.bat)：启动通讯前置配置工具服务。shutdown.sh(shutdown.bat)：关闭通讯前置配置工具服务。deploy.sh(deploy.bat):发布业务。可以加参数 help查看详细用法。geronimo.sh(geronimo.bat): 启动或者关闭通讯前置服务
12、器。Config目录：log4j.xml：日志输出的配置文件，在日志章节中有详细介绍。activemq.xml：activeMQ配置文件，系统内部使用到，一般无需更改。第三章 业务配置工具第一节概念业务配置工具是用来收集用户的业务需求, 生成通讯前置服务器可读的配置文件的图形化用户界面。该图形界面左边是树状结构，右边是相应节点的属性配置。下面我们先看一下配置好的一个业务的左边树状部分，至于具体如何配置我们后面会做详细介绍，在此的目的是先了解一些基本概念。图3.1 业务配置树状图上图是配置工具中业务配置左边的树状图，它是按被管理节点的从属关系组成的一棵树。点击相应的节点右边就会出现该节点的属性配
13、置界面，每个节点的属性配置界面在后面配置业务时讲解。下面先对这棵树进行说明：这棵树的根节点是前置服务，它包含两种子节点，系统服务（资源管理）和业务管理。系统服务中的配置是所有业务共用的全局资源，一般情况下很少需要改动。每个具体业务都可以继承和使用系统服务中的资源，并可单独配置本业务的资源。业务管理是对所有业务进行管理，是整个配置工具的核心，下面就介绍业务管理节点。业务管理节点是由多个具体管理节点组成，在上图中，交行公积金业务管理就是其中的一个管理节点，每个管理节点下又是由很多应用节点组成，比如上图中的公积金客户端就是交行公积金业务管理节点中一个业务应用。应用一般分为两种，面向客户端应用和面向服
14、务端应用，以后我们都会简称为客户端应用和服务端应用。客户端应用一般面向客户端，即正在开发的系统，服务端应用一般面向第三方，与第三方所提供的服务接口打交道。每个客户端应用都必须要有一个input的流程处理模块，即该应用下必须存在input的路径文件，负责该应用下面所有交易的交易代码的识别并以此选择后继流程，比如上图中的公积金客户端的交易代码识别模块。服务端应用无此特殊要求。每个应用下面的plan为该应用的资源配置文件，由以下十个部分组成：依赖模块，业务管理，接入适配器，接出适配器，文件流水号发生器，路由配置器，消息发送器，消息接收器，存储机制，控制器，这十种资源的详细配置在业务资源管理章节都有详
15、细介绍。该应用下的所有交易都共用这些资源。交易管理节点又是由报文格式配置、流程配置、变量配置以及脚本配置节点组成，它们之间的关系在后面讲具体配置时会有详细介绍。每个交易节点的路径名称必须是该交易所处理的交易代码，否则，交易流程无法正确被处理。交易节点下一级目录的流程配置节点，工作流配置文件的文件名称也必须和交易代码的名称一致。工作流是由一系列的组件组成，它支持顺序、选择、循环结构，整个工作流的流程图同结构化流程图完全类似。报文节点下可以有多个报文配置，供工作流中的拼包和拆包组件调用。下面再讲一下在配置工具上所看到的树状结构与通讯前置服务器的目录结构的关系，实际上它们是一一对应关系，对应关系如下
16、图所示，其中配置工具上的根节点前置服务对应着base根目录，其它的对应关系在图中也可以清晰的看到，红线左边是通讯前置服务器的目录结构，右边是配置工具上树状结构，也可以参照图3.1来看。在业务配置工具（即IDE）环境下对任何配置文件的修改都保存在了前置服务端。图3.2树状结构与通讯前置服务器上目录关系第二节 功能介绍一、导入、导出功能该功能方便用户将配置好的业务从一台服务器移到另一台服务器上。它的操作顺序是首先将配置好的业务导出到一个jar包中，然后再将该jar包导入到其它前置服务器上。下面分别介绍导入和导出操作。1导出导出又分以下几种情况：（1）导出所有的业务配置。操作方法是将鼠标右键点击根节
17、点前置服务，再选择导出，然后就会弹出一个对话框，只要选择路径和填写文件名即可。（注：此处最好避免使用中文文件名，否则导入时候会有问题）（2）导出一个客户的所有业务。操作方法是将鼠标右键点击客户节点，再选择导出。（3）导出一个指定的业务。操作方法是将鼠标右键点击指定的业务节点，再选择导出。（4）导出某个业务下的指定交易。操作方法是将鼠标右键点击指定的交易节点，再选择导出。（5）导出某个指定的配置文件。操作方法是将鼠标右键点击指定的配置文件节点，再选择导出。2导入点击配置工具的菜单上的工具栏，再点击工具栏上的导入，然后选择需要导入的jar包（通过配置工具导出的jar包），点击导入即可。注：（1）当
18、更新的通讯前置服务中的jar包时（比如afe.jar），最好要重新启动配置工具服务器，否则导入、导出时可能会出错。（2）jar包命名避免采用中文，应该采用英文或数字等。（3）导入时，如果有同名目录（待导入的服务器上已经存在同jar包业务相同的目录），则会替换掉已有的文件。因此导入整个业务时，要检查是否存在同名目录。（在配置工具的状态栏上会显示出路径）二、业务配置配置工具的主要作用就是对业务进行配置，它的详细配置稍后再详细介绍，先介绍一下业务配置的几个辅助功能：1复制功能复制业务，复制交易，复制工作流，复制报文，复制资源配置文件（包括接入、接出适配器等）。它的操作只要将鼠标右键点击到相应的节点上
19、，然后选择复制即可。2粘贴功能复制好以后，接下来就是粘贴到相应的节点下，粘贴的操作主是用鼠标右键点击到相应的节点上，然后选择粘贴，如果有同名情况（指目录相同），则会弹出相应的对话框提示重命名。3删除功能删除客户，删除业务，删除交易，删除工作流，删除报文，删除资源配置文件等，它的操作只要将鼠标右键点击到相应的节点上，然后选择删除即可。注：上述三个操作将鼠标左键点击到相应节点上时，都可以在菜单上选择相应的操作（可以选择菜单上的图标）。4重命名功能重命名工作流名称，重命名报文名称，它的操作只要将鼠标右键点击到相应的节点上，然后选择重命名即可。若重命名报文名称，则在流程中的引用该报文的拆包或者拼包组件
20、需要选择新的报文引用。注:在删除或者重命名应用时，最好先对将要操作的应用进行卸载，在更改完成后再对其进行部署。否则，若删除该应用，需要到通讯前置服务下手动卸载该应用。手动卸载应用方法，可到通讯前置服务bin目录下输入 deploy.sh help查看相关帮助，前置系统默认的用户名和密码分别是system，manager。注：红色部分系统目前暂不支持。5报文浏览器功能报文浏览器的作用是为了方便用户编辑报文，它可以将同一个业务下编辑好的报文中的某些节点导入到当前编辑的报文中。因为在同一个业务下每个报文中的很多节点的配置都完全相同，这样就可以很方便的编辑后面的报文。它的操作方法是在编辑报文时，在报文
21、编辑界面的菜单上选择报文浏览器，然后在弹出的界面中选择报文中的指定节点（可以多选），再右键点击，选择加入当前编辑报文即可。如果选择了多个节点加入到当前编辑报文，它不能保证加入后节点的顺序同原报文中的节点相同，一般情况下都不相同，它是随机的。我们可以通过报文节点中的上移和下移来调整节点的顺序。6数据词典功能首先说明数据词典的功能可以由报文浏览器功能实现，它的作用也是帮助用户重复利用编辑好的报文。它的操作方法是先将常用的数据字段节点加入数据词典，然后在编辑报文时，可以将需要的数据字段从数据词典中取出加入到当前编辑报文中。上面讲述了配置工具的几个辅助功能，剩下就是如何配置业务。业务的配置根据不同情况
22、配置方法也不一样，在接下来几节对不同情况下的业务配置分别加以介绍，包括资源配置，交易配置，报文配置等。第三节 业务配置步骤一、启动配置工具启动配置工具分三步进行：首先，在通讯前置服务器上启动通讯前置服务，若通讯前置服务在windows操作系统上，运行命令/startup.bat，若通讯前置服务在unix或linix等操作系统上，运行命令/startup.sh。（注：此startup.sh位于文件根目录下，避免使用bin/目录下的startup.sh来启动系统）另外，与平台无关的启动方式为 java jar bin/server.jar& 。若不小心将前置服务中的配置连接服务卸载，则需要手动启动
23、配置连接服务，运行命令depolyConfigServer.sh即可，此命令中需要输入用户名和密码，它们分别是system,manager。其次，在客户端（操作系统是windows）启动通讯前置图形化的配置工具，方法是直接双击eciIDE.exe即可。最后，将配置工具和通讯前置服务建立连接，只有同服务器建立连接后才可以进行业务配置了。建立连接的方法是：在启动配置工具时，会弹出建立新服务连接的界面，如下图3.3所示：从图中可以看出，通过配置工具可以连接到局域网内所有的通讯前置服务器(图中包括本机在内，已配置了三台通讯前置服务器的地址)，可以选择需要连接的服务器，再点击连接按钮，也可以添加新的连接
24、，添加新的连接时，只需要正确填写服务器地址和端口即可，端口默认为3780，该端口可以在启动配置工具服务时重新设定，另外也可以对已有的配置加以编辑，进行修改。图3.3 建立新服务连接界面二、业务配置准备在对业务进行配置前，必须清楚以下几个方面：首先，清楚第三方和中间业务的通讯模式，主要有以下几种：同步短连接，同步长连接，异步短连接，异步长连接。因为通讯模式的不同，接入、接出适配器和流程配置都有所不同，后面将举例说明各种情况业务的配置。其次，清楚交易发起方是第三方还是中间业务，并且要知道第三方接收、发送交易的端口是否相同，发送和接入是作为客户端还是作为服务端，它也涉及到接入、接出适配器选择问题。再
25、次，要知道第三方和中间业务通讯包的报文格式，主要有8583报文、natp报文、定长报文、分隔符报文、xml报文等。另外要正确配置交易，还要知道双方报文接口之间的关系，也就是它们之间字段的对应关系。了解上述几方面后，就可以进行业务配置了，接下来几节中就举例说明各种情况的业务配置，首先介绍一种比较简单情况，双方是同步短连接情况，且第三方是作为客户端发送和接收数据。第四节同步短连接业务配置一、同步短连接概念同步，就是指发送数据和接收数据是使用同一条连接，且是同一个端口。具体来说是交易发起方在发送一笔交易后，必须要等待该笔交易的返回（超时除外），才会接着发送下一笔交易。短连接是指完成一笔交易后（从发送
26、数据，直到数据返回），连接就断开，做下一笔交易时，重新建立新的连接。二、业务配置下面以交行公积金联名卡业务配置为例，以此来说明同步短连接业务配置方法。先对交行公积金联名卡业务的详细情况介绍一下：首先，通讯模式公积金方和中间业务都是同步短连接，交易是由中间业务方发起，且收发数据都是作为客户端，由前置机作为服务端起监听来接收数据，再通过报文转换拼成公积金方所需的包，然后，前置机接收中间业务返回的包，再通过一次报文转换拼成中间业务所需的包，最后将数据包返回给中间业务。其次，公积金方的报文为XML报文，提供WEBSERVICE接口，中间业务的报文格式是定长报文（指每个字段的长度是固定的），且数据包也是
27、定长包（整个包的长度是固定的）它的基本流程如下：三、同步短连接业务配置步骤第一部分：配置客户端应用1 在通讯前置系统|新建管理节点 下新建一个管理节点图3.5 新建管理节点2 在弹出的添加新管理节点中填写管理节点名称和目录名称及描述信息，然后按确定按钮。图3.6 添加新管理节点界面3 在通讯前置系统公积金联名卡新建应用 下添加一个客户端应用 图3.7 添加新应用4 在弹出的添加应用配置中填写应用名称和目录名称，类型选择客户端应用。图3.8 添加新应用配置界面5下面再对交行公积金联名卡业务的客户端应用的资源管理进行配置(1) 配置接入适配器双击 公积金联名卡客户端应用plan ，打开资源管理界面
28、图3.9资源管理界面在界面中选择接入适配器|套结字接入适配器|右键选择“新建短连接服务端接入适配器”，如下图所示：图3.10 接入适配器选择界面填写适配器名称，监听端口，超时时间，绑定地址为默认值0.0.0.0（即localhost）图3.11 短连接服务端接入适配器属性配置界面第二部分：配置服务器端应用部分1在通讯前置系统公积金联名卡新建应用 下添加一个服务端应用 图3.12 添加服务端应用2配置接出适配器，双击 公积金联名卡客户端应用plan ，打开资源管理界面，在接触适配器上选择“新建WEBSERVICE接出适配器”。 图3-13 添加WEBSERVICE接出适配器3填写适配器名称，WS
29、DL地址，包名，另外需要注意的是，包含所填包名的jar文件必须手动打包并上传到通讯前置服务器上。（系统目前提供一个可根据WSDL文件地址直接生成Jar包的一个单独应用，直接将生成的jar文件替换到/repository/afe/jars目录下即可。关于这个打包程序的更多信息，请向Agree索取。） 图3-14 配置WEBSERVICE接出适配器基本信息到此为止，公积金联名卡的业务资源配置已完成，剩下几个资源：消息发送器、路由配置、储存机制等暂时略过不讲，此业务中也不需要用到，它们作用及详细配置请参考资源配置章节，接下来就进行具体交易的配置了。6 交易配置交易配置包括客户端交易配置和服务端交易配
30、置两部分，两者都包括报文配置和流程配置，交易配置的顺序一般是先配置工作流，再配置报文，当然也可以交叉进行。在进行工作流配置前先将公积金方和中间业务方查询账户余额的接口信息列出。(1) 报文接口公积金的报文接口说明，查询结果以XML文件形式返回给通讯前置。序号数据项名称数据项代码数据格式数据规则说明1返回值FHZCHAR(4)文本取值见返回值代码对照表2 个人登记号GRDJHVARCHAR2(30)文本3姓名XMVARCHAR2(20)文本4余额YENUMBER (18,2)0到9的数字，两位小数5查询日期CXRQCHAR (8)YYYYMMDD表3.1公积金方余额查询接口说明 返回XML文件内容Demo如下： - 0000110101*00李某某- lmkgjjye 56.00 20050916 /GJJ
