普天海油信息系统间统一通信工具BIT接口说明

1、.信息系统间统一通信工具（BIT）接口说明 文档编写： 谭贺春 提交日期： 2010-07-19 审 批 人： 北邮项目组2010-07-20文档修改记录撰写人修改时间原版本号修改内容介绍谭贺春2010-07-20V1.0编写文档目 录1、综述42、术语43、软件的组成结构43.1配置信息加载43.1.1 配置文件43.1.2 配置信息加载接口53.2协议对象63.2.1 Request对象73.2.2 Response对象83.2.3 Notification对象93.2.4 Ack对象103.2.5 OneWay对象103.3编解码113.4安全机制123.5客户端操作123.6服务器端操

2、作133.7日常功能144、数据处理机制144.1专门用来处理Request请求的RequestWork154.2专门用来处理Notification的NotificationWork174.3专门用来处理OneWay的OneWayWork175、使用说明185.1 软件包的组成185.2 如何准备数据库映射文件185.3 使用方法181、 综述 BIT软件是针对普天海油项目中诸多子系统间的数据通信，开发的一个Java的接口软件。普天海油项目存在着BOSS、GIS等这样的相对独立的子系统，系统间数据需要根据查询的方式、上报确认方式、上报不确认方式等来及时的通信。该软件提供公用的接口，完成上述需

3、求。该软件的通信传输协议使用xml格式组织，数据获取采用hibernate的查询接口，故在软件的使用过程中服务器方需要产生支持hibernate的标准java Bean和相关配置文件。此外，BIT软件支持Http post和socket网络协议方式。2、 术语序号术语描述1BIT网管通信接口(BUPT Interface toolkit)2Hibernate一个开放源代码的对象关系映射框架，它对JDBC进行了非常轻量级的对象封装，使得Java程序员可以随心所欲的使用对象编程思维来操纵数据库。3HQLHibernate配备的一种面向对象的查询语言4BOSS电动车基本信息的管理系统5GIS地理信息

4、系统6javabeanJavaBean 是一种JAVA语言写成的可重用组件。为写成JavaBean，类必须是具体的和公共的，并且具有无参数的构造器。AVA语言写成的可重用组件。为写成JavaBean，类必须是具体的和公共的，并且具有无参数的构造器。3、 软件的组成结构 该软件根据协议文档要求，抽象出了Request、Response、Notification、Ack、OneWay等对象。软件可以解析符合协议标准的XML，将其内容封装到以上抽象出来的对象当中，并且也可以逆向的将对象内容解析后组织成XML格式。软件提供信息的接收和发送的功能。发送功能：组织Request对象，转换Request对象

5、为协议规定格式的xml字符串，并发送给服务器端，接受符合Response协议规定的xml字符串； 组织接收功能：接收符合Request消息协议规定的xml字符串，将其转化成Request对象，并对Request对象进行相关处理，处理后，组织Response对象，转换Response对象为符合Response消息协议规定的xml字符串，最后将这个字符串发送给客户端；接收符合Notification消息协议规定的xml字符串，将其转化成Notification对象，并对Notification对象进行相关处理，处理完成后，组织Ack对象，转换Ack对象为符合Ack消息协议规定的xml字符串，最后将

6、这个字符串发送给服务器端；接收符合OneWay消息协议规定的xml字符串，将其转化成OneWay对象，并对OneWay对象进行相关处理.由此软件主要结构为：配置信息加载、协议对象、编解码、安全机制、发送功能、接收功能、日常功能等。3.1配置信息加载3.1.1 配置文件在使用该软件前，需对软件提供的配置文件根据实际使用情况进行修改。这主要是出于对软件的可维护性的考虑。1、 config.xml配置文件结构：<properties><!- 服务器端软件访问用户名密码 token论证-><username>qiyubin</username><p

7、assword>123</password><people username="qiyubin" password="123"> </people><people username="admin" password="admin"></people><!- Token生存周期 秒为单位 -><liveTime>300</liveTime></properties>作用：用来配置服务器端的服务器访问密码。

8、参数解释：username服务器用户名。password服务器密码。Livetime 用户登陆后不活动的存活周期，单位是秒。使用场景：在服务器部署阶段使用，配置好相应的信息。2、 perties配置文件结构：socket.北京普天发电站=5:3000http.notificationTest=http:/localhost:8080/transmit/servlet/NotificationServerhttp.onewayTest=http:/localhost:8080/transmit/servlet/OneWayServer

9、作用：所有的目的地址信息均在这个文件中。注意：程序运行时文件位于WebRootWEB-INFclasses下。每次软件重新部署，需备份该文件。参数解释：http.+标识名称（sign）：一个符合http协议的地址, 值的格式：socket.+标识名称(sign)：值的格式：6:3000标识名称可以为汉字。使用场景：在服务器部署阶段使用，配置好相应的信息。软件提供接口可根据标识名称(sign)对该配置文件操作。3.1.2 配置信息加载接口config.xml、perties文件里的信息可以通过类HYApplicaiton和接口Destinati

10、on的实现类提供的方法获取。HYApplicaiton位于com.bupt.transmit.unite.environment包下；Destination位于com.bupt.transmit.unite.service.destination包下，SocketDestination和HttpDestination为Destination的实现类。HYApplicaiton方法如下：方法摘要 DestinationgetDestination(ProtocolType protocolType)       &#

11、160;   功能描述：根据protocolType的值获取destination的实现类的实例，其中ProtocolType为枚举类型 intgetTokenLiveTime()           功能描述：获取token的生存时间ProtocolType为枚举类型：枚举常量摘要http   http协议标识socket  socket协议标识Destination接口方法如下：方法摘要 intaddDestii

12、nation(java.lang.String sign, java.lang.String address)           功能描述：增加目的地址。 intdeleteDestination(java.lang.String sign)           功能描述：删除目的地址。 AddressgetAddress(java.lang.S

13、tring sign)           功能描述：得到目的地址。 intmodifyDestination(java.lang.String sign, java.lang.String address)           功能描述：修改目的地址。Address用于封装地址信息，字段说明如下：字段摘要 java.lang.Stringhttp

14、Address           http 协议使用的地址 java.lang.StringsocketIp           socket协议使用的ip地址 intsocketPort           socket协议使用的socket端口3.2协议对象这部分主要是对协

15、议内容的抽象，将协议抽象为Request、Response、Notification、Ack、OneWay等对象。每个抽象类中包含将对象自身编码为xml格式的字符串的encode（）方法。另外对于id和token系统会自动生成，用户不需要再对其操作。该部分接口位于软件包 com.bupt.transmit.unite.model：类摘要Ack功能描述：封装ack协议的类Notification功能描述：封装notification的类OneWay功能描述：封装oneWay协议的类Request功能描述：封装request基础类Response功能描述：封装response基础类3.2.1 Re

16、quest对象Request对象是对协议部分request消息的一种抽象，Request提供接口方法如下：方法摘要 voidaddHql(java.lang.String value)           功能描述：采用hql方式获取数据时，填写这个，此时不需要使用addParameter填写Parameter voidaddInclude(java.lang.String value)      

17、0;    功能描述：采用standard查询方式时，填写该字段，否则会出现查询错误 voidaddParameter(java.lang.String discribe, java.lang.String value)           功能描述：采用standard查询方式时，填写该字段，否则会出现查询错误。 java.lang.Stringencode()     &#

18、160;     功能描述：将Request对象解析为xml格式的字符串 java.lang.StringgetHql()           功能描述：haql查询时，得到hql语句 java.lang.StringgetInculude()           功能描述：standard查询时，得到include值 

19、;java.lang.StringgetName()             java.util.MapgetParameters()           功能描述：standard查询时，得到参数信息部分 voidsetName(java.lang.String name)        

20、;   功能描述：设置request的处理类型的名字，name：详见协议文档name命名规范3.2.2 Response对象response对象是对协议部分response消息的一种抽象，response提供接口方法如下：方法摘要 voidaddAttribute(java.lang.String key, java.lang.String value)           功能描述：增加attribute；key为字段信息；value

21、为key的对象类型（支持简单对象类型） voidaddData(java.lang.Object keys, java.lang.Object values)           功能描述：增加传输的数据；一个查询出来的bean中的字段需组织成数组. java.lang.Stringencode()           功能描述：将Response对象解析为

22、xml格式的字符串 java.util.MapgetAttributes()           功能描述：获取全部属性，属性为键值对 java.lang.StringgetCause()            功能描述：在ack中得到出错的原因 java.lang.StringgetCode()      

23、     功能描述：得到出错的原因代码 java.util.List<java.util.Map>getDatas()           功能描述：获得复杂数据类型，list中的一个map为一个实体。 java.lang.StringgetReplyId()             java.l

24、ang.StringgetType()           功能描述：得到返回的response类型 voidsetCause(java.lang.String cause)           功能描述：封装错误原因 voidsetCode(java.lang.String code)       

25、;    功能描述：设置错误编号 voidsetIsfinished(boolean isfinished)           功能描述：标识是否已传输结束，若传输结束位True，否则为false voidsetReplyId(java.lang.String replyId)           功能描述：封装 请

26、求的 request 对应的reponse ID voidsetType(java.lang.String type)           功能描述：封装返回的response类型，可以是success、failure、zero3.2.3 Notification对象 Notification对象是对协议部分Notification消息的一种抽象，Notification提供接口方法如下：方法摘要 voidaddAttribute(java.lang.String&

27、#160;key, java.lang.String value)           功能描述：增加attribute.key为字段信息；value为key的对象类型（支持简单对象类型） voidaddData(java.lang.Object keys, java.lang.Object values)           功能描述：增加传输的数据；一个

28、查询出来的bean中的字段需组织成数组.   java.lang.Stringencode()           功能描述：将Notification对象解析为xml格式的字符串 java.util.MapgetAttributes()           功能描述：获取全部属性，属性为键值对 java.util.List<java.uti

29、l.Map>getDatas()           功能描述：获得复杂数据类型，list中的一个map为一个实体。 java.lang.StringgetName()           功能描述：得到notification的处理类型的名字，name：详见协议文档name命名规范 voidsetContent(Content content)  &

30、#160;        功能描述：封装消息内容部分 voidsetName(java.lang.String name)           功能描述：设置notification的处理类型的名字，name：详见协议文档name命名规范3.2.4 Ack对象Ack对象是对协议部分ack消息的一种抽象，ack提供接口方法如下：方法摘要 java.lang.Stringencode() &

31、#160;         功能描述：将Ack对象解析为xml格式的字符串 java.lang.StringgetCause()           功能描述：在ack中得到出错的原因 java.lang.StringgetCode()          功能描述：在ack中得到出错原因的代码

32、60;java.lang.StringgetRepId()          功能描述： 得到repId，repId对应Notification的id，作为对Notification返回信息标识 java.lang.StringgetType()         功能描述：得到ack的类型 可以是 success、failure voidsetCause(java.lang.String 

33、;cause)           功能描述：在ack中设置出错的原因 voidsetCode(java.lang.String code)           功能描述：在ack中设置出错的代码 voidsetRepId(java.lang.String repId)        &#

34、160;  功能描述：设置repId，repId对应Notification的id，作为对Notification返回信息标识 voidsetType(java.lang.String type)           功能描述：封装ack的类型 可以是 success、failure3.2.5 OneWay对象OneWay对象是对协议部分oneway消息的一种抽象，OneWay提供接口方法如下：方法摘要 voidaddAttribute(java

35、.lang.String key, java.lang.String value)           功能描述：增加attribute.key为字段信息；value为key的对象类型（支持简单对象类型） voidaddData(java.lang.Object keys, java.lang.Object values)           功能

36、描述：增加传输的数据；一个查询出来的bean中的字段需组织成数组. keys 一个bean中所有属性字段；values 每个bean的属性字段的值。 java.lang.Stringencode()           功能描述：将Oneway对象解析为xml格式的字符串 java.util.MapgetAttributes()           功能描述：获取全部属性，属性

37、为键值对 java.util.List<java.util.Map>getDatas()           功能描述：获得复杂数据类型，list中的一个map为一个实体。 java.lang.StringgetName()           name为执行操作的名称+所要操作的对象 voidsetName(java.lang.String n

38、ame)           功能描述：设置oneway的处理类型的名字，name：详见协议文档name命名规范3.3编解码根据协议xml抽象的对象，可以和xml进行转换，编解码部分即实现该功能。解码部分代码位于软件包 com.bupt.transmit.unite.modelConvert的类XmlParser：方法摘要 AckdecodeAck(java.lang.String xml)        

39、   功能描述：解析Ack协议的字符串，转换为Ack对象 NotificationdecodeNotification(java.lang.String xml)           功能描述：解析Notification协议的字符串，转换为Notification对象 OneWaydecodeOneWay(java.lang.String xml)       &#

40、160;   功能描述：解析OneWay协议的字符串，转换为OneWay对象 RequestdecodeRequest(java.lang.String xml)           功能描述：解析Request协议的字符串，转换为Request对象 ResponsedecodeResponse(java.lang.String xml)        &#

41、160;  功能描述：解析Response协议的字符串，转换为Response对象每一个xml的抽象类都提供了encode()方法，用于实体转xml，详见3.2协议对象3.4安全机制为了实现安全机制，包com.bupt.transmit.unite.service.impl下提供了RefreshToken实现安全机制：方法摘要static ResponseallowLogin(Request r)       功能描述：负责当用户的请求为登陆操作时过滤用户的登陆请求。首先判断用户请求的用户名密码

42、是否正确，错误返回login_001错误，正确继续到第2次判断。然后判断用户请求的用户名是否登陆，错误返回login_003错误，正确分配用户令牌。static ResponseallowUse(Request r)           功能描述：主要负责过滤 登陆的用户请求，用户将传递用户的消息令牌。共经过三次判断，第一次：服务器方将验证用户的消息令牌是否正确，错误返回login_002错误，正确则跳到第2次判断。服务器方将验证用户的消息令牌是否过期，错误返回login_0

43、05错误，正确请求跳到第3次判断。服务器方将验证用户的权限是否足够进行该操作，错误返回login_004错误，正确请求正确数据。3.5发送功能客户端负责组织request请求、接收response相应、接收Notification消息、发送对Notification的反馈Ack消息，接收oneway消息。对客户端的操作接口TransmitClientService位于com.bupt.transmit.unite.service下，其实现类TransmitClientServiceImpl位于com.bupt.transmit.unite.service.impl下，接口的主要方法如下：方法摘

44、要 AcksendNotification(Notification notification, java.io.InputStream socketReader, java.io.OutputStream socketWriter)           功能描述：发送notification并且通过阻塞返回ack；用于socket协议 java.util.List<Ack>sendNotification(Notification&

45、#160;notification, java.util.List addressList)           功能描述：发送notification并且通过阻塞返回ack；用于处理http协议 voidsendOneWay(OneWay oneway, java.io.InputStream socketReader, java.io.OutputStream socketWriter)     

46、60;     功能描述：发送oneway；用于socket协议 voidsendOneWay(OneWay oneWay, java.util.List addressList)           功能描述：发送oneway；用于处理http协议 ResponsesendRequest(Request request, java.io.InputStream socketReader

47、, java.io.OutputStream socketWriter)           功能描述：发送request并且通过阻塞获取response对象；用于socket协议 ResponsesendRequest(Request request, java.lang.String Url)           功能描述：发送请求并且通过阻塞获取res

48、ponse对象；用于处理http协议使用方法：步骤一：用户包装好相应的协议模型步骤二：实例化该接口步骤三：使用该接口相应的方法步骤四：接受接口返回值执行自己的业务操作注意：所有发送的目的地址在pertie存储，需使用Destination对象可获取地址信息。3.6接收功能服务器端负责接收request请求、处理request发送response、发送Notification消息、发送oneway消息。对服务器端的操作接口TransmitServerService位于com.bupt.transmit.unite.service下，其实现类TransmitServe

49、rServiceImpl位于com.bupt.transmit.unite.service.impl下，接口的主要方法如下：方法摘要 voidreceiveNotification(HttpServletRequest request, HttpServletResponse response)           功能描述：以http方式接收处理notification voidreceiveNotification(java.lang.String&#

50、160;xml, java.io.OutputStream os)           功能描述：以socket形式的接收处理Notification voidreceiveOneWay(HttpServletRequest request, HttpServletResponse response)           功能描述：以http方式接收处理On

51、eWay voidreceiveOneWay(java.lang.String xml)           功能描述：以socket形式接收处理oneWay voidreceiveRequest(HttpServletRequest request, HttpServletResponse response)           功能描述：以Ht

52、tp方式处理request voidreceiveRequest(java.lang.String xml, java.io.OutputStream os)           功能描述：以socket形式接收处理request注意： 使用socket协议接收时，在服务器端需获得输入流，解析出xml字符串，做为参数；另外，需要获取输出流，做为参数。3.7日常功能为了简化用户的操作，封装了一些常用的操作。这些操作的方法接口位于com.bupt.transmit.un

53、ite.normal包下的UsualRequest类：方法摘要static ResponseloginRequest(java.lang.String username, java.lang.String password, java.io.InputStream socketReader, java.io.OutputStream socketWriter)           功能描述：用户请求登陆操作，由于request请求必须基于登陆的境

54、况下，才能进行相应的操作，所以使用request请求数据时，须使用该方法登陆。用作socket协议。static ResponseloginRequest(java.lang.String username, java.lang.String password, java.lang.String url)           功能描述：用户请求登陆操作，用作http协议。username为远程服务器用户名，password为远程服务器用户密码，url为远程

55、服务器url地址，在程序中调用该接口，即可登陆上服务器。static ResponselogoutRequest(java.io.InputStream socketReader, java.io.OutputStream socketWriter)           功能描述：已经登陆上的远程服务器执行注销登陆操作，用作socket协议。url：已经登陆的URL服务器地址static ResponselogoutRequest(java.lang.St

56、ring url)           功能描述：已经登陆上的远程服务器执行注销登陆操作，用作http协议。4、数据处理机制为了便于用户更加便捷的处理某类操作，我方提供一个方便的接口，让用户可以通过实现这个接口就可以处理用户的某类业务操作。运行原理:服务器在自动处理数据中，会根据协议传输过来的name属性自动调用服务器中的相关类。比如：进行一个登陆操作，协议内容为：<?xml version="1.0" encoding="utf-8"?&

57、gt;<request id="123" name=" BSlogin"> <parameters> <userName>qiyubin</userName> <password>123</password> </parameters></request>解析name字段操作关键字为login,服务器知道这个操作是login而且协议是request协议，则自动反射出类名为com.bupt.transmit.unite.service.request.Login

58、RequestWork然后调用此类进行相关业务操作。接下来介绍的内容为运行机制的使用和如何拓展.4.1处理Request请求的RequestWorkRequest是经常使用的一种请求方式，这个接口就是为了实现程序接受request后进行的操作。接口RequestWork位于com.bupt.transmit.unite.service包下。接口方法如下：方法摘要 ResponsedealRequest(Request request)           功能描述：服务器本地

59、处理request请求，处理完毕后的信息封装成response使用方法：一 路径和命名规范：为了让本程序能够正常运行，本接口的实现类统一实现在com.bupt.transmit.unite.service.request下。命名以 request协议中name为标准，首字母大写后缀为RequestWork如: XxxxRequestWork.二 编写逻辑本方法中的参数为获取到的request请求，所以请程序员从request中提取信息，执行相应的操作，再将信息封装到返回值response中。三 还要做什么？程序编写完毕后，使用者不需要再做什么操作，服务器会在接受该类request自动调用该方法

60、，自动返回给发送方使用示例：package com.bupt.transmit.unite.service.request;import java.util.ArrayList;import java.util.HashMap;import java.util.List;import java.util.Map;import com.bupt.transmit.unite.model.Content;import com.bupt.transmit.unite.model.Request;import com.bupt.transmit.unite.model.Response;import

61、com.bupt.transmit.unite.model.Token;import com.bupt.transmit.unite.service.RequestWork;import com.bupt.transmit.unite.service.config.ConfigData;import com.bupt.transmit.unite.service.impl.RefreshToken;/* * * 功能描述：服务器对request name=login的核心工作类 * * author 漆羽斌 */public class LoginRequestWork implements

62、RequestWork /* * 服务器端login操作 */public Response dealRequest(Request request) / TODO Auto-generated method stubResponse re = RefreshToken.allowLogin(request);if (re = null) String name = request.getName();Content c = new Content();Map m = new HashMap();List<Map> lm = new ArrayList<Map>();c.setContentType(m);m.put("token", "string");Map d1 = new HashMap();d1.put("token", reque