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

广东电信有限公司研究院
宽乐通信Web Service接口中间件
WebUCComapionV1.12部署说明书

江洪
2007-6-7

本文描述WebUCCompanionV1.12版本在各种应用服务器的部署流程。另外，对管理维护操作也作了一定的说明

目录
第1章 文档说明 3
第2章 Uniportal服务器部署 3
2.1 安装uniportal平台 3
安装过程 3
2.2 安装WebUCComapionV1.12 6
安装过程 6
2.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.jar
uniportalv100r001d330平台运行期文件
serviceonly_ins.jar
WebUCComapionV1.12版本文件
jboss-net.sar
J模块
log4j.properties
日志配置文件
WebUCConfig.xml
WebUCComapionV1.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.jar

Please 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 Settings\z30607]d:/portal

提示:d:\portal目录不存在
输入Y-创建;输入N-重新选择安装目录;E-退出安装:[Y]

端口号设置

请输入HTTP端口号:[8080]

WebService端口:[8083]
JNDI端口:[1099]
RMI invoker端口:[4444]
JMX端口:[7888]
JMX的HTML管理端口:[8889]
UIL2ServerILService 端口:[8092]
RMI Naming Service 端口:[1098]
pooled invoker 端口:[4445]
MC Https 端口:[7443]

是否安装安全证书？
输入Y-安装;输入N-不安装:[Y]

请输入HTTPS端口号:[8443]

请输入生成安全证书的参数:
请输入您的站点域名:[unknown]localhost
请输入您的组织单位名称:[unknown]huawei
请输入您的组织名称:[unknown]com
请输入您所在的城市和区域名称:[ShenZhen]NanJing
请输入您所在的洲或者省份的名称:[GuangDong]JiangSu
请输入该单位的两字的国家代码:[CN]
请输入别名:[unknown]portal
请输入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
执行启动文件目录
conf
Portal系统配置文件目录
definition
Portal平台相关配置文件目录
deploy
部署文件目录
jboss
Jboss工作目录
lib
系统库文件目录
logs
日志目录
service
业务部署目录
work
系统工作目录

2.2 安装WebUCComapionV1.12
在安装完成uniportal平台后，就可以开始业务的安装。
在命令行方式下执行java –jar serviceonly_ins.jar即可安装业务。
安装过程
F:\>java -jar serviceonly_ins.jar
Prepare 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 Settings\z31483]f:\ddd
目录不存在或你没有写权限! 重新输入? Y--是, others-退出:[Y]

输入安装的目标目录:[C:\Documents and Settings\z31483]f:\1_temp
目录不是一个uniportal的目录!重新输入? Y--是, others-退出:[Y]

输入安装的目标目录:[C:\Documents and Settings\z31483]f:\ttt
在这里选择的安装目标目录是uniportal平台的安装目录

#########################安装参数设置如下:#############################
## 安装路径:f:\ttt ##
####################################################################
输入Y-使用上述参数进行安装;输入N-修改参数设置E-退出安装:[Y]

..............
Deploying servcies...Done!
Checking plugin...Done!

安装完成!
在业务安装完成后，需要运行业务部署命令，完成业务部署，业务部署命令是
uniportal deploy（Window操作系统）
或
./uniportal.sh deploy（UNIX、Linux操作系统）。

2.3 文件配置
在业务部署完成以后，就要进行业务文件配置。主要是安装模块，部署log4j.properties和WebUCConfig.xml两个配置文件。
安装模块就是将jboss-net.sar目录文件拷贝到%uniportal%/deploy目录下即可。
安装模块后，在将业务配置文件log4j.properties和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-INF\web.xml
WebUCCompanion应用Tomcat服务器启动配置文件
WEB-INF\lib\
Axis平台文件和WebUCCompanion业务运行期文件
WEB-INF\jwsClasses\
WebUCCompanion的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目录下，进入到WebUCCompanion\conf下，打开log4j.properties文件，将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-INF\web.xml
本中间件WebUCCompanion应用需要配置的web容器配置文件，主要用于服务器启动时初始化WebUCCompanion应用
WEB-INF\ weblogic.xml
Weblogic平台配置文件
WEB-INF\ web-services.xml
本中间件WebUCCompanion应用的web service服务器端组件部署描述符文件
WEB-INF\lib\
本中间件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-INF\weblogic.xml文件是weblogic服务器的参数描述文件。部署时，将这个文件用文件编辑器打开，将其中标签下的内容粘贴到服务器上原有的weblogic.xml文件中就可以了。
注意，如果服务器上原有的weblogic.xml文件中如果已经存在标签且其中的内容与解压文件weblogic.xml中的一致就不需要进行粘贴操作。
4、 修改第三方web应用的web.xml文件
解压文件WEB-INF\web.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-INF\lib\中所有的文件到拷贝（上传）到第三方web应用WAR目录下的WEB-INF\lib\目录即可。如果服务器上第三方应用的WEB-INF目录下没有lib目录，可以新建这个目录再进行文件拷贝（上传）。
6、 拷贝（上传）WebUCCompanion目录
这一步是要将解压目录WebUCCompanion整个拷贝（上传）到第三方web应用的WAR目录下即可。
拷贝（上传）完成后进入到服务器上的WebUCCompanion/conf目录中，用文件编辑器打开log4j.properties文件，将其中的${WEB_APPLICATION_WARDIR}修改成第三方web应用的WAR目录的绝对路径。
7、 设定业务参数值
在上传到服务器的解压目录WebUCCompanion\的conf目录下，有一个ServiceParameters.properties文件。该文件是指定中间件使用的几个必要的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：应用服务器应用初始化文件。
Log4j.properties：日志配置文件
WebUCConfig.xml：应用配置文件

Web.xml
在本应用中，web.xml的配置主要是为了使应用服务器在启动的时候初始化本应用，其内容是在Web.xml中添加一个servlet标签，格式为：

WebUCCompanionServlet
WebUCCompanion Servlet

com.jiangh.webuc.servicemanager.ThirdPartyServerApp

log4j config file path
value>./../webapps/testWS1/WebUCCompanion/conf/log4j.properties

webUCCompanion config file path
./../webapps/testWS1/WebUCCompanion/conf/WebUCConfig.xml

>
web application root dir
testWS1/WebUCCompanion

14

在这个配置文件中，主要需要关注的参数是3个init-param的param-value值。第一个init-param是log4j.properties配置文件的位置。这个位置是指其对于应用服务器的bin目录的相对路径值。例如，如果本业务是部署Tomcat服务器上的webapps/testWS1的目录下的话，那么这个参数值就设为./../webapps/testWS1/WebUCCompanion/conf/log4j.properties。
第二个init-param是业务配置文件WebUCConfig.xml对于Tomcat服务器bin目录的相对路径值。例如，如果本业务是部署在Tomcat服务器上的webapps/testWS1的目录下的话，那么这个参数值就设为./../webapps/testWS1/WebUCCompanion/conf/WebUCConfig.xml。
第三个init-param参数值是本应用的自带的Web应用目录。这个值是相对于WebUCCompanion应用根目录的路径。例如，如果本业务是部署在testWS1的目录下的话，那么这个参数值就设为testWS1/WebUCCompanion。
Log4j.properties
这个文件是应用的日志配置文件，内容比较简单。主要关注的是其中日志文件的路径参数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/EventCallBackService
Tomcat平台：
http://${ip}:${port}/${context-root}/WebUCCompanion/EventCallBackService.jws
Weblogic8.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(Register