用友NCV5-Portlal技术红皮书.doc

portal技术红皮书nc-uap 5.0用友nc-uap2018-12-221第 页目 录第一章前言11.什么是portal12.nc portal的简介1第二章nc portal容器21.nc portal框架图22.nc portal的界面用语23.nc portal页面展现序列图34.nc portal目录结构45.nc portal管理与应用46.portal及portlet的国际化4第三章portlet开发61.portlet的介绍62.nc portal的内置portlet62.1portal管理portlet62.2cms管理portlet62.3iframeportlet62.4rssportlet63.portlet的开发实例73.1基于jsp视图技术的 portlet的开发73.2基于spring mvc框架的portlet开发93.3有效利用nc rich client控件开发交互性更强的portlet133.4如何利用iframeportlet进行简单第三方系统集成143.5如何利用ajax153.6如何利用json框架153.7如何引入自定义css和script153.8portlet的缓存设置16第四章portal主题开发17第五章portal sso技术181.概念介绍182.api介绍202.1用户资料来源202.2单点集成213.开发流程223.1iuserprovider的方法介绍233.2iwebapploginservice接口的方法介绍233.3系统配置过程244.集成实例附录274.1与iufo的集成274.2与bo的集成28附录301.引用的技术文档30第 30 页第一章 前言1. 什么是portal许多企业和组织需要为企业内部员工、外部客户群体量身定制有“价值”的企业信息，但是，一方面是好些有“价值”的企业信息获取并不是一件轻松的事情，信息部门需要整合来自不同的应用系统，不同数据源，不同平台的无数各种类型的数据和资源；另一方面，如何轻松实现一个为所有的用户群体量身定制的系统构架也不是一件容易的事情。传统技术整合这些资源的技术复杂度和成本都太高，许多企业无法负担如此的投入。portal 技术的出现，带给人们解决这类难题的曙光。portal技术强调以用户为中心，提供个性化、单点登录、不同来源的内容整合功能，从而实现了信息的集中访问。portal从本质上来说就是一个内容聚集的平台。2. nc portal的简介nc portal是基于jsr168规范而实现的一套j2ee技术体系架构的portal。它构建于nc基础服务与nc rich client基础组件之上，完美融合ajax技术与spring mvc技术，提供了灵活而丰富的个性化和管理定制功能。nc portal允许多种安全认证方式和自选第三方系统用户来源，采取了基于角色访问控制(rbac)的权限模型。并提供了完善和通用的第三方系统集成框架和单点登录框架，ncportal发版默认集成nc、iufo、bo、自定义查询报表应用，实施sso比商业portal简单易用。它提供的portal管理功能，允许管理员在运行态对portal进行定制，而无需重启甚至编码。同时，内建的换肤机制使得实现自定义皮肤非常简单，只需完成相应图片的替换即可。nc portal提供了引入了一些通用的api，使得portlet可轻松调用ajax，json，以及使用nc richclient组件。第二章 nc portal容器1. nc portal框架图2. nc portal的界面用语在nc portal中，每一个tab控件页签对应着一个布局定义。布局即一个tab页内容的描述，它由多个列构成，每个列又由portlets组成。布局可由管理员动态定制，并可在运行时修改。布局可嵌套布局，从而组成相对复杂的界面。一个布局中的portlet不能重复。布局和portlet的访问控制，是由基于角色的权限控制模型定义的。因此，管理员可在运行时，通过portal管理portlet，对各种资源进行安全管理。3. nc portal页面展现序列图在nc portal中，portlet的展现是一个异步的过程。因此一定要注意多个ajax异步请求操作潜在的对session的并发访问问题。同时，nc portal也提供了对portlet内容的缓存方案（兼容jsr168规范），可设置全局缓存（针对所有用户一致的内容），按用户缓存（不同用户看到不同的内容），及细粒度的按状态缓存（比如只缓存视图状态而不缓存编辑状态）。部署portlet时可按照需要设置缓存，从而有效提高页面展现速度，减少对服务器端的压力。4. nc portal目录结构5. nc portal管理与应用portal数据源设置portal采用nc的数据源配置，只需在ierp/portal/perties中配置对应nc的数据源名即可。nc portal开发环境配置nc portal的开发环境即nc5.0的开发环境，请参考相应文档。6. portal及portlet的国际化portal容器及内置portlet的多语化是基于nc的多语机制，并符合jsr168规范。二次开发的portlet需参照规范的方式实现自定义resourcebundle，或者直接使用nc portal的通用多语言资源绑定类，springresourcebundle。有关nc的国际化机制请参考相应的文档。这里需要提出的是，nc portal针对jsp页面，封装了简单的多语化el表达式，可直接在页面中调用 $ml:trans(key to translate)即可，java类中可直接调用languageutil工具类中的相应方法进行。1. nc portal页面中一些工具类和预置对象。serurityutil类是一个安全相关类。可直接从此类中提取和用户有关的信息及权限信息。stringpool类提供了常用的字符串常量定义。getterutil类提供了相应的字符串操作方法。paramutil提供了提取http请求参数的工具方法。每个页面中都包含了一个themedisplay的实例，此实例是请求级别的，可从此实例中获得大多数当前请求信息。具体每个类的操作方式请参考类自身定义和javadoc。第三章 portlet开发1. portlet的介绍一个portlet就是一个独立的web应用。它通过portlet容器与portal服务打交道。从本质上来说，它是一个网页内容片段，众多portlet通过portal页面组织在一起而形成一个完整的页面。因此，只要符合jsr168规范，这个portlet就可以享受到所有符合此规范的portal容器所带来的服务与功能。对于一个portlet，区分为多种状态(state)和多种模式(mode)。在nc portal中，支持portlet的最大化(maximized)，最小化(mininized)和正常(normal)状态，以及支持视图(view),编辑(edit)和帮助(help)三种模式。当然，一个portlet具体拥有的模式和状态是通过配置而从这里面选取的子集。完整的portlet的定义请参阅jsr168规范的文档。2. nc portal的内置portlet2.1 portal管理portletportal管理portlet提供了portal容器的管理功能。包括用户管理，角色管理，资源管理，布局定义等功能节点。此portlet利用了nc rich client控件的灵活特性，使nc portal可在运行时完成个性定制而无须重启服务器和重新编码。2.2 cms管理portletcms管理portlet提供了几个常用的portlet，包括新闻管理，论坛管理，公司发文管理，公告管理及连接管理等。新闻管理和连接管理提供了比较灵活的功能，配合其它portlet可快速构建网页内容。关于内容管理portlet的使用，请参考nc portal的用户使用文档。2.3 iframeportletiframeportlet是一通用简单集成portlet，既可用于用户个性化定制时引入外部网站的工具，也可用于管理员的静态定义。此portlet的使用可参考3.4小节。2.4 rssportletrss portlet是读取rss站点内容的通用portlet。此portlet的使用请参考用户使用文档。需要注意的是，此portlet在使用过程中可能会遇到浏览器的权限问题，这个问题可通过配置后台代理解决。具体方式是在ierp/portal/perties中设置portal.rss.mode=1。如果需要代理，可设置#http xy.host=#http proxy xy.port=#http proxy xy.username=#http proxy xy.password=#http proxy xy.domain=3. portlet的开发实例一个portlet的开发，通常来说要走下面几步：(1) 按照规范实现javax.portlet.portlet接口。(2) 编写相关的页面文件(任何portal容器支持的视图技术)。(3) 在配置文件portlet.xml中配置此portlet。如果portlet相对较复杂，可能还会选择不同的持久化技术(hibernate,ibatis,jdo等),以及不同的mvc框架和视图框架的组合(sprint,struts,jsf,tapestry等)。nc portal针对基于jsp，jsf和基于spring mvc技术的portlet开发实现了一套基类。大多数情况下无需重新实现portlet接口，只需进行相关的流程类的编写即可。在整个portlet的编写过程中，我们推荐的组合是nc jdbcframework (持久层)+nc ioc + spring mvc + jsp技术（请参阅相应的文档）。通过我们的开发环境以及nc portal的内置支持，这种看似复杂的组合实现起来就比较简单了。 nc portal为多种模版技术的portlet开发提供了内置支持，并抽象出了相应的基类。大大简化了portlet的开发难度。下面以几个简单的portlet作为样例:3.1 基于jsp视图技术的 portlet的开发jsp portlet适用于业务流程简单，只作简单展现的portlet。以一个具有view和edit状态的简单portlet为例。我们可以直接采用nc portal提供的jspportlet作为portlet接口的实现类。针对各种状态，我们需要写出相应的jsp页。首先建立视图状态下的jsp页面，helloworldview.jsp,内容如下: hello,this portlet is in view mode!其中 为nc portal提供的常用tag和类引用的定义。推荐使用。是jsr168规范要求的变量声明定义。它将把renderrequest,renderresponse,及portletconfig放置在此page中，以供引用。剩下的内容就是一个普通的html所具有的内容。其中需要注意四点:1.此部分内容只是一内容片段。不能包含等信息。2.推荐以包裹整个内容片段。这样可更清晰的区分整个portlet内容的结构。3.虽然基于jsp技术，但portlet内容体不推荐使用request，response和session等区域变量。应代之以renderrequest, renderresponse,portletsession等在中定义的页面变量。4.页面允许script语法。但是推荐放置于之外，如下面同理，建立一个helloworldedit.jsp,内容如下 hello,this portlet is in view mode!这样就完成了portlet两个状态页的定义。下面需要在portlet的定义文件web-inf/conf/portlet.xml中配置此portlet.在web-infconfportlet.xml中，我们添加helloworldportlet的定义,此portlet的定义文件由jsr168规范定义helloworld portlethelloworldportlet /注意不能和已有的重复 helloworld portletview-jsp /指明view模式下的jsp页面/html/portlets/helloworld/helloworldview.jspedit-jsp/指明edit模式下的jsp页面/html/portlets/helloworld/helloworldedit.jsp /是否需要portlet外边框。(推荐)decoratortruenc.bs.portlet.jspportlet /portlet实现类。统一使用此类0/是否启用缓存 -1，永不过期。0，不启用，0的数字，以分钟为单位指明缓存失效时间/在html展现方案中支持集中模式。此处支持view,edittext/htmlviewediten/支持的语言种类nc.bs.portlet.springresourcebundle /对应的多语言资源类，如果使用nc 多语言机制，统一使用此类/portlet其它信息定义hello world portlethello worldhello,world/portlet可能会用到的属性定义!- -role_admin定义完毕portlet，我们还需要在portlet的分类定义文件中定义此portlet。在web-inf/conf/display.xml中，在某一个category下，加上一条：到此，portlet的开发与定义完成。重启服务器。打开portal页面，可以在个人设置或者portal管理-布局管理中添加此portlet。3.2 基于spring mvc框架的portlet开发spring mvc框架小巧，灵活，稳定，不会像其它mvc框架一样将流程绑的太死，这也是笔者推荐它的主要原因。关于spring mvc的使用，请参考spring相关技术文档。当然，在nc portal中使用其它框架也是允许的。此处仅介绍spring mvc在nc portal中的配置与应该注意的地方。nc portal针对spring mvc提供了actionportlet的实现。与jspportlet相似，基于此portlet的开发仅需要开发相应的页面流程即可。下面以自定义链接portlet作为样例，具体需求是这样的：用户可在编辑模式下增加自己需要的链接地址，在视图模式下按照列表形式显示所有链接。我们按照下面的次序完成此portlet：a建表并编写对应vo类。create table pub_mylink (pk_mylink char(20) primary key, name varchar(20) not null, url varchar(100) not null)对应mylinkvo.javapackage nc.portlet.mylinks;import nc.jdbc.framework.orm.ipersistenceobject;import nc.vo.pub.portal.base.valueobject;public class mylinkvo implements valueobject, ipersistenceobjectprivate string pk_mylink;private string name;private string url;public string getprimarykey() return pk_mylink;public string gettablename() return pub_mylink;public string getname() return name;public void setname(string name) = name;public string getpk_mylink() return pk_mylink;public void setpk_mylink(string pk_mylink) this.pk_mylink = pk_mylink;public string geturl() return url;public void seturl(string url) this.url = url;b. 编写bs接口类及实现。查询服务接口imylinkqueryservicepackage nc.portlet.mylinks;import nc.vo.pub.businessexception;public interface imylinkqueryservice public mylinkvo getalllinks(string userid) throws businessexception;插入服务接口imylinkservicepackage nc.portlet.mylinks;import nc.vo.pub.businessexception;public interface imylinkservice public string insertmylinkvo(mylinkvo vo) throws businessexception;编写对应actionurl的处理类package nc.portlet.mylinks;import javax.portlet.actionrequest;import javax.portlet.actionresponse;import mon.nclocator;import mon.portletbaseaction;import nc.vo.pub.portal.exception.serviceexception;public class mylinkeditaction_n extends portletbaseaction public void processaction(actionrequest req, actionresponse res)throws serviceexception, exception string name = req.getparameter(name);string url = req.getparameter(url);mylinkvo vo = new mylinkvo();vo.setname(name);vo.seturl(url);imylinkservice service = (imylinkservice) nclocator.getinstance().lookup(imylinkservice.class.getname();service.insertmylinkvo(vo);setforward(req, /mylink/view);参考jdbcframework相关文档，依次实现以上两个接口。c. 编写对应的action编写view状态对应的类package nc.portlet.mylinks;import javax.servlet.http.httpservletrequest;import javax.servlet.http.httpservletresponse;import mon.nclocator;import nc.bs.portal.util.securityutil;import org.springframework.web.servlet.modelandview;import org.springframework.web.servlet.mvc.controller;public class mylinkviewaction implements controller private static final string view_page = mylinks/view;public modelandview handlerequest(httpservletrequest request,httpservletresponse response) throws exception imylinkqueryservice queryservice = (imylinkqueryservice) nclocator.getinstance().lookup(imylinkqueryservice.class.getname();string userid = securityutil.getuserid(request);mylinkvo linkvos = queryservice.getalllinks(userid);request.setattribute(linkvos, linkvos);return new modelandview(view_page);编写对应的jsp文件，按照上面路径配置的jsp，应该放置于/html/portlets/mylinks/view.jsp 与/html/portlets/mylinks/edit.jspview.jsp$edit.jspform name=link_edit_form onsubmit=return sys_checklink_valid(this); action= method=post链接名称链接地址window.sys_checklink_valid = function(form)return true;d. 配置并运行。 参考nc服务配置分别配置 /mylink/view /mylink/edit /mylink_n/edit,并按照jspportlet的方式配置portlet.xml.重起中间件即可3.3 有效利用nc rich client控件开发交互性更强的portletnc rich client控件赋予了比传统web界面更强的交互能力。适合一些对交互性要求比较强的应用。关于如何使用nc rich client，请参考相关红皮书。在portlet中应用rich client控件，基本与编写普通的jsp一样的流程和配置,需要注意以下两点:a.在引入时必须使用init_f.jsp代替init.jsp,这是区分是否使用rich client控件的关键。b.在此页中所有的代码，实际上是运行在javascript语意环境下的，所以必须以javascript语法来写。3.4 如何利用iframeportlet进行简单第三方系统集成iframeportlet是一个通用的外部应用集成portlet，利用此portlet，可以直接将第三方系统集成进来。但是此portlet仅适用于对外部应用的简单集成，如果想做到单点登录，请参考第五章,portal sso技术。使用iframeportlet，只需在web-inf/conf/portlet.xml中，添加一个portlet定义：integrate portletintegrateportletintegrate portletnc.bs.portlet.iframeportlet0text/htmlviewennc.bs.portlet.springresourcebundleintegrate portletintegrateintegratesrcheight-normal0role_admin/portlet3.5 如何利用ajaxnc portal对ajax进行了一定的封装，使用ajax，可直接调用loadpage(url, param, return func, return args, method, asyn);参数分别是：目标url,目标参数,异步回调函数,回调函数将会用到的参数传递，调用方法(post true, get false),默认为post,是否异步调用,默认是异步.因此,可以这样调用 loadpage(“”);loadpage(, null, null, null, true, false)如果调用方式为异步，则返回结果会通过回调函数返回。此回调函数会接受三个参数，xmlhttprequest对象，returnargs数组对象，以及exception对象。如果exception对象不为空，则表示调用过程出现了异常。需要注意的是，如果是portlet url，不能直接使用此调用。需调用我们提供的全局函数triggerlinkaction(url, param);比如:var url = “”;var param = “cmd=update”;triggerlinkaction(url, param);此调用的结果将会被portlet容器接受并自动转换为portlet内容。3.6 如何利用json框架json是对ajax的轻量封装，非常适合从js object到java object的相互转换，具体使用请参考json的相关手册。需注意的是我们对它进行了一定程度的增强，使得它可以直接注册接口服务以及转换super vo，以方便适应nc提供的服务。在使用json之前，调用 initremotecall();此函数实际上对json进行了初始化。如果已初始化将不会再次初始化。初始化之后的变量赋予了window.remotecall.因此之后就可以使用window.remotecall进行远程调用。3.7 如何引入自定义css和script所有需运行时由portal引入的javascript和css文件，应该放在/html/script 和/html/css中。需注意的是，这种方式会导致portal页面初始化载入更多的代码。如果确定某些script文件并不是在初始化时用到。建议使用全局函数dynamicaddscript(window.globalpath+ /html/script/xx.js)进行运行时动态引入。3.8 portlet的缓存设置nc portal实现了jsr168规范定义的缓存配置，并在此基础上进行了一定的扩充。缓存类型分为全局缓存，按用户缓存。同时这两种缓存类型都可按状态进行缓存。全局缓存：适用于所有用户看到的是同样内容的portlet。启用这种缓存，可大大减小服务器端的压力。按用户缓存: 适用于不同用户看到不同内容的portlet。比如与权限有关的portlet。缓存的启用，只需按照规范在portlet的配置中设置10，其中的10以分钟为单位。0表示不启用缓存，1表示缓存永不过期。如果启用了缓存，默认为全局缓存。可通过设置cachetype1 更改为按用户缓存。也可通过portal管理页签进行运行时设定。所有缓存一经启用，默认按照所有状态进行缓存。可通过设置cachestate2进行状态设置。状态分别是edit 1, view 2, help 4,最终值为几个状态之和。此值也可以在运行时设置。第四章 portal主题开发nc portal的主题开发分为两部分：theme开发和colorscheme开发。colorscheme是针对于某一theme下颜色样式。其中theme开发难度比较大，需要对整个portal容器有很深的理解，此处不做进一步介绍。而colorscheme开发则绝大多数是对css和图片的修改。colorscheme开发：colorscheme开发涉及到两部分。控件部分的colorscheme开发以及portal容器的colorscheme开发。其中控件的colorscheme开发基本与portal无关，唯一要求colorscheme 的 id与portal的保持一致。此部分请参阅轻量级控件开发文档。portal容器的colorscheme的开发量，取决于所对应的theme，大多数情况下只需替换图片与编辑/html/themes/theme id/colorscheme id/styles下的portal.css即可。theme和colorscheme的配置文件位于web-inf/conf/look-and-feel.xml下，在完成新的theme和colorscheme编辑之后，按照里面已有的格式配置新的定义，重启服务器，即可应用新的主题。第五章 portal sso技术1. 概念介绍 sso（single sign-on）即单点登录技术。它是指在多个子系统的大型应用中，用户在子系统之间进行切换时，不需要每次都重新输入用户的身份信息，从而做到一处认证，整个应用系统都能有效识别。单点登录只是一种功能概念，并没有对实现方式的定义和限制。nc-portal的单点登录技术，就是sso技术的一种实现方式。sso的初步实现思路是：使用数据库来存储各应用系统的访问凭证并关联portal用户，在portal登录后通过登录的portal用户自动找到各应用系统的凭证直接进入各应用系统（每个应用系统一个portlet）。图1、nc-portal sso的凭证库模型凭证库槽用来模拟凭证库存放地，同一类凭证存放在一个凭证库槽中，一个凭证库槽就是一个用户的一个portlet的凭证存放地，这个槽中可放置多于一个的凭证。portal用户id：portal用户portlet id：portlet标识共享级别：有三个级别：专有、应用共享、全局共享。专有是只能本用户本portlet使用；应用共享是本用户同后端应用名的其它portlet也可使用；全局共享是所有用户同后端应用名都共享。共享级别直接在portlet.xml中的具体portlet的设置一个来定义，如果不设置，默认为应用共享：share_level1共享级别含义：专有0；应用共享1；全局共享2在portlet.xml中定义了什么级别，该portlet保存凭证时就以该级别创建凭证槽。在当前portal实现中，仅支持应用共享的级别，其他级别视实际需求，在后继版本中在进行实现。凭证类型：活动型（消极型），安全性上更严密的要求，暂时不考虑实现。后端应用名：portlet类名验证用户：应用系统的用户验证密码：用户的密码对资源：除了用户、口令之外的其它登录信息，使用xml格式序列化后存储。如一个nc portlet凭证资源： accountcodeglcorppk1001 凭证库模型涉及包含两个过程：凭证的创建和凭证的维护。凭证的创建过程是通过用户登录集成第三方页面，输入合法的第三方系统用户名和密码信息来实现的。通过此过程，系统在数据库中记录凭证库槽及凭证的对应信息。如果一个用户拥有多个某个portlet对应系统的凭证，那么进入时默认以第一个进入，同时提供在edit模式下的选择或者重新输入来维护凭证，多个凭证下拉列出供选择重新登录。图2 sso实现类图2. api介绍nc-portal 单点登录是nc-portal集成其它系统（目前支持web系统）的框架和工具，nc-portal里的sso在实现多个系统单点登录的功能上进行了扩展：可以定义单点登录的用户来源user provider（可以是任何支持的数据来源）。因此，在具体实现与nc-portal的集成过程中，需要注意和实现两个关键点，即：用户资料来源和单点集成。下面将分别针对两个关键点来进行介绍说明。2.1