核算平台通讯开发说明

1、核算平台通讯开发说明修订历史制定日期制定/修订 内容摘要页数版本拟稿审查批准2015.01.04初稿王瑞目录目录31. 概述42. 核算平台作为服务端52.1 说明52.2 实时通讯52.3 字段映射103. 核算平台作为客户端123.1 说明123.2 实时通讯123.2.1 创建通讯服务123.2.2 配置请求/响应报文173.2.3 设置参数及字段值193.3 批量通讯211. 概述核算平台对外通讯主要分两种场景，分别是核算平台作为服务端及核算平台作为客户端，下面分别进行说明。2. 核算平台作为服务端2.1 说明核算平台作为服务端，对其他平台系统提供服务，即其他平台发请求到核算，核算平台

2、收到请求之后做相应的业务逻辑处理，之后将处理结果返回给请求方。核算平台作为服务端，通讯主要采用实时方式，下面进行详细说明。2.2 实时通讯常用的通讯方式有TCPIP通讯（即Socket通讯）、HTTP通讯、WebService通讯等，这里以TCPIP通讯方式为例进行说明。首先，在EMP Explorer视图下，选中“渠道逻辑”，右键点击“新建渠道接入定义”，会弹出对话框，如下图所示。选中“TCPIP渠道接入”，在名称栏中输入接入渠道的名称，如“QSTcpipChannel”，此处不支持中文，最后点击“Finish”按钮。此操作会在web.xml文件添加一个<servlet>和<

3、;servlet-mapping>，如下所示。<servlet>中load-on-startup的值需要大于1。接下来进行参数设置，如下图所示，默认的超时设置是600000ms，即10分钟，可根据实际情况进行设置，一般采取默认。通讯设定处，连接方式可选“短连接”和“长连接”，短连接表示一次通讯完成之后关闭连接，长连接表示通讯完成之后连接也不关闭；双工模式可选“false”和“true”，一般情况下默认选“false”，false表示单工。监听端口设置：如下图所示，端口根据实际需求填入端口数字，持久连接可选true或false，一般默认选false，最大连接限制、使用线程缓冲和

4、缓冲线程数可根据实际需求填写。解包处理设置：此处实现类是“m.CommProcessor4Xingye”，此类实现“com.ecc.emp.tcpip.CommProcessor”接口，主要包括两个接口方法readPackage和wrapMessagePackage，前者主要用于接到报文后对报文信息进行初步的解包处理，如读取报文长度，将后面的报文读取出来，可添加一些特殊的预处理，如MAC校验等，后者是在响应报文完成拼包之后，再对响应报文做些特殊处理，如加上报文头长度，MAC校验等。各个实施项目需求不一，此类一般各项目需要根据实际需求定制。接入逻辑设置：此处实现类是com.ecc.emp.acc

5、ess.tcpip.EMPTCPIPRequestHandler，主要功能是对请求报文进行解包处理，响应报文进行拼包处理。对于TCPIP通讯，如果需要对报文的字段进行映射，可使用com.ecc.emp.access.tcpip.EMPTCPIPMappedRequestHandler类。serviceIdField与之后的Biz相对应，此处一般默认填“serviceId”，表示根据serviceId的值查找biz中对应的业务逻辑。“是否截去请求报文头”和“是否在返回报文中附带报文头”可根据实际需求配置。双击“请求报文头”及“响应报文头”根据实际需求配置报文头。选中上图中的“TCPIP渠道接入”

6、，右键“新建”，选中“TCPIP接入交易”并点击，弹出框如下图所示，选中biz，点击“Next”，在接下来的弹出框选中业务逻辑，然后点击Finish。会创建一个TCPIP接入交易，如下图所示。描述栏可改为有意义的描述，交易码也可根据实际需求进行修改。之后选中上图中的点击右键，“新建”，分别新建请求报文和响应报文，然后分别双击请求报文和响应报文根据实际需求配置报文格式。2.3 字段映射核算平台作为产品，各交易场景有自己的请求响应报文，报文中的字段由核算平台自己定义。在项目实施中，报文的字段与核算平台的字段命名不一致，这就需要进行字段映射。目前字段映射功能只支持TCPIP通讯方式，具体配置说明如下

7、。配置TCPIP渠道接入时，接入逻辑应把实现类设为com.ecc.emp.access.tcpip.EMPTCPIPMappedRequestHandler。字段映射配置文件DICTMapped.xml放在与applicationCmis2Ycloans.xml同级路径下，对于公共字段，放到common子节点下，其他放到各自的serviceId下。此处id为核算平台的数据字段定义，mappedID为外部平台定义的数据字段（示例全部在前面加new_）每个ServiceID对应的字段映射配置如下，以serv10000100054为例进行说明。<serv10000100054><f

8、ield id="LOAN_NO" mappedID="new_LOAN_NO" /><field id="FEE_TYP" mappedID="new_FEE_TYP" /><field id="TX_LOG_SEQ" mappedID="new_TX_LOG_SEQ" /><field id="STR_DT" mappedID="new_STR_DT" /><field id=&quo

9、t;END_DT" mappedID="new_END_DT" /><field id="LmHoldFeeTxList" mappedID="new_LmHoldFeeTxList" /><field id="SEQ_NO" mappedID="new_SEQ_NO" /><field id="CREATE_DT" mappedID="new_CREATE_DT" /><field id=&quo

10、t;CREATE_USR" mappedID="new_CREATE_USR" /><field id="FEE_AMT" mappedID="new_FEE_AMT" /><field id="SETL_FEE_AMT" mappedID="new_SETL_FEE_AMT" /><field id="FEE_CDE" mappedID="new_FEE_CDE" /><field id=&quo

11、t;FEE_CCY_CDE" mappedID="new_FEE_CCY_CDE" /><field id="FEE_TYP" mappedID="new_FEE_TYP" /><field id="FEE_CHRG_PCT" mappedID="new_FEE_CHRG_PCT" /><field id="HOLD_SETL_DT" mappedID="new_HOLD_SETL_DT" /><f

12、ield id="SETL_IND" mappedID="new_SETL_IND" /><field id="FEE_RMK" mappedID="new_FEE_RMK" /><field id="LAST_PAY_DT" mappedID="new_LAST_PAY_DT" /><field id="LOAN_ACCT_TYP" mappedID="new_LOAN_ACCT_TYP" />

13、;<field id="RECV_PAY_IND" mappedID="new_RECV_PAY_IND" /><field id="FEE_BASE_AMT" mappedID="new_FEE_BASE_AMT" /><field id="FEE_CHRG_PCT" mappedID="new_FEE_CHRG_PCT" /><field id="HOLD_SETL_DT" mappedID="new

14、_HOLD_SETL_DT" /><field id="SETL_IND" mappedID="new_SETL_IND" /><field id="FEE_RMK" mappedID="new_FEE_RMK" /><field id="LAST_PAY_DT" mappedID="new_LAST_PAY_DT" /><field id="LOAN_ACCT_TYP" mappedID=&quo

15、t;new_LOAN_ACCT_TYP" /></serv10000100054>3. 核算平台作为客户端3.1 说明核算平台与外部系统（如核心及清算系统等）通讯分为两种情况，实时和批量。下面就这两种情况分别进行说明。3.2 实时通讯核算平台作为客户端，向外部系统发出请求，外部系统收到请求之后做出响应，然后返回给核算平台，这是一个完整的通讯过程。核算要实现发出报文请求的功能，需要完成三个步骤，创建通讯服务、配置请求/响应报文、设置参数及字段值、下面进行详细说明。3.2.1 创建通讯服务创建通讯服务，选择目标Biz，在如下图所示。在服务定义视图，点击“创建”，弹出对话

16、框，选择“通讯类服务”的“TCPIP访问服务”，组件ID处填“toHexin”，“组件描述”可选填，最后点击“Finish”按钮。此处实例选择了“TCPIP访问服务”，可根据项目实际情况选择其他通讯类服务。点击“Finish”之后，弹出对话框如下图此处双工通讯选“false”，持久连接选“false”（可根据项目实际需求进行设置），如下图所示。点击，右键新建“ConnectToHost”，选中“ConnectToHost”设置端口，主机地址及持久连接，本例子设置端口7777，核心ip地址，持久连接为“false”，如下图所示，此处按项目的实际情况设置参数。点击，右键新建“Co

17、mmProcessor”，选中“CommProcessor”，设置实现类“m.CommProcessor4Xingye”，本类实现了“com.ecc.emp.tcpip.CommProcessor”接口，主要包括两个接口方法readPackage和wrapMessagePackage，前者主要用于接到响应报文后对报文信息进行初步的解包处理，如读取报文长度，将后面的报文读取出来，可添加一些特殊的预处理，如MAC校验等，后者是在请求报文完成拼包之后，再对响应报文做些特殊处理，如加上报文头长度，MAC校验等。各个实施项目需求不一，此类一般各项目需要根据实际需求定制，点击“Finish”按钮，如下图所

18、示。核算与核心通讯服务创建完毕，如下图所示。3.2.2 配置请求/响应报文选择目标Biz，在“数据报文”视图，如下图所示在“报文定义ID”填入batchNoticeReq，描述填入“批量文件通知清算请求报文”，点击“创建”，然后选中“batchNoticeReq”，在右侧配置请求报文，如下图所示。同样操作配置响应报文“batchNoticeResp”，此处不再详述。3.2.3 设置参数及字段值在表pay_diagram_head中插入一条数据，如下所示，seq_no是配置序号，trade_code和trade_memo可选填，req_fmt_id对应上文配置的请求报文的id，rep_fmt_i

19、d对应上文配置的响应报文的id，req_head和rep_head可选，sys_name为配置的通讯服务的id，rep_fmt_error_id可选，encode为通讯采用的编码。以批量文件通知请求报文为例，请求报文需求如下。配置此报文，除了上文配置请求报文外，还需要在表pkg_typ_dtl中插入下面的数据，如下图所示。Typ_id对应于表pay_diagram_head的seq_id，seq_no为字段的编号，对于xml报文无意义，可不填，FLD_NM为报文中的字段名称，FLD_DESC为字段描述，FLD_LEN是字段长度，适用于定长报文，此处为空，FLD_VAL为字段值的配置。字段值的配

20、置下面进行详细说明。目前字段值取值来源主要有5种情况：固定值、业务对象的某个属性值，上下文的某个element的值，定制值，业务对象的某个属性值得加工值。1. 对于固定值，直接在FLD_VAL中填入即可，如上文中的transcode的值为固定值8001，则在pkg_typ_dtl表中transcode对应的fld_val为8001。2. 对于业务对象的某个属性值，配置为#属性的get方法，如上文中的交易流水号serialno,值来源于业务对象com.yuchengtech.ycloans.db.domain.PayPkgIr的实例中的batTxSeq的值，此处配置为#getBatTxSeq，使

21、用反射的方式获取PayPkgIr实例的batTxSeq值。3. 若字段的值来自于上下文ctx的某一个element的值，则配置为$element名称。4. 若字段的值来自于自定义的值，则配置为%FiledTool中的方法名，实现逻辑是从FieldTool的方法中获取，适用于ctx和业务对象都不能拿到字段的值，只能定制化获取，如上文中的date，配置为，获取满足特定格式的当前时间，getCurrentTime是FieldTool类中的方法。5.若字段的值来自于业务对象的某个属性值的加工后的值，则配置为%#属性个get方法，同时需要在FieldTool类中添加此get方法，并将属性值作为此方法的参

22、数，加工逻辑在此方法中实现。常见的场景是对金额做特殊处理等。整数10位，小数2位，右对齐左补0，如1234.56就是000000123456，此处可以采用此方法。以上配置完成之后，即可在代码中调用ServiceContainer.getMessageWrapper().send(messageId, buzObj, op)方法发送请求报文，messageId是报文配置的ID，对应上述例子中的6，buzObj为业务对象，可以为任意类型，op为OnlineParam，是联机参数，主要提供上下文信息。messageId值可以在Parameters类中定义一个属性，然后通过ServiceContain

23、er.getSystemParameter().getXXXId()获取messageId的值，messageId的值可在applicationContetxt.xml的parameter对应的bean中配置，如下图所示，下图是Parameter的bean配置的一部分。3.3 批量通讯核算平台与外部系统进行通信，存在批量通讯场景，比如发送对账文件，批扣文件等。目前批量通讯多以文件形式发送。先按照报文要求生成批量文件，然后放到本地或者ftp的配置好的路径下。报文一般采用定长报文或者分隔符报文。下面以定长报文为例进行说明，分隔符报文类似。假设报文需求如下：记录换行符“n”在表pkg_typ插入请求

24、和响应报文的配置，如下图所示，请求报文对应的是typ_id为4的配置，响应报文对应的是typ_id为5的配置；pkg_typ表示报文类型，此处“DC”表示定长报文，“FGF”表示分隔符报文；fld_del为分隔符标识，“SX”表示竖线分隔，“DH”为逗号分隔，主要用于分隔符报文；ln_del为文件的换行标识配置，“HH”表示换行符，“HE”表示换行+回车符；fld_alg为对其方式的配置，“Y”表示右对齐，“Z”表示左对其；fd_chr为结束符配置，“SY”表示双引号，“DY”表示单引号，“DH”表示逗号，“NL”表示没有；emt_sd为空发送标示配置，“Y”表示即使没有可发送的内容也要传送，“N”表示空不发送，默认为N；hd_del为表头分隔符，“MH”表示冒号。之后在p