SG-UAP_V3 0 0_高级开发手册_分册5 平台功能扩展

SG-UAP高级开发手册国家电网公司应用系统统一开发平台（SG-UAP V3.0.0）高级开发手册5.平台功能扩展国网信息通信产业集团研发中心2017年8月目录1MX展现框架扩展31.1概述31.2建立MX框架扩展模块41.3用MXFramework的格式扩展控件51.4非MX规范方式控件扩展71.5添加/替换主题资源： 样式、图片、国际化等91.6接入自定义开发控件/页面101.7自定义登录页面及主页102日志管理扩展132.1概述132.2日志管理模块扩展方法143异常管理扩展183.1概述183.2自定义异常的提示页面193.3自定义服务端异常类型194工具类的自定义开发204.1概述204.2自定义开发工具类215BPM任务列表的自定义扩展335.1概述335.2任务列表的自定义扩展345.2.1服务端方法自定义开发345.2.2客户端方法的自定义开发405.3流程接口与服务说明445.3.1BPM集成模块接口（egrate.bpm.api）445.3.2BPM集成模块接口（egrate.bpm）455.3.3BPM模块（org.sotower.bpm.api）475.3.4Web服务47修订记录版本号修订说明修订人修订时间审核人1.2创建，修正李郑2013/04/281.5修订章节1.4节和5.3节李郑2013/06/211.5修订章节1.5节李郑2013/07/05SG-UAP平台功能扩展1 MX展现框架扩展1.1 扩展原则1.1.1 最小化原则通常情况下，通过新建MXFramework的扩展模块项目来对前端框架进行扩展，扩展模块只需要包含所需要扩展的文件（脚本文件、样式文件等），切记不要把整个MXFramework的拷贝过来。1.1.2 继承扩展原则当MXFramework提供的控件满足大部分用户需要的时候，只需要对其进行继承扩展，以满足部分个性化的需求。1.1.3 组合扩展原则当一个通用组件涉及到俩个以上控件组合实现的时候，使用组合扩展方式。1.1.4 面向接口扩展原则当用户扩展一个现有控件的时候，应当针对公共接口和保护方法扩展，切记不要重写该控件，如需重写请创建一个全新的控件。1.2 建立MX框架扩展模块建立MX框架扩展模块包括以下几个步骤：1. 创建模块扩展项目2. 扩展项目名称可自定义，然后下一步进行指定扩展的mx模块bundle，在Plug-in ID一行点击Browse“浏览”按钮，在弹出的对话框中找到com.sgcc.uap.mxframework，选中后点击“确定”。3. 完成这两步后，mxframework的扩展模块就建立成功了。1.3 用MXFramework的格式扩展控件当MXFramework的控件不能满足项目组需要时，项目组可以使用MXFramework的格式来扩展控件，以达到满足项目组需求的目的。首先需要建立与MX相同的目录结构，即在扩展模块下建立mx文件夹，然后在其下建立scripts/editors目录，editors为平台已有的目录，因此在其下面建立SampleTextEditor.js即依照平台MX的格式进行控件扩展。如下所示：SampleTextEditor为继承于TextEditor的具有自定义功能的控件。$ns(mx.editors);mx.editors.SampleTextEditor = function() var me = $extend(mx.editors.TextEditor); var base = ; me.text = null; me.valuelength = 0; base.init = me.init; me.init = function() base.init(); ; me.setText = function(p_text) me.textMode = p_textMode; ; me.setMaxLength = function(p_maxLength) me.valuelength = p_maxLength; ; me.endOfClass(arguments); return me; 由于我们是对MX框架的扩展，因此在使用方式上，扩展后的控件与MX控件并无迥异，如下所示：$import(mx.editors.SampleTextEditor);var sam = new mx.editors.SampleTextEditor();p_page.addControl(sam);1.4 非MX规范方式控件扩展 非MX规范方式扩展同样需要在mx/scripts目录下，可以建立自己定义的文件夹，例如extd，然后在此文件下定义扩展的组件，如下图所示。 扩展可以继承已有控件并对多个控件进行组合使用，示例代码如下：$ns(mx.extd);$include($theme/extendcomp.css);mx.extd.ExtendComp = function()var me = $extend(mx.containers.Container);var base = ;me.dataGrid = null;me.toolBar = null;base.init = me.init;me.init = function() base.init(); _init();function _init() me.dataGrid = $instanceOf(me.dataGrid, mx.datacontrols.DataGrid) ? me.dataGrid: (new mx.datacontrols.DataGrid(me.dataGrid); me.toolBar = $instanceOf(me.toolBar, mx.controls.ToolBar) ? me.toolBar: (new mx.controls.ToolBar(me.toolBar); me.addControl(me.toolBar); me.dataControl(me.dataGrid); return me.endOfClass(arguments); 由于我们是对MX框架的扩展，因此在使用方式上，扩展后的控件与MX控件并无迥异，如下所示：$import(mx.extd.ExtendComp);var ext = new mx.extd.ExtendComp();p_page.addControl(ext);1.5 添加/替换主题资源： 样式、图片、国际化等 MXFramework框架提供的以主题库为单位的样式，默认提供了default、aero、ie67三套主题库，用户可以通过页面的配置”theme”来改变使用的主题库。 用户如果需要改变框架的主题风格和控件样式，可以在扩展模块中mx/resources/themes定义自己的主题库，例如这里我们建立了android主题库，可以在该文件下，给出整体一套控件的样式库。 其中，images文件夹放置了控件中需要使用的图片。主题库的样式文件可按照MXFramework给出的默认的两套主题库的基础上进行修改，关于控件样式的调整及修改细节可以参考文档SG-UAP_V1.5_高级开发参考手册_2.客户端开发的样式主题开发及应用相关内容。需要提醒的是在theme.css中引入了当前样式库的所有css，如果用户的扩展控件扩展了css文件，则务必将扩展控件的css同样在theme.css引入，这样才可以保证扩展控件的css可用。关于MXFramework中默认使用的通用图标，可以用同样的方式在扩展模块的mx/icons文件夹下以相同名称的图片来达到修改图标的目的。主要通过以下三种方式进行样式扩展。 默认扩展方式。例如：TabControl控件默认的标签头是在顶部，我们需要标签头在底部，修改的样式文件如下:.mx .tabControl #headbottom: 0px;top: auto;height: 33px;.mx .tabControl #bodybottom: 32px;top: 0px;padding: 5px;.mx .tabControl #head aborder-bottom: 1px solid #898C95;border-top: none;margin-top: 0px;height: 33px;background:url(images/tab_control_button_bg.png);.mx .tabControl #head a:hoverborder-top:none;color: #FFFFFF;background:url(images/tab_control_button_selected.png);.mx .tabControl #head a.selectedtop: 0px;height: 33px;border-top: none;border-bottom: 1px solid #898C95;color: #FFFFFF;background:url(images/tab_control_button_selected.png);.mx .tabControl #head a.selected:hoverborder-bottom:1px solid #898C95;border-top:none;需要注意的是，扩展默认样式的时候，样式文件中须要包含未修改部分和修改部分，因此默认样式扩展缺乏一定的灵活性，并且代码冗余。 通用扩展方式。默认样式扩展是对平台已有样式文件的修改，这种修改会应用到所有模块项目中。当用户需要灵活配置扩展样式时，默认样式扩展方式便无法实现。例如：用户需要在模块1中使用标签头在底部的TabControl,而在模块2中使用默认的标签头在顶部的TabControl，如果采用默认扩展方式便无法实现了。通用样式扩展是指在一个模块项目新建一个通用扩展Weblet，在这个通用扩展Weblet中定义扩展样式，而需要运用该扩展样式的Weblet需要在注册时添加对通用扩展Weblet的依赖。例如：我们通过通用样式扩展方式修改TabControl标签头的位置。首先，需要新建一个通用扩展Weblet，例如Ext；然后在resources/themes/aero中新建一个TabControl.css文件，文件内容如下：.ext .tabControl #headbottom: 0px;top: auto;height: 33px;.ext .b1 .ext .b2 .ext .tabControl #bodybottom: 32px;top: 0px;padding: 5px;.ext .tabControl #head aborder-bottom: 1px solid #898C95;border-top: none;margin-top: 0px;height: 33px;background:url(images/tab_control_button_bg.png);.ext .tabControl #head a:hoverborder-top:none;color: #FFFFFF;background:url(images/tab_control_button_selected.png);.ext .tabControl #head a.selectedtop: 0px;height: 33px;border-top: none;border-bottom: 1px solid #898C95;color: #FFFFFF;background:url(images/tab_control_button_selected.png);.ext .tabControl #head a.selected:hoverborder-bottom:1px solid #898C95;border-top:none;最后将样式应用到相应的Weblet中，我们需要在Weblet的注册文件中添加对Ext的依赖，如下所示：mx.weblets.WebletManager.register( id: DefectManage, name: 缺陷管理, requires: PMSExtention/ext, bpm/bpmintegrate, onload: function(e) , onstart: function(e) var mvc = new DefectManage.views.MainViewController(); e.context.rootViewPort.setViewController(mvc); );同时，在视图控制器的me._onactivate方法中添加以下代码:me.getView().$e.parent().addClass(ext);值得注意的是，通用样式扩展的样式文件仅仅包含修改的部分，不需要包含未修改的部分，因此通用样式扩展不存在样式文件内容冗余，使用更加灵活。 Weblet局部样式扩展。Weblet样式扩展即在当前Weblet中定义样式扩展文件。该扩展样式仅在当前Weblet使用。仍然以扩展TabControl为例。首先在Weblet（DefectManage）的resources/themes/aero中新建一个TabControl.css文件，文件内容如下：.DefectManage .tabControl #headbottom: 0px;top: auto;height: 33px;.DefectManage .toolbaritem divbottom: 0px;top: auto;height: 33px;.DefectManage .tabControl #bodybottom: 32px;top: 0px;padding: 5px;.DefectManage .tabControl #head aborder-bottom: 1px solid #898C95;border-top: none;margin-top: 0px;height: 33px;background:url(images/tab_control_button_bg.png);.DefectManage .tabControl #head a:hoverborder-top:none;color: #FFFFFF;background:url(images/tab_control_button_selected.png);.DefectManage .tabControl #head a.selectedtop: 0px;height: 33px;border-top: none;border-bottom: 1px solid #898C95;color: #FFFFFF;background:url(images/tab_control_button_selected.png);.DefectManage .tabControl #head a.selected:hoverborder-bottom:1px solid #898C95;border-top:none;最后引入扩展样式，需要在Weblet的onload事件中引入扩展样式文件，mx.weblets.WebletManager.register( id: DefectManage, name: 缺陷管理, onload: function(e) DefectManage.include($theme/tabControl.css); , onstart: function(e) var mvc = new DefectManage.views.MainViewController(); e.context.rootViewPort.setViewController(mvc); );同时，在视图控制器文件的me._onactivate方法中添加以下代码:me.getView().$e.parent().addClass(DefectManage);同样，Weblet样式扩展中的样式文件仅包含修改的样式部分。国际化（internationalization）又称为i18n。软件的国际化，要使它能同时应对世界不同地区和国家的访问，并针对不同地区和国家的访问，提供相应的、符合来访者阅读习惯的页面或数据。当需要在应用程序中添加对一种新的语言的支持时，无需修改应用程序的代码1. 客户端国际化实现关于需要扩展MXFramework中的国际化文件locale/zh_CN/messages.js,则可以将系统默认的messages.js内容拷贝后，在扩展模块下建立resources/locale/zh_CN/message.js文件，然后在该文件中重置已有键的本地语言值，这样在js脚本中即可以使用mx.msg(key)来获得所对应的值。messages.js中的键值对描述如下所示：mx.messages = DAY_0: SUN, DAY_1: MON, DAY_2: TUE, DAY_3: WED, DAY_4: THU, DAY_5: FRI,DAY_6: SAT2. 服务端国际化实现实现国际化相关的资源文件统一管理：一.实现资源文件与语言的关系配置；1）在自己的业务模块的src下新建文件夹locales2）国际化的资源文件统一放在新建的文件夹locales下，资源文件名为：message_zh_CN.properties，message_en_US.properties。将需要国际化的信息写入到属性文件中。例配置中文要显示的信息，可在message_zh_CN.properties文件中作如下配置：TESTI18N=欢迎0,现在时间是：1TESTEX=你好!则调用如下实现国际化:/*所引用类路径com.sgcc.uap.i18n.utils.I18nUtils*/无占位符调用情况I18nUtils.getMsg(this,TESTEX);/有占位符调用情况I18nUtils.getMsgWithParam(this,TESTI18N,user,newDate();3）国际化语言的支持在uap项目的perties属性文件中增加如下配置：#国际化信息设置，value格式为language_country，默认设置为中文。如：zh_CN。#language参考ISO-639代码。country参考ISO-3166代码I18N=zh_CN2.提供国际化相关的资源文件在运行态时的添加和修改的功能接口。1.6 接入自定义开发控件/页面 关于第三方控件以及业务需求开发的组件，均建议新建模块项目，将业务相关的控件以及页面写到模块项目中，当其他模块项目中需要引入的时候可以使用模块依赖，以及weblet间调用的方式（模块依赖和weblet调用可以参考SG-UAP_V1.5_高级用户手册_2.客户端开发.doc的节）， 自定义开发控件的方法可以参考SG-UAP_V1.5_高级用户手册_2.客户端开发.doc的节。1.7 自定义登录页面及主页 每个业务系统均需要有自己的主页以及登录页面，我们假设main.jsp为业务系统自定义开发的首页登录界面，则只需在uap-clientWebContentWEB-INFperties文件中修改登录页的设置，ISC_WORKBENCH_LOGINURL=/模块名/weblet名/main.jsp，这样在集成了ISC的情况下，在用户未登录的情况下均跳转该登录界面。 同样如何调用统一权限进行登录以及注销等操作以及获取当前用户以及用户菜单这些功能，对于业务系统的主页自然是要关心的内容，下面给出了统一权限相应接口调用的示例，可参考该实现代码，业务系统进行自行开发自己的主页系统。 客户端代码：var params = params: userName: xmmc, password: main.utils.AESUtil.encrypt(_key, password), url: mx.mappath(/./iscintegrate/rest/common/loginuser/validate) ; me.restClient.post( /./workbench/rest/portal/login, JSON.stringify(params), function(p_context) if (p_context.successful) me.currentUser = p_context.resultValue; _currentUser_loaded(me.currentUser); else mx.indicate(info, 该用户未通过验证！); );服务端代码：RequestMapping(value = /login, method = RequestMethod.POST)public ResponseBody Object login(RequestBody String p_loginData, HttpServletRequest p_request) throws IOException tryObjectMapper mapper = new ObjectMapper();Map map1 = mapper.readValue(p_loginData, Map.class);Map map = (Map) map1.get(params);String url = (String) map.get(url);ResponseEntity entity = restTemplate.postForEntity(url, p_loginData, String.class);Map validateMap = mapper.readValue(entity.getBody(), Map.class);if (Boolean)validateMap.get(successful)if (p_request != null)p_request.getSession(true).setAttribute(user, validateMap.get(resultValue);p_request.getSession(true).setAttribute(userID, (Map)validateMap.get(resultValue).get(id);return PortalResult.successWrapedResult(validateMap.get(resultValue);catch (Exception e)log.error(用户名密码验证失败, e);return new PortalResult(false, null, error); return new PortalResult(false, null, loginFailed);2 日志管理扩展概述日志组件对平台、业务系统运行过程中的日志进行收集记录。可以配置日志的级别，输出位置和输出格式。平台集成apache commons logging作为通用的日志记录组件，集成apache log4j作为日志具体的处理组件。apache commons logging组件会在运行期从类路径中加载log4j，使用log4j进行具体的日志处理。在开发时采用apache commons logging的接口进行操作，程序不要显示依赖log4j中的对象，如：import mons.logging.Log;private final static Log xxlog = LogFactory.getLog(XXXXX.class)在需要记录日志的位置按照级别记录日志，平台建议使用以下四个级别，优先级从高到低分别是ERROR、WARN、INFO、DEBUG。建议使用如下:if(log.isDebugEnabled() / 判断日志级别是否指定了debug级别。 log.debug(方法开始)平台提供名为perties日志配置文件，配置路径为uap/WebContent/WEB-INF/configuration/perties，在文件中按照log4j的规则配置日志的输出级别，输出格式和输出目的地。Log4j配置文件的内容为：log4j.appender.platform=org.apache.log4j.ConsoleAppenderlog4j.appender.platform.Target=System.outlog4j.appender.platform.layout=org.apache.log4j.PatternLayoutlog4j.appender.platform.layout.ConversionPattern=%dISO8601 Platform : %m%nlog4j.appender.thirdparty=org.apache.log4j.ConsoleAppenderlog4j.appender.thirdparty.Target=System.outlog4j.appender.thirdparty.layout=org.apache.log4j.PatternLayoutlog4j.appender.thirdparty.layout.ConversionPattern=%dISO8601 Thirds :%5p %c1:%L - %m%.sgcc=.sgcc=info, .hibernate=error, .springframework=error, .apache=error, thirdparty日志管理模块扩展方法平台的日志管理使用log4j框架的日志功能，因此日志管理模块的扩展其实就是在log4j框架下扩展appender接口，达到自定义日志的需求。log4j 框架是用 Java 语言编写的事实上的标准日志记录框架。作为 Jakarta 项目的一部分，它在 Apache 软件许可证（Apache Software License）下分发，Apache 软件许可证是由开放源代码促进会（Open Source Initiative ，OSI）认证的一种流行的开放源代码许可证。log4j 环境是完全可配置的，或者通过编程方式完成，或者通过属性中的配置文件或者 XML 格式的配置文件完成。此外，它还允许开发人员无需修改源代码就可以选择性地筛选出日志记录请求。log4j 环境包括三个主要组件：1. logger（日志记录器）：控制要启用或禁用哪些日志记录语句。可以对日志记录器指定如下级别：ALL、DEBUG、INFO、WARN、ERROR,FATA或OFF。2. layout（布局）：根据用户的愿望格式化日志记录请求。3. appender：向目的地发送格式化的输出。log4j 框架允许向任何日志记录器附加多个 appender。可以在任何时候对某个日子记录器添加（或删除）appender。附随 log4j 分发的 appender 有多个，包括：ConsoleAppender、FileAppender、SMTPAppender、JDBCAppender、JMSAppender、NTEventLogAppender、SyslogAppender也可以创建自己的自定义 appender，自定义appender的方法：1. 扩展AppenderSkeleton抽象类。2. 指定您的 appender 是否需要 layout。3. 如果某些属性必须同时激活，则应该在activateOptions()方法内完成。4. 实现close()方法。它必须把 closed 字段的值设置为true。记得释放所有资源。5. 可选地指定要使用的默认ErrorHandler对象。6. 编写append()方法的代码。这个方法负责附加日志记录事件，并在错误发生时负责调用错误处理程序。自定义Appender代码示例：package com.orangesoft.logging;import org.apache.log4j.AppenderSkeleton;import org.apache.log4j.spi.LoggingEvent;import org.apache.log4j.spi.TriggeringEventEvaluator;public class IMAppender extends AppenderSkeleton private String host; private int port = 5222; private String username; private String password; private String recipient; private boolean chatroom = false; private String nickname; private boolean SSL = false; private int bufferSize = 16; protected TriggeringEventEvaluator evaluator; / Set/Get methods for properties public void setHost(String host) this.host = host; public String getHost() return this.host; .other set/get methods. / AppenderSkeleton callback methods public boolean requiresLayout() . public void activateOptions() . public void append(LoggingEvent event) . public synchronized void close() . 应用配置示例：log4j.rootLogger = ALL,imlog4j.appender.im = com.orangesoft.logging.IMAppenderlog4j.appender.im.host = JABBER_SERVER (e.g. )log4j.appender.im.username = APP_JABBER_ACCOUNT_USERNAMElog4j.appender.im.password = APP_JABBER_ACCOUNT_PASSWORDlog4j.appender.im.recipient = YOUR_JABBER_ADDRESS (e.g. )log4j.appender.im.layout=org.apache.log4j.PatternLayoutlog4j.appender.im.layout.ConversionPattern = %n%r %-5p %M:%L - %m应用代码示例:package com.orangesoft.logging.examples;import org.apache.log4j.Logger;import org.apache.log4j.PropertyConfigurator;/* * Generates the number of logging events indicated by the first * argument value. The application ends with an ERROR level event * to trigger the IMAppender action. */public class EventCounter private static Logger logger = Logger.getLogger(EventCounter.class); public static void main(String args) int numEvents = Integer.parseInt(args0); String log4jConfigFile = args1; PropertyConfigurator.configure(log4jConfigFile); for (int i = 1; i = numEvents; i+) (Event # + i); logger.error(This error event triggers the delivery, new Exception(This is a mock exception); 3 异常管理扩展概述异常管理包括异常报错前端页面提示以及信息封装及异常处理，平台提供异常信息封装，按异常程度、应用范围定义了异常基类，可在基类中添加上下文对象（用户信息、模块信息、类名、方法名、服务器节点信息），并对异常进行编号。通过异常转换规则，可将原始异常、业务异常封装成应用平台的标准异常。建立统一的异常处理流程，接收各模块捕获的原始异常，将异常按信息封装的规则，进行封装，并为前端用户和后台日志提供异常输出。4 自定义异常的提示页面通常在服务端抛出异常会将异常打印在启动的中间件控制台中，对于系统用户而言并不知此刻发生了系统发生了什么故障，因此为了提供友好的异常提示，平台可以通过在配置文件中指定服务端抛出异常后前端显示的信息提示页面，将当前系统异常显示在前端。平台前端在向后台请求数据时，若在服务端发生异常则向前端返回错误信息，数据格式为：successful:false,resultValue:,resultHint:执行select ttsswtglwt0_.ID as ID7_, ttsswtglwt0_.WTBH as WTBH7_, ttsswtglwt0_.LYLX as LYLX7_, ttsswtglwt0_.LYBH as LYBH7_, ttsswtglwt0_.LYMC as LYMC7_, ttsswtglwt0_.ZY as ZY7_, ttsswtglwt0_.WTXXYMS as WTXXYMS7_, ttsswtglwt0_.JCPTBB as JCPTBB7_, ttsswtglwt0_.TYQXBB as TYQXBB7_, ttsswtglwt0_.BPMBB as BPMBB7_, ttsswtglwt0_.HJMS as HJMS7_, ttsswtglwt0_.WTDJ as WTDJ7_, ttsswtglwt0_.WTTJRQ as WTTJRQ7_, ttsswtglwt0_.WTZT as WTZT7_, ttsswtglwt0_.XWJJSJ as XWJJSJ7_, ttsswtglwt0_.SJJJSJ as SJJJSJ7_, ttsswtglwt0_.BUGBS as BUGBS7_, ttsswtglwt0_.SSXMZ as SSXMZ7_ from T_TSS_WTGL_WTFKDXX ttsswtglwt0_出错，原因为ORA-00904: TTSSWTGLWT0_.SSXMZ: 标识符无效n。,errorPage:$serverPath/psm/pbgcrt/resources/html/error.jsp,type:error其中可以看到服务端返回的errorPage就是错误跳转的页面，在UAP项目中uap-clientWebContentWEB-INFperties文件中添加异常页面配置项，可具体到具体异常类型对应的提示页面。CUSTOM_EXCEPTION=default:$serverPath/psm/pbgcrt