宽乐通信Web Service接口中间件WebUCComapionV112部署说明书.doc

广东电信有限公司研究院宽乐通信Web Service接口中间件WebUCComapionV1.12部署说明书江洪2007-6-7本文描述WebUCCompanionV1.12版本在各种应用服务器的部署流程。另外，对管理维护操作也作了一定的说明目录第1章 文档说明3第2章 Uniportal服务器部署32.1 安装uniportal平台3安装过程32.2 安装WebUCComapionV1.126安装过程62.3 文件配置7第3章 Tomcat服务器部署7第4章 维护管理8第1章 文档说明宽乐通信Web Service接口中间件WebUCComapion是基于java开发的部署于java应用服务器上的中间件，它既可以集成于第三方应用中，也可以独立部署。本文档就宽乐通信Web Service接口中间件在已支持的各种应用服务器的部署作完整的说明。文档将按照不同的服务器分别进行描述。 本文档是针对WebUCComapionV1.12版本做的部署说明。如果并非这个版本，请参考本文其他版本。第2章 Uniportal服务器部署WebUCComapionV1.12使用的Uniportal服务器是华为提供的uniportalv100r001d330版本平台。该平台包含jboss3.2.6版本的将j2ee应用服务器，其Web Service模块使用。由于第三方服务器应用一般不会使用uniportal平台作为宿主平台，所以部署在Uniportal平台上的WebUCComapionV1.12是作为独立应用而部署。WebUCComapionV1.12的uniportal部署版本包含的文件说明如下：文件名称解释uniportal_plt_ins.jaruniportalv100r001d330平台运行期文件serviceonly_ins.jarWebUCComapionV1.12版本文件jboss-net.sarJ模块perties日志配置文件WebUCConfig.xmlWebUCComapionV1.12应用配置文件部署的流程为：安装uniportal平台安装WebUCComapionV1.12文件配置。详细流程如下：2.1 安装uniportal平台在安装uniportal平台之前需要确认服务器上安装了JDK1.4.2版本，并且正确设置了环境变量。环境变量设置完成后，就可以安装Portal了。获取uniportal_plt_ins.jar包，在命令行方式下执行java jar uniportal_plt_ins.jar安装Portal，安装过程D:java -jar uniportal_plt_ins.jarPlease select the language you wish to use during installation:1.default(zh)2.en#欢迎使用华为技术有限公司智能网Uni-Portal# 当前时间是: 2004-10-19 17:47:04 # 当前版本是: V100R001D300 # 通用安装向导将引导您安装Uni-Portal # 安装过程中需要向您询问一些参数. # 提问时中括号内的是推荐的缺省值,直接键入回车键,表示使用推荐值. #选择安装的类型,1-覆盖安装 2-升级安装:1请输入安装目录C:Documents and Settingsz30607d:/portal提示:d:portal目录不存在输入Y-创建;输入N-重新选择安装目录;E-退出安装:Y端口号设置请输入HTTP端口号:8080WebService端口:8083JNDI端口:1099RMI invoker端口:4444JMX端口:7888JMX的HTML管理端口:8889UIL2ServerILService 端口:8092RMI Naming Service 端口:1098pooled invoker 端口:4445MC Https 端口:7443是否安装安全证书？输入Y-安装;输入N-不安装:Y请输入HTTPS端口号:8443请输入生成安全证书的参数:请输入您的站点域名:unknownlocalhost请输入您的组织单位名称:unknownhuawei请输入您的组织名称:unknowncom请输入您所在的城市和区域名称:ShenZhenNanJing请输入您所在的洲或者省份的名称:GuangDongJiangSu请输入该单位的两字的国家代码:CN请输入别名:unknownportal请输入KeyStore密码:uniportal-keystore-password请输入证书的有效时间:100请输入MC的HTTP端口号:7080是否安装为后台服务？输入Y-安装;输入N-不安装:N#安装参数设置如下: # 安装路径:d:portal # 端口号设置: # WebService端口:8083 # JNDI端口:1099 # RMI invoker端口:4444 # OILServerILService端口:8090 # UILServerILService端口:8091 # JMX端口:7888 # JMX的HTML管理端口:8889 # UIL2ServerILService 端口:8092 # RMI Naming Service 端口:1098 # pooled invoker 端口:4445 # MC Https 端口:7443 # HTTP端口号:8080 # HTTPS端口号:8443 # MC的HTTP端口号:7080 #输入Y-使用上述参数进行安装;输入N-修改参数设置;E-退出安装:Y开始安装.Deploying servcies.Done!Checking plugin.Done!安装完成!在安装成功之后，用户可以看到如下的目录结构：目录和文件功能bin执行启动文件目录confPortal系统配置文件目录definitionPortal平台相关配置文件目录deploy部署文件目录jbossJboss工作目录lib系统库文件目录logs日志目录service业务部署目录work系统工作目录2.2 安装WebUCComapionV1.12在安装完成uniportal平台后，就可以开始业务的安装。在命令行方式下执行java jar serviceonly_ins.jar即可安装业务。安装过程F:java -jar serviceonly_ins.jarPrepare files needed while install,wait please.Please select the language you wish to use during installation:1.default(zh)2.en#欢迎使用华为技术有限公司智能网Uni-Portal# 当前时间是:2004-10-27 15:12:56 # 当前版本是:V100R001D311 # 通用安装向导将引导您安装Uni-Portal # 安装过程中需要向您询问一些参数. # 提问时中括号内的是推荐的缺省值,直接键入回车键,表示使用推荐值. #选择安装的类型,1-覆盖安装 2-升级安装:1在这里需要选择覆盖安装输入安装的目标目录:C:Documents and Settingsz31483f:ddd目录不存在或你没有写权限! 重新输入? Y-是, others-退出:Y输入安装的目标目录:C:Documents and Settingsz31483f:1_temp目录不是一个uniportal的目录!重新输入? Y-是, others-退出:Y输入安装的目标目录:C:Documents and Settingsz31483f:ttt在这里选择的安装目标目录是uniportal平台的安装目录#安装参数设置如下:# 安装路径:f:ttt #输入Y-使用上述参数进行安装;输入N-修改参数设置;E-退出安装:Y.Deploying servcies.Done!Checking plugin.Done!安装完成!在业务安装完成后，需要运行业务部署命令，完成业务部署，业务部署命令是uniportal deploy（Window操作系统）或./uniportal.sh deploy（UNIX、Linux操作系统）。2.3 文件配置在业务部署完成以后，就要进行业务文件配置。主要是安装模块，部署perties和WebUCConfig.xml两个配置文件。安装模块就是将jboss-net.sar目录文件拷贝到%uniportal%/deploy目录下即可。安装模块后，在将业务配置文件perties和WebUCConfig.xml拷贝到%uniportal%/jboss/bin目录下即可经过以上的操作，就完成WebUCCompanionV1.12在uniportal平台上的安装。安装完成后，打开IE浏览器，键入http:/ip:8080/testWS，应该可以看到本业务的主页面，后面的设置操作请参考第4章的叙述。第3章 Tomcat服务器部署在Tomcat上部署的WebUCCompanion业务比较灵活，可以轻易地实现与第三方平台应用的整合。由于Tomcat服务器本身并不支持Web Service，所以WebUCCompanion的Tomcat版本包含了Axis1.4的类库。WebUCComapionV1.12的Tomcat版本包含以下目录/文件：目录/文件说明WEB-INF存放WebUCComapnion业务运行所需要的库文件WEB-INFweb.xmlWebUCCompanion应用Tomcat服务器启动配置文件WEB-INFlibAxis平台文件和WebUCCompanion业务运行期文件WEB-INFjwsClassesWebUCCompanion的Web Service服务器端实现class文件WebUCCompanion存放WebUCCompanion应用的web文件、Web Service服务器端jws文件、配置文件存放目录和日志存放目录部署比较简单，只需要将上述文件拷贝到Tomcat服务器上相应的目录下即可。下面详细介绍文件拷贝部署的过程。首先是拷贝本应用的WEB-INF文件夹。如果本应用是作为独立应用部署，先在webapps目录下创建一个目录，这里以目录名称为testWS1为例进行叙述，目录建好后，进入，将WEB-INF目录下全部内容拷贝进去。如果本应用作为第三方应用集成，那么将本应用的WEB-INF目录下除web.xml文件以外的其他文件拷贝到第三方应用的WEB-INF目录。然后对本应用的web.xml文件，将名为WebUCCompanionServlet的servlet标签的所有内容拷贝到第三方应用的web.xml文件中。部署完本应用的WEB-INF文件夹后，假设该WEB-INF文件夹被部署到名称为testWS1的目录下面，接着，就需要修改web.xml。在web.xml中，找到WebUCCompanionServlet的servlet标签定义。WebUCCompanionServlet的servlet定义中有3个init-param标签参数定义，将第一个参数log4j config file path中webapps和WebUCCompanion中间的目录名称改为testWS1。同理，修改第二个参数webUCCompanion config file path的webapps和WebUCCompanion中间的目录名称改成testWS1。第三个参数web application root dir的WebUCCompanion前面的目录名称testWS1。接下来，将WebUCCompanion目录拷贝到testWS1目录下，进入到WebUCCompanionconf下，打开perties文件，将log4j.appender.A2.File字段值中webapps和WebUCCompanion中间的目录名称修改成testWS1。至此，就完成了WebUCCompanionV1.12在Tomcat服务器上的部署。打开Web浏览器，输入http:/ip:8080/%应用部署的根目录名称%/WebUCCompanion，就会显示本应用的主页界面。第4章 Weblogic Server8.1平台部署本版本的发布文件包含两个，一个为testWebUCWAR.rar，另一个是WebUCCompanion.jar。testWebUCWAR.rar是本版本的运行文件，WebUCCompanion.jar文件是用于提供第三方应用进行本中间件接口开发的编译库文件。本文档针对testWebUCWAR.rar文件讲解其部署于Weblogic Server8.1上，并与第三方WEB应用整合的过程。4.1 部署过程将发布文件testWebUCWAR.rar解压，得到的解压文件目录结构如下：目录/文件说明WEB-INF存放WebUCComapnion业务运行所需要的库文件与相关配置文件WEB-INF classes本中间件的运行期class文件WEB-INFweb.xml本中间件WebUCCompanion应用需要配置的web容器配置文件，主要用于服务器启动时初始化WebUCCompanion应用WEB-INF weblogic.xmlWeblogic平台配置文件WEB-INF web-services.xml本中间件WebUCCompanion应用的web service服务器端组件部署描述符文件WEB-INFlib本中间件WebUCCompanion应用运行期依赖库文件WebUCCompanion存放WebUCCompanion应用的web文件（jsp）、配置文件存放目录和日志存放目录下面，需要分步将这些解压文件拷贝（上传）到wls服务器上的第三方web应用的相关目录中，并修改某些配置文件的配置信息，具体步骤如下：1、 拷贝（上传）classes文件解压目录WEB-INF classes中的文件是本中间件的主要运行期class文件。只需要将这个解压目录下面所有的文件拷贝（上传）到wls服务器第三方web应用的WAR目录中相应的WEB-INF classes目录下即可。2、 部署web-services.xml文件解压文件WEB-INF web-services.xml是本中间件web service服务器端组件的部署描述符文件，这个文件的部署是将其拷贝（上传）到第三方web应用的WAR目录的WEB-INF目录下即可。注意，如果第三方web应用的WEB-INF目录下已经有web-services.xml文件，那么不能直接将其覆盖，而是应该将解压文件WEB-INF web-services.xml中标签下的内容拷贝到第三方web应用的web-services.xml文件中。3、 修改第三方web应用的weblogic.xml文件解压文件WEB-INFweblogic.xml文件是weblogic服务器的参数描述文件。部署时，将这个文件用文件编辑器打开，将其中标签下的内容粘贴到服务器上原有的weblogic.xml文件中就可以了。注意，如果服务器上原有的weblogic.xml文件中如果已经存在标签且其中的内容与解压文件weblogic.xml中的一致就不需要进行粘贴操作。4、 修改第三方web应用的web.xml文件解压文件WEB-INFweb.xml是本中间件依赖文件，用于设定中间件初始化入口serlvet地址。但是，第三方web应用本身的WAR目录中肯定已经存在web.xml文件，所以不能直接将解压文件拷贝（上传）到第三方应用的目录中覆盖其原有的同名文件，只能够将解压文件的web.xml文件中的内容拷贝到第三方web应用的web.xml文件中。使用文件编辑工具分别打开解压web.xml文件和第三方web应用中的web.xml文件。将解压web.xml文件中和标签下的所有内容粘贴到第三方web应用中的web.xml文件文件中。粘贴操作完成后，对第三方web应用的web.xml文件进行修改。对于添加上来的标签下的$WEB_APPLICATION_WAR_DIR修改成第三方web应用的WAR目录的绝对路径，将$WEB_APPLICATION_CONTEXT_ROOT修改成第三方web应用的application.xml中指定的值。至此，第三方应用的web.xml文件修改完成，保存到服务器即可。5、 拷贝（上传）lib依赖库文件将解压文件WEB-INFlib中所有的文件到拷贝（上传）到第三方web应用WAR目录下的WEB-INFlib目录即可。如果服务器上第三方应用的WEB-INF目录下没有lib目录，可以新建这个目录再进行文件拷贝（上传）。6、 拷贝（上传）WebUCCompanion目录这一步是要将解压目录WebUCCompanion整个拷贝（上传）到第三方web应用的WAR目录下即可。拷贝（上传）完成后进入到服务器上的WebUCCompanion/conf目录中，用文件编辑器打开perties文件，将其中的$WEB_APPLICATION_WAR_DIR修改成第三方web应用的WAR目录的绝对路径。7、 设定业务参数值在上传到服务器的解压目录WebUCCompanion的conf目录下，有一个ServicePperties文件。该文件是指定中间件使用的几个必要的web service组件的URL地址，在平台重启之前，需要设定这些URL的值。其中，将其中代有$符号的参数按规定修改成地址值即可。修改完成后在服务器上保存这个文件即可。8、 重启Domain，检查部署有效性以上所有步骤都完成以后，就可以重启第三方web应用所在的Domain。Domian启动完成后，打开浏览器，输入URL地址：http:/$服务器IP/$Domain端口/$ context-root /WebUCCompanion，如果上述部署操作正确的话，可以看到如下页面：接着检查本中间件的Web Service服务器端组件部署的正确性。在浏览器上键入URL地址：http:/ $服务器IP/$Domain端口/$ context-root /EventCallBackService，正确应该能够看到以下页面： 第5章 维护管理5.1 基本配置文件信息WebUCCompanion应用维护管理操作主要包括配置文件的修改，维护Web页面操作等。配置文件的管理WebUCCompanion应用主要有3个配置文件，它们是：Web.xml：应用服务器应用初始化文件。Lperties：日志配置文件WebUCConfig.xml：应用配置文件Web.xml在本应用中，web.xml的配置主要是为了使应用服务器在启动的时候初始化本应用，其内容是在Web.xml中添加一个servlet标签，格式为： WebUCCompanionServlet WebUCCompanion Servlet com.jiangh.webuc.servicemanager.ThirdPartyServerApp log4j config file path ././webapps/testWS1/WebUCCompanion/conf/perties webUCCompanion config file path ././webapps/testWS1/WebUCCompanion/conf/WebUCConfig.xml web application root dir testWS1/WebUCCompanion 14 在这个配置文件中，主要需要关注的参数是3个init-param的param-value值。第一个init-param是perties配置文件的位置。这个位置是指其对于应用服务器的bin目录的相对路径值。例如，如果本业务是部署Tomcat服务器上的webapps/testWS1的目录下的话，那么这个参数值就设为././webapps/testWS1/WebUCCompanion/conf/perties。第二个init-param是业务配置文件WebUCConfig.xml对于Tomcat服务器bin目录的相对路径值。例如，如果本业务是部署在Tomcat服务器上的webapps/testWS1的目录下的话，那么这个参数值就设为././webapps/testWS1/WebUCCompanion/conf/WebUCConfig.xml。第三个init-param参数值是本应用的自带的Web应用目录。这个值是相对于WebUCCompanion应用根目录的路径。例如，如果本业务是部署在testWS1的目录下的话，那么这个参数值就设为testWS1/WebUCCompanion。Lperties这个文件是应用的日志配置文件，内容比较简单。主要关注的是其中日志文件的路径参数log4j.appender.A2.File，这个参数值应设置为对于应用服务器bin目录的相对路径，例如：log4j.appender.A2.File=././webapps/testWS1/WebUCCompanion/logs/webuc.log上述例子是当WebUCCompanion应用部署在Tomcat服务器的webapps/testWS1目录下的日志文件路径。WebUCConfig.xml这个文件是WebUCCompanion应用本身的业务级配置文件，需要配置的参数都是应用中需要读取的重要参数。在应用部署的时候，不需要修改该文件的配置信息。关于该文件中配置参数的信息，请直接参考该文本本身所提供的配置说明。5.2 中间件管理本中间件提供了基本的管理页面用于减少第三方web应用的开发量。第三方web应用在调用本中间件的其他用户接口进行服务时，必须进行中间件的管理设置。中间件管理分为两步，第一步是设置URL信息，页面如下： 上述各地址配置解释如下： 本地消息回调服务地址是设置本中间件相对于宽乐通信业务的web service组件的URL地址。中间件部署在不同平台上，这个URL的格式也有所不同，具体为：Uniportal/JBOSS平台：http:/$ip:$port/jboss-net/services/EventCallBackServiceTomcat平台：http:/$ip:$port/$context-root/WebUCCompanion/EventCallBackService.jwsWeblogic8.1平台：http:/$ip:$port/$context-root/WebUCCompanion/EventCallBackService?WSDL其中，$ip指集成本中间件的第三方web应用服务器地址，$port指服务器端口。注意，这里的http:/$ip:$port/ 必须是外网Internet能够访问得到的IP及端口。如果web服务器有公网的域名，可以用域名代替ip+port的形式。Tomcat平台和Weblogic8.1平台的URL格式中的$context-root字段是指集成本中间件的第三方web应用配置的web应用根路径。后面四个参数都是宽乐通信业务web service组件的地址，这几个地址的格式都是固定的，不用修改。需要修改的地方就是URL中的IP地址和PORT。将默认的IP地址和端口修改成为现网宽乐通信平台的IP和PORT或者域名就可以了。上面的URL都设置好以后，点击“确定”按钮就设置完成。URL地址设置完成以后，就需要进行宽乐通信注册操作。宽乐通信注册操作的页面如下：这个页面比较简单，只需要填入管理员宽乐账号及其密码，按确定即可。这里的管理员宽乐账号是用于在现网宽乐平台注册第三方应用的，其性质就类似与短信SP代号之类的。这个宽乐管理员账号需要各本地网向第三方web应用厂商分配。点击了“确定”按钮以后。中间件就执行向宽乐通信注册本第应用，如果执行成功，其返回的成功代码是0，如下图所示：注意，在以后每次第三方web应用服务器重启之后都要进行本操作。在注册操作完成以后，第三方web应用就可以通过用户接口向用户提供服务了。关于用户接口的使用，请参考文档宽乐通信Web Service接口中间件接口说明书V1.25_070608。5.3 Weblogic Server8.1部署问题处理本中间件在Weblogic Server8.1服务器上部署的时候可能会出现一些与其他服务器部署时不同问题，对这些问题的说明如下。1、 与Axis冲突问题本中间件使用Axis1.4作为web service客户端实现解决方案，而如果Weblogic Server8.1平台本身安装在UNIX/Linux服务器上，则有可能发生weblogic服务器与Axis冲突的问题。具体问题发生在当中间件做为web server客户端调用Axis1.4版本的库文件类时，服务器抛出异常信息，如下：Root cause of ServletException.javax.xml.parsers.FactoryConfigurationError: Factory class is the wrong type at javax.xml.parsers.DocumentBuilderFactory.newInstance(DocumentBuilderFactory.java:115) at org.apache.axis.utils.XMLUtils.getDOMFactory(XMLUtils.java:221) at org.apache.axis.utils.XMLUtils.(XMLUtils.java:83) at org.apache.axis.configuration.FileProvider.configureEngine(FileProvider.java:179) at org.apache.axis.AxisEngine.init(AxisEngine.java:172) at org.apache.axis.AxisEngine.(AxisEngine.java:156) at org.apache.axis.client.AxisClient.(AxisClient.java:52) at org.apache.axis.client.Service.getAxisClient(Service.java:104) at org.apache.axis.client.Service.(Service.java:113) at com.jiangh.webuc.ucservice.client.RegisterServiceClient1.getRandNum(RegisterServiceClient1.java:107) at com.jiangh.webuc.servicemanager.RegisterManager.RegToRemoteService(RegisterManager.java:50) at com.jiangh.webuc.webclient.RegisterWebClient.registerToService(RegisterWebClient.java:36) at jsp_servlet._webuccompanion._manager._gogetcallbackaddr._jspService(_gogetcallbackaddr.java:174) at weblogic.servlet.jsp.JspBase.service(JspBase.java:33) at ernal.ServletStubImpl$ServletInvocationAction.run(ServletStubImpl.java:971) at ernal.ServletStubImpl.invokeServlet(ServletStubImpl.java:402) at ernal.ServletStubImpl.invokeServlet(ServletStubImpl.java:446) at ernal.ServletStubImpl.invokeServlet(ServletStubImpl.java:305) at ernal.WebAppServletContext$ServletInvocationAction.run(WebAppServletContext.java:6354) at weblogic.security.acl.in