serviceUi操作手册.docx

ServiceUi使用手册1.概述ServiceUi是一套用于增强Bosent服务调用功能的Bosent应用，提供了三个主要功能：生成WebService种子对象、服务测试和输入参数校验。1. ServiceUi的服务测试功能：serviceUi可以通过读取扩展的服务用户接口配置文件自动生成测试页面，能够提供更友好的界面，并且可以将Map或List类型的参数展开。2. ServiceUi的输入参数校验功能：该校验是对输入参数格式进行校验，参数的格式可在扩展的服务用户接口配置文件中定义。3. ServiceUi生成WebService种子对象的功能：可以通过ServiceUi将WebService种子对象(封装了对服务的调用)发布成WebService，部署到NetWeaver服务器上。2.ServiceUi的存放位置serviceUi是bosent下的一个扩展应用，其配置文件出于在eclipse环境和NetWeaver IDE环境的初始化自适应的目的，其放置位置需要放在各应用组应用目录下的config/serviceUi目录下，并且config目录需要加入到源路径中：如每个应用对应一个或多个serviceUi_*.xml配置文件，例如：merchant应用的配置文件为serviceUi_customer.xml。3. 扩展服务用户接口配置文件3.1 元素及其扩展 serviceUi_*.xml配置文件的根元素是，其作用是：l 包含元素，实现了按应用分组service配置，便于维护配置文件。l service-group对应一个WebService种子对象，其下包含的service对应一个WebService种子对象的方法。l service-group对应测试页面上的一个一级菜单，其下包含的service对应一个菜单项。例子：有如下属性：l name : 服务组名，全局唯一。同时作为默认的WS种子对象的类名。l title : 标题。测试页面菜单标题。WS种子对象源码的类注释内容。l class-name : WS种子对象的类名。必填，此属性的值为WS种子对象的全类名。此属性将生成的种子对象存放的位置交由用户自己决定。各元素详细扩展情况可参照2.3节：元素属性表中的说明。 3.2 和元素及其扩展serviceUi.xml扩展了和元素的属性，增加了显示和校验相关的配置，注意：元素不是以Bosent服务为单位，而是以WebService为单位，其下所属的元素的配置也是以WebService的接口定义为准。主要的扩展配置如下：l 和元素title属性，用于配置在测试页面中服务与参数显示的标题。l 元素other-name属性，因为存在多个WebService调用同一个Bosent服务的情况，所以该属性用做生成的WebService种子对象服务方法名，同时也是元素的唯一标示。原有的name属性仍然表示一个Bosent服务名。l 属性other-name属性，用于对外发布的WebService接口和内部使用的Bosent服务接口命名不一致的情况。l class-name属性，用以避免类命名冲突。l 格式校验相关的属性，如值长度length。l 类型为Map或List的参数如果包含预先定义的内部结构，可以在该参数的元素下嵌套子元素来配置参数的内部结构。嵌套层数没有限制。l 类型为Map或List的参数如果不包含内部结构，即自由Map或自由List，则只需指定该参数的元素type属性为Map或List，并不再嵌套子元素即可。l 各元素详细扩展情况可参照2.3节：元素属性表中的说明。以服务findAllAsList为例，原服务配置文件内容如下： 3.3 标示入参中的业务字段入参中有些参数是包含业务含义的，如前台流水号，渠道日期等，但是各个组对这些入参的命名却并不一致。为此，attribute元素设置了一个属性transactionlog-field-name，用于标示该参数是哪一个业务字段。目前有效的业务字段名包括：业务字段名称字段说明clientSerialNumber前台流水号organizationCode组织机构号teller柜员clientDate渠道日期channel渠道请在配置serviceUi配置文件的时候将需要标示为业务字段的参数上加上指示它业务含义的名称，如下图所示：通过这样的配置，serviceUi就能够知晓哪个参数是标示什么业务字段，就如上例，originatePartyId就是标示organizationCode（组织机构号）；origianteTellerId就是标示teller(柜员号)。3.4 元素属性表为满足各应用组提出的所有需求，对扩展服务用户接口配置文件的属性定义非常的多，有些属性甚至是专为某一个应用组而做的，使用者不必全部记牢，但需有所了解，知道serviceUi提供了哪些功能配置，具体需使用时可查阅文档，粗体字标示的属性是较为重要的，需要用户必须记住。l 元素功能说明属性service-group服务组属性名必选属性说明name是服务组名，全局唯一。title否服务组标题。不填为name。测试页面一级菜单标题。class-name是WebService种子对象全类名(包括包名)。l 元素功能说明属性service服务配置属性名必选属性说明name是Bosent服务名。标示该WebService需要执行哪个Bosent服务以实现功能。other-name否WebService种子对象服务方法名。不填默认为Bosent服务名。title否服务标题。不填为name。validate否输入参数校验标识，默认为true。input-mapbean-package否输入接口Bean包名，默认为WebService种子对象包名。output-mapbean-package否输出接口Bean包名，默认为WebService种子对象包名。input-mapbean-class-name否输入接口Bean类名，默认为WebService种子对象名后加“Input”。output-mapbean-class-name否输出接口Bean类名，默认为WebService种子对象名后加“output”。file-log否文件型服务日志开关，默认为关db-log否数据库型服务日志开关，默认为关，此开关与流水号判重有关，对外服务接口应该都开启。trace-stack-log否服务跟踪堆栈日志开关，默认为关allow-same-serial-number否允许重复流水号开关，默认为关，此开关与db-log开关有关，可让调用失败的服务使用同一流水号再调一遍。debug否服务的监控日志开启，默认为关debugLevel否服务监控的日志级别，默认为infodebugExpression否服务监控的过滤表达式auto-change-name否字段名自动命名开关，默认为开，开启此开关，对List类型参数，会自动在其配置的名称后面加一个“s”。business-log否业务日志开关，默认为开dump否服务发生异常是否dump的开关，默认为开is-synchronize否是否同步服务标示，默认为同步服务，此开关仅在生成webservice种子对象时有用，可控制生成异步调用的webservice。add-user-login否往入参中设置userLogin参数的开关，默认为开l 元素功能说明属性validator-name自定义校验器配置属性名必选属性说明无-直接将校验器全类名写在元素内容中。l 元素功能说明属性description服务描述信息属性名必选属性说明无-直接将服务描述信息写在元素内容中。l 元素功能说明属性transactionlog-field业务字段映射关联属性名必选属性说明name是业务字段名Key是业务字段对应的参数KEY值l 元素功能说明属性attribute参数配置属性名必选属性说明name是参数名。other-name否WebService种子对象接口参数名。class-name否有扩展子参数的节点需要此参数用于制订扩展生成的MapBean的类名，避免类命名冲突。不填的情况下，默认的MapBean类名为服务方法名+参数别名。type是 参数类型。mode是参数的输入输出标示。optional否参数是否必输，输入参数该属性必选。default-value否参数的默认值，仅用于serviceUi页面测试。fixed-value否参数的固定值，配置此属性后，该参数将不作为接口对外，并总是赋值为此配置填入的值。length否参数的长度，用于数据校验。strict-length否参数长度校验方式，true表示输入值长度需与length值完全相等，false表示输入值长度不能超过length值。默认为false。scale否参数的精度，用于数据校验。transactionlog-field-name否映射的业务字段名charType否参数的字符类型，用于数据校验。pattern否验证参数格式的正则表达式。l 元素功能说明属性value-range参数取值范围配置属性名必选属性说明type是取值范围类型，有value和entity两种。l 元素功能说明属性value参数可取值配置。属性名必选属性说明value是参数的可取值。description否参数可取值的描述。l 元素功能说明属性value参数可取值配置，从实体中获取。属性名必选属性说明key-field-name是主键参数名。description否主键参数描述。entity-name是用于获取取值范围的实体名。 4生成WebService种子对象4.1 生成WS种子数据serviceUi提供了WebService种子对象生成器用于生成向NetWeaver服务器部署的WebService种子对象，要将Bosent服务生成其对应的WebService种子对象需要该配置扩展的服务用户接口配置文件。对于包含有预先定义好内部结构的Map和List类型的参数，需要在配置文件的节点下再嵌套子节点，以描述其内部详细结构，否则，该参数将被当做自由Map或自由List参数看待。同时，最好自己定义节点下的class-name属性以指定由Map或List类型参数扩展生成的MapBean的类名，默认的情况下，为了避免类命名冲突，扩展生成的MapBean的类名为服务方法名+参数别名拼接而成。由Map或List类型参数扩展生成的MapBean将以嵌套类的形式放在最上层MapBean中。每一个MapBean中均包含一个toMap()方法和一个fromMap()方法用以使参数在JavaBean和Map形式中相互转换，另外最上层MapBean中还有一个toString()方法，该方法返回一个XML格式的字符串，显示当前参数中各属性的值。生成WebService种子对象的步骤如下：1. 确保服务用户接口配置文件放到正确的位置（详见本手册第2节所述）。2. 新增eclipse的运行项：菜单 Run-Run Configurations，选择Java Application，增加一个运行项，Main Class 设置为:com.giantstone.bosent.serviceui.webservice.generator.WebServiceSeedObjectGenerator3. 修改参数：选择Arguments面板，输入如下参数：n WebService种子对象的源包路径。n WebService种子对象生成模式标示：“-a”表示将配置文件目录下的所有已定义的服务组全部生成WebService种子对象，“-s”表示仅生成指定的服务组的WebService种子对象。此标签固定为“-s”；n 服务组名：指定要生成种子对象的服务组名。如下图所示：4. 点击Run按钮，如执行成功则控制台会输出生成的种子