uap6.3分布式传输平台开发接口及关键技术说明

1、NC 分布式传输开发接口及规范版 本号：2.5：基础技术中心-集成产品开发部编制编 制人：黄海泉 ()更新时间：2013.8.9更新日期更新内容作者产品版本文档版本2012.3.16创建文档，加入了总体说明、基本概念、基本假设、资源传输接口及规范、系统信息查询接口、扩展性六个部分的内容。黄海泉6.11.02012.5.21增加 6.2 节-传输资源详情查看接口黄海泉6.11.12012.12.21删去了后续版本不再支持的旧接口的描述黄海泉6.11.22013.3.7增加 4.4 节-资源数据卸载接口黄海泉6.32.02013.3.131、增加“第七章-系统事件”2、移除“第三章 3 节-基本假

2、设-系统节点的与帐套一致。3、第二章 1 节-系统目录-增加了 6.3 版本的系统节点的改变的说明。黄海泉6.32.12013.3.181、更新“第五章 1 节-分布式系统查询接口”改为 6.3 版本的新接口。2、增加“第五章 3 节-分布式系统查询接口”3、更新“第七章 1 节-分布式传输的事件机制”中“分布式系统上下文对象”的获取方式。黄海泉6.32.22013.3.221、更新“第七章 事件”对于系统基础事件的描述。2、增加“第七章 3 节 资源传输层事件” 加入了“传输任务改变事件”黄海泉6.32.32013.4.81、增加“第七章 第 3 节 2 点” 加入“传输任务改变件(Chan

3、ging)”黄海泉6.32.42013.8.91、 “第六章 第 1 节”加入“通用规则设置接口”2、“第七章 第 2 节 系统基础事件”中加入了“系统节点停用事件”和“系统目录改变事件”黄海泉6.32.53、“第七章 事件”中加入了事件的“集群传播”特性的描述目录前言6一、分布式传输总体说明6二、基本概念6系统目录61.资源及资源类型72.传输任务73.三、分布式传输的基本假设8每一个“系统节点”配置的“系统目录”都是相同的81.每一个“系统节点”配置的“资源类型”都是相同的8资源传输接口及规范82.四、资源数据创建接口8资源数据处理接口10资源回执处理接口12资源数据卸载接口131.2.3

4、.4.五、分布式传输系统信息查询接口14分布式系统目录查询接口14资源类型查询接口151.2.分布式系统查询接口153.六、扩展性15资源控制规则的接口及规范151.传输资源详情查看接口172.七、事件171、分布式传输的事件机制172、系统基础事件18系统节点启动/停止事件191)系统节点状态变化事件202)系统节点停用事件203)系统目录改变事件21资源传输层事件214)3、1)传输任务改变后事件(Changed)212)传输任务改变件(Changing)22前言本文档描述了UAP 分布式传输的业务开发接口及规范，面向基于分布式传输实现上层业务的分布式的各领域开发。一、 分布式传输总体说明

5、分布式传输的目标是提供一个与具体业务无关的通用的数据传输通道，实现企业分布式环境下数据传递的需求。分布式传输是基于消息中间件的，其数据传输的基本模型采用“发布-订阅”模型，数据发送方发送数据的过程是一个消息发布的过程，数据接收方通过订阅消息的方式接收数据。数据的发送与接收之间是异步进行的。二、基本概念系统目录1.“系统目录”来描述了完整的企业系统的每一个独立的分系统之间的拓扑结构。“系统目录”中的每一项称为一个“系统节点”。在分布式传输中，系统目录描述的是一个无向网状拓扑，每一个系统节点在通讯上都是对等的，相互之间都可以传输数据。在一个分布式系统网络当中，每个系统节点都通过“系统目录”维护了一

6、份分布式系统网络拓扑图。在一份“系统目录”中，标识了一个当前系统节点，如下图。一个分布式系统节点从逻辑上对应于一个 NC 系统（帐套）。这种对应关系在6.1 版本时通过帐套和节点的设置相同的值来建立的。从 6.3 版本开始，取消了通过帐套和节点一致性的配置要求，一个分布式系统节点对应到一个系统数据源上。使用该数据源的 NC帐套将自动地被作为一个分布式系统节点，该帐套管理下的当前分布式系统节点，也就是系统目录中“数据源”与当前帐套的“数据源”相同的系统节点。从 6.3 版本开始，配置一个分布式系统目录时，需要指定其对应的数据源。一份系统目录中不能配置两个数据源相同的节点。如果“系统目录”中未配置

7、有与当前帐套数据源相同的系统节点，则当前帐套无法启用分布式传输的相关功能。NC01 的系统目录当前NC01NC02NC03NC01NC03 的系统目录NC02 的系统目录NC01NC01MQNC02当前NC03NC02NC03当前NC03NC02资源及资源类型2.分布式传输本身是业务无关的，将要传输的数据都通称为“资源”，并通过“资源类型”分类标识不同的资源数据。“资源类型”定义了一种“资源”的数据获取接口、接收处理接口、回执处理接口等相关接口。“资源类型”由相关的业务开发进行配置。传输任务3.“传输任务”定义了定时执行的资源发送操作，将一种或多种资源发送给指定的一个或多个系统节点。三、 分布

8、式传输的基本假设1.每一个“系统节点”配置的“系统目录”都是相同的在分布式系统环境中，一个“系统节点”通过“系统目录”识别整个分布式系统网络。两个系统节点之间能够进行通讯的前提条件是它们各自的“系统目录”都配置了对方的系统编码。因而，“系统目录”的一致性由实施阶段保证，分布式传输本身查和各个“系统节点”之间的“系统目录”的一致性。2.每一个“系统节点”配置的“资源类型”都是相同的每一个“系统节点”中都有一份相同的“资源类型”列表，由业务开发在开发阶段预置。四、 资源传输接口及规范资源传输的基本过程包括发送、接收、回执处理三个环节，分布式传输在这三个环节都定义了接口，由具体业务实现针对特定资源类

9、型的业务逻辑。这些接口包括：a、在发送方调用的资源数据创建接口；b、在接收方调用的资源数据处理接口；c、在发送方调用的处理回执处理接口。1. 资源数据创建接口数据资源创建接口用于在分布式传输执行任务时获取资源数据。当发送资源数据时，分布式传输将实例化一个到资源的接口实现类的对象，调用接口方法获取具体数据。接口类型分布式传输在V6.1 版本定义的资源数据创建接口：nc.itf.uap.distribution.restrans.ITransResourceCreator无状态的接口实现接口的实现要求是无状态的，分布式传输在每次发送资源时都会创建该资源的数据创建实现类的实例，业务开发不应该试图通过

10、实现类的成员去维护那些在该资源的多次数据创建操作之间的状态数据。资源数据的结构通过资源数据创建接口返回的对应于一个资源数据包的资源数据被定义为类型 nc.itf.uap.distribution.restrans.TransResourceData ；资源数据创建接口要求返/*传输资源数据创建接口；*注：分布式传输V6.1 新增接口， 将之前接口中提供的参数和多种返回值都以对象进行封装，并且取代原来的单一资源包创建接口和大数据量的多资源包创建接口， 以提供更简洁的实现和更灵活的扩展；* ver6.1author haiq*/publicerface ITransResourceCreator

11、/*返回资源数据；*当实现者需要将大数据量资源进行分包时，的实现是，*在迭代器的每一次 next 操作时再创建数据，以避免占用过大的内存；*param contextreturnthrows BusinessException*/public Iterator getResDatas( ITransResCreationContext context) throws BusinessException;回一个TransResourceData 的迭代器 Iterator。一项资源数据由两部分组成：a、数据内容（Dontent）；b、规则内容（RuleContent）；在 TransResour

12、ceData 类型上定义了与此对应的两个属性。ontent 和 RuleContent 的数据结构均为 FileContentVO 。一个 DFileContentVO 由两部分组成：字节数据(byte)和属性(Properties) ；字节数据为要传输的资源数据；属性为传输该资源包时随附传输的由 Key-Value 组成的Properties。大数据量资源的分包发送新的数据创建接口通过迭代器 Iterator从业务实现中获取资源数据。迭代器的每一个元素将被创建为一个独立的资源包文件（pkg）进行发送。建议 Iterator的实现者在每次 next 操作时才分步地生成一个资源分包数据，而不是生

13、成所有数据的列表返回，以减少内存占用。2. 资源数据处理接口资源数据处理接口是接收方在接到资源数据之后，由分布式传输调用执行数据处理操作。接口类型分布式传输在 V6.1 版本定义的处理接口数据处理接口：nc.itf.uap.distribution.restrans.ITransResourceProsor无状态的接口实现接口的实现要求是无状态的，分布式传输在收到资源开始处理时都会创建该资源指定的处理实现类的实例，业务开发不应在接口的实现类中通过类成员维持那些需要在多次处理操作之间需要保持的状态数据。大数据量分包发送的资源的处理与资源数据创建接口采用迭代器 Iterator来获取由具体业务实

14、现的分 包数据 一样 ，资源 数 据的处 理接口 也采用 迭代器 Iterator将接收到的资源包传递给业务实现类。/*资源数据处理接口；*author haiq*/publicerface ITransResourceProsor /*处理接收到的资源数据；*对于大数据量的资源分包数据，建议实现者不要全部把迭代器的所有元素都出来，以免占用过大内存；而是分步进行，处理一个元后再下一个元素进行处理； 实现者在执行完成处理之后，以返回值的形式返回处理回执数据；*如果返回 null，则传输会给发送方返回一个表示处理成功的默认回执；*如果处理过程发生异常，则传输会给发送方返回一个表示处理失败的默认回执

15、；*param transResDatasparam contextreturnthrows BusinessException*/ReceiptData pros(Iterator transResDatas, ITransResProsContext context) throws BusinessException;迭代器的迭代长度以及顺序与资源创建接口产生的数据一致。其中的每一项元素对应于磁盘上的一个资源包文件，只有当迭代器行进到该项元素时才会从磁盘加载资源数据。因此，建议实现者不要地将迭代器的所有元素都出来维持在内存中。回执数据的返回处 理 回 执 的 通 过 接 口 的 处 理 方

16、 法 (pros) 的 返 回 值 返 回 一 个nc.itf.uap.distribution.restrans.ReceiptData 的实例。如果返回 null，则传输会给发送方返回一个表示处理成功的默认回执。如果处理方法发生异常，则传输会给发送方返回一个表示处理失败的默认回执。3. 资源回执处理接口资源处理回执接口是在发送方接收到资源接收方回复的处理回执时，由分布式传输调用以通知具体业务实现代码获知先前发送的资源被接收方处理的结果。接口类型分 布 式 传 输在V6.1版 本 定 义 的 回 执 处 理 接 口 ：nc.itf.uap.distribution.restrans.ITra

17、nsResReceiptProsor无状态的接口实现接口的实现要求是无状态的，分布式传输在收到资源处理回执时会创建该资源类型指定的回执处理实现类的实例，业务开发不应在接口的实现类中通过类成员维持那些需要在多次处理操作之间需要保持的状态数据。4. 资源数据卸载接口资源数据卸载接口是分布式传输在发起一次数据卸载操作卸载某个特定资源时被调用，用以通知具体业务实现代码将该资源的不需要的相关数据通过接口提供的输出流输出到磁盘中，并将其从数据库删除。接口类型分布式传输 在V6.3版本定义 的 资源数据卸载接口 ：TI OZL GV JOYZXOHZOUT XKYZXGTY /:XGTY8KYUXIK;TR

18、UGJKX/*传输资源回执的处理接口；*此接口在发送方系统被调用，当发送方系统收到接收方在处理了传输资源之后返回的处理回执时，将触发一次调用；*author haiq*/publicerface ITransResReceiptProsor /*收到回执；*param receipt回执数据；param context回执处理上下文；*/public void onReceiptReceived(ReceiptData receipt, ITransResReceiptProcContext context);调用时序在卸载资源时，会先调用资源类型的数据卸载接口实现类的实例卸载该资源相关的上层

19、业务数据，之后再对传输上的资源数据进行卸载。无状态的接口实现接口的实现要求是无状态的，分布式传输在卸载资源数据时会创建该资源类型指定的数据卸载实现类的实例，业务开发不应在接口的实现类中通过类成员维持那些需要在多次处理操作之间需要保持的状态数据。五、 分布式传输系统信息查询接口1.分布式系统目录查询接口接口类型：GV OZL JOYZXOHZOUT ZUVURUM_ /*OYZ9_YZKS4UJK7KX_/*传输资源卸载接口；*当资源类型了此接口的实现时，系统在卸载资源数据时将实例化该实现类，并调用 unload 方法；*author haiq*/publicerface ITransResou

20、rceUnloader /*卸载资源；*param context*/public void unload(ITransResourceUnloadContext context);可以查询当前子系统所处分布式环境下的整个系统拓扑及各个子系统的信息。注：6.1 版本的 nc.itf.uap.distribution.restrans.IDistSystemNodeQuery 接口已不使用。2.资源类型查询接口接口：nc.itf.uap.distribution.restrans.ITransResourceQuery可以查询当前子系统所的资源类型的信息。3.分布式系统查询接口接口：uap.di

21、stribution.sys.ISystemQuery提供获取当前分布式系统上下文对象、检查当前是否运行于分布式系统上下文的操作。六、 扩展性1.资源控制规则的接口及规范1) 通用规则V6.1 开始将资源类型抽象为接口nc.itf.uap.distribution.restrans.ITransResourceType，并为资源类型（ITransResourceType）定义了 Properties 属性，这些属性由字符串的Key-Value 组成。分布式传输了这些 Key-Value 属性数据的持久化。业务上针对资源类型的通用控制规则通过资源类型的属性保存为字符串的Key-Value ，由分

22、布式传输其持久性。资源类型的属性仅存在于本地子系统，而不会随着资源传输而在系统节点间传输。目前分布式传输在资源类型属性(TransResourceProperties)上设置了 4 个预定义属性，默认值为 true：可增加TransResourceProperties.KEY_ADD_ENABLE可修改TransResourceProperties.KEY_UPDATE_ENABLE可删除TransResourceProperties.KEY_DEL_ENABLE重复数据可覆盖 TransResourceProperties.KEY_OVERRIDE_ENABLE2) 通用规则设置接口nc.i

23、tf.uap.distribution.restrans.ITransResourceTypeManageExtend此接口用于批量设置资源类型的通用规则（可新增、可修改、可删除、重复数据可覆盖），上层业务可以根据需要在某些时机通过该接口为其相关的资源类型设置符合其业务要求的规则。3) 自定义规则如果需要针对资源类型定义更加特殊、更加丰富的控制规则，则需要具体的业务开发自行定义所需的控制规则的数据结构，并自行自定义控制规则数据的持久化。分布式传输仅定义了一个在实施态下编辑资源类型的自定义规则的 UI接口nc.itf.uap.distribution.restrans.ITransResExte

24、n需要定义一个 UIPanel 并实现此接口。PropertiesEditor，具体业务4) 规则的传输通过资源类型的属性定义的通用控制规则分布式传输为资源类型的控制规则随着资源包的发送而传输到目的系统提供了，这就是通过资源数据的规则内容（RuleContent）进行传输。当具体业务实现资源数据创建接口时，将自行把规则数据写入到RuleContent 中，接收方的处理接口的实现者需要对 RuleContent 进行对应的。2.传输资源详情查看接口1) 用途“传输资源详情查看接口”是用于共具体业务开发任务实现查看传输任务产生的资源对应的业务信息。2) 实现方式“传输资源详情查看接口”包括三部分：

25、a)资源包详情查看节点；显示资源包对应的业务信息的 NC 节点，通过资源类型。b)回执详情查看节点；显示资源包对应的回执信息的 NC 节点，通过资源类型。c)传输资源查看对象nc.pub.uap.distribution.restrans.TransResourceBrowser此类型定义了传输资源对应的任务方和接收方信息、资源包数据、回执包数据等信息，在打开“资源包详情查看节点”和“回执详情查看节点”时通过ode.ui.FuncletInitData 传递给节点，节点在打开时通过该对象展现相应的业务数据内容；3.预置任务执行接口七、 事件1、分布式传输的事件机制分 布 式 传 输的 事 件接

26、 口 都 需 要 继 承 自uap.distribution.event.IEventListener 接口。一个器需要指定事件subject）和器对象器之后会返回一个 IEventListenerHandle对象，该对象用于标识每个已的器对象，通过EventListenerHandle 对象者可以调用 unregist 方法注销事件。*需要注意的是回收器回收，一旦者必须要持有此IEventListenerHandle 对象以避免其被回收器试图回收 IEventListenerHandle 对象便会导致事件器被自动地注销。2、系统基础事件系统基础事件是指由ISystemContext 管理的事

27、件，这些事件都。地通过 ISystemContextISystemContext 是一个分布式系统节点中所有对象的根对象。一个运行时的分布式系统节点在系统中都有唯一对应的ISystemContext 对象。系统事件的需要通过 ISystemContext 对象的 addListener 方法进行。ISystemContext .addListener 方法需要提供两个参数：事件subject 和 监实例listener。对于subject 参数，分布式传输定义的系统事件都会一个相应的subject 常量，事件器时需要采用该值。ISystemContext 的获取方式有两种:1)通过预置系统启动

28、器（uap.distribution.sys.ISystemStartupListener）在分布式系统启用运行时得到（详见下一节：“系统节点启动/停止事件”）。2)通过 NCLocatetInstance()SystemQuery.class).getCurrentSystem() 取得。.lookup.distribution.sys.I1) 系统节点启动/停止事件系统节点启动/停止事件是在服务器启动或停止时，或者通过分布式系统目录建立或销毁分布式系统节点时触发。与其它的系统事件不同，启动/停止事件可以通过系统事件表（_listenerreg）各个领域的器实现。通过启动事件可以获得先于分布

29、式传输的传输任务、资源等传输操作的触发点，执行某些业务状态的初始化操作。/*ISystemContext 分布式系统上下文；分布式系统上下文是一个运行着的分布式系统节点的根对象；与系统节点相关的对象都由其。* ver6.3author haiq*/publicerface ISystemContext /*事件器；*事件器的者需要持有时返回的 IEventListenerHandle 使其不被回收器回收才能确保器的有效；*一旦 IEventListenerHandle 不再被任何对象持有而被回收器回收时将自动注销对应的事件器；*持有者也可以通过 unregist 方法主动注销器；*param

30、param param subject 事件；param listener 事件器；return*/public IEventListenerHandle addListener(String subject, IEventListener listener);系统节点启用事件a)接口：uap.distribution.sys.ISystemStartupListener事件：ISystemStartupListener. EVENT_SUBJECT 常量集群：全局系统节点停止事件b)接口：uap.distribution.sys. ISystemShutdownListener事件：ISys

31、temShutdownListener.EVENT_SUBJECT 常量集群：全局系统节点状态变化事件2)此事件反映分布式系统节点的启用/停用状态改变。当分布式系统节点被系统管理员在“分布式系统目录”中执行“启用/停用”操作之后将触发此事件通知。接口：uap.distribution.topology.IDistSystemNodeSeChangedListener事件：IDistSystemNodeSeChangedListener.EVENT_SUBJECT 常量集群：全局系统节点停用事件3)此事件表明分布式系统节点正在被停用。当分布式系统节点被系统管理员在“分布式系统目录”中执行“停用”

32、操作时触发。与“ 系 统 节 点 状 态 变 化 事 件 ” 不 同 ， 通 过 此 事 件 的 参 数SystemNodeDisableEvtArgs 的 setCancel 方法将 cancel 属性置为true 可以停用操作。如果将 cancel 置为 true，则同时需要设置 cancelReason 属性以指明停用操作的原因。接口：uap.distribution.topology.IDistSystemNodeDisableListener事件：IDistSystemNodeDisableListener.EVENT_SUBJECT 常量触发时机：在“停用”操作触发之后，“系统节点状态变化事件”触发之前。集群：单机；仅在收到操作请求的主机上触发。4) 系统目录改变事件此事件表明当前分布式系统节点的分布式系统目录正在修改更新。只有当前系统启用过分布式才会存在此事件，在此情况下，如果当系统管理员修改分布式系统目录后执行保存时触发事件。通过此事件的参数 DistSystemDirectoryUpdatingEvtArgs 的setCancel 方法将cancel 属