Apache Axis初级教程---安装、应用

本文讲述了 Apache Axis 的安装及简单应用，作为 Apache Axis 的一个入门教程。虽然现在 Apache Web Service 项目已经推出了 Apache Axis2 ， Axis2 相对 Axis 是一个很大的更新，关于 Apache Axis2 的介绍，请参考 http://ws.apache.org/axis2 ，目前的版本是 1.3 。既然已经有了 Apache Axis2 这个更加优秀的 Web Service Engine ，为什么还要介绍 Apache Axis 呢，原因在于系统的兼容性，从 Apache Axis 既存系统 Migration 到 Apache Axis2 有的时候并不是很容易，所以 Axis 还残留一些利用的价值。

本文主要介绍安装下载、安装、运行 Apache Axis 及部署一个样例 Web Service 并使用客户端进行调用。

关于 Apache Axis 的一些概念，摘录 Apache Axis 官方说明：

Apache Axis 是开源的 SOAP 服务器和客户端。 SOAP 是网络间不同语言的程序进行交互的方法。 SOAP 通常在 HTTP 上交换信息 : 客户端 POST 一个 SOAP 请求，然后接受 HTTP 响应， HTTP 的响应可能为成功代码、 SOAP 响应或者错误代码。

SOAP 消息的格式是 XML ，在不同的 SOAP 系统之间使用这种消息格式来对信息进行结构化。消息在 SOAP Envelope 中包含一个或者多个 SOAP 元素， Header 或者 SOAP Body 。

Axis 实现了 JAX-RPC API 。 JAX-RPC API 是 Java 服务编程的标准之一。

Axis 编译后的文件为 axis.jar ，它实现了在 jaxrpc.jar 和 saaj.jar 中声明的 JAX-RPC API 。它需要很多辅助类，例如日志、 WSDL 处理和内省。这些文件可以被打包成 axis.war ，然后将其部署到 servlet 容器中。 Axis 中附带了一些样例的 SOAP 服务程序。

 

前提条件：

本部分内容讲述的是 Java 的服务器端编程，设计的内容较多，主要是以下各部分内容，读者应该掌握或者了解以下内容：

1.         核心 Java 数据类型、类以及编程概念。

2.         线程、线程安全以及同步的概念。

3.         类加载器的概念以及层次化类加载器， "ClassNotFoundException" 的常见原因。

4.         如何从异常信息中分析问题， NullPointerException 以及一些常见异常的原因及修正方法。

5.         web 应用程序、 servlet 的概念，以及类、类库和数据在 web 应用程序中的分布位置。

6.         应用程序服务器的启动以及发布应用程序。

7.         网络的概念， sockets API ，尤其是 TCP/IP 。

8.         HTTP 的概念、核心协议以及错误代码， HTTP 头信息以及基本认证的细节。

9.         XML 的概念。

以上 9 条是 Apache Axis 中的说明，笔者认为除此之外，还应该对 WSDL(Web Service Description Language),SOAP(Simple Object Access Protocol) 有一定的了解。

另外， Apache Axis 1.4 需要 XML Parser 的支持，如果 Java 的版本是 Java 1.4 的话，那么已经包含了 XML Parser ，如果使用以前的版本，需要下载 XML Parser 并设置到系统 CLASSPATH 中。或者如果使用 Apache Tomcat 4.1 版本以后的服务器，都已经包含了 XML Parser 。推荐使用的 XML Parser 是 Xerces 。 Apache Axis 要求 jdk 的版本为 jdk 1.3+ 。

 

0. 下载必要的软件及 jar 文件。

本文需要下载一下软件及 jar 文件：

tomcat(tomcat5.5)

mail.jar(javamail)

activation.jar(jaf)

xmlsec.jar （ xmlsec ）

axis-1_4 （ axis ）

1. 设置环境变量

将下载的 axis-bin-1_4.zip 解压缩，解压缩后的目录为 AXIS_HOME ，目录结构如下：

假设 AXIS_HOME 为 d:/axis-1_4, 设置以下环境变量：

AXIS_HOME=d:/axis-1_4

AXIS_LIB=%AXIS_HOME%/lib

AXISCLASSPATH=%AXIS_LIB%/axis.jar;%AXIS_LIB%/commons-discovery-0.2.jar;%AXIS_LIB%/commons-logging-1.0.4.jar;%AXIS_LIB%/jaxrpc.jar;%AXIS_LIB%/saaj.jar;%AXIS_LIB%/log4j-1.2.8.jar;%AXIS_LIB%/wsdl4j-1.5.1.jar;

在 windows 系统中，可以将上述变量设置到环境属性中，避免每次执行 set 操作。通过查看 ” 我的电脑 ”--->” 属性 ” ，设置以上三个环境变量，如下图所示：

然后将 AXISCLASSPATH 添加到系统的 CLASSPATH 变量中，这样在执行需要用到 AXISCLASSPATH 中的类的时候，就不需要使用 java –cp %AXISCLASSPATH% 了。当然也可以不将其加入到系统 CLASSPATH 中， up to you 。

2. 安装 axis

拷贝 AXIS_HOME/webapps/axis 目录到你的应用程序服务器，这个服务器需要支持 Servlet 2.2 以上的规范，推荐使用 Tomcat 4.1 版本以上的服务器。当然也可以使用其他的服务器。笔者使用的服务器为 apache-tocmat-5.5.25 ，此时应该将 AXIS_HOME/webapps/axis 拷贝到 TOMCAT_HOME/webapps 目录下，即拷贝完成后 axis 的目录为 TOMCAT_HOME/webapps/axis 。

在 Java 1.4 中修改了以 java.* 和 javax.* 类的加载顺序，他们只能从 endorsed ( 认可的 ) 目录。 jaxrpc.jar 和 saaj.jar 包含 javax package ，所以可能没有被加载。如果 happyaxis.jsp 不能找到相关的类，那么应该将这些类由 TOMCAT_HOME/webapps/axis/WEB-INF/lib 下拷贝到 TOMCAT_HOME/common/lib 目录下，然后重新启动 Tomcat 。

Axis 需要找到一个 XML Parser ，如果应用程序服务器或者 Java 运行时环境没有相应的解析器 ( 并且 axis web 应用程序可以使用 ) ，那么就需要下载并添加。 Java 1.4 包含 Crimson 解析器，所以可以忽略这个步骤，虽然 Apache Axis 认为 Xerces 更好一些。

添加的 XML 解析器需要兼容 JAXP 1.1 。建议使用 Xerces jars ，下载地址为 xml-xerces distribution 。除非 JRE 或者服务器有明确的要求，否则的话可以将解析器的 jar 文件放在 axis/WEB-INF/lib 目录下。本部分如果使用 Xerces 的话，需要将 xml-apis.jar 和 xercesImpl.jar 文件拷贝到 AXISCLASSPATH 中 ( 如前所述 ), 这样 Axis 就可以使用 XML 解析器。

3. 查看 Axis 信息

启动 Tomcat 服务器，然后再地址栏输入 http://localhost:8080/axis ，根据需要修改主机名和端口号，应该可以看到如下页面：

其中主要的菜单如下：

Validation ：确认本地的安装配置是否成功，在该页面会对系统的配置做一个汇总，如果存在问题会以警告的消息进行醒目提示。

List ：列出当前可用的 Web Service 。

Call ：调用本地终端节点。

Visit ：访问 Apache Axis 官方网站。

Administrater Axis ：管理员信息，默认情况下是禁用的，可以通过修改 %TOMCAT_HOME%/webapps/axis/WEB-INF/web.xml 添加 servlet-mapping 来启用。

SOAPMonitor ： SOAP 监视器，默认情况下禁用，启用方法在后文介绍。

 

执行 Validation 操作，可以看到如下页面：

这就是所谓的 Axis Happiness 页面了，这个页面包含了如下的内容：

需要的组件

Ø         Found SAAJ API ( javax.xml.soap.SOAPMessage ) at D:/apache-tomcat-5.5.25/common/lib/saaj.jar

Ø         Found JAX-RPC API ( javax.xml.rpc.Service ) at D:/apache-tomcat-5.5.25/common/lib/jaxrpc.jar

Ø         Found Apache-Axis ( org.apache.axis.transport.http.AxisServlet ) at D:/apache-tomcat-5.5.25/webapps/axis/WEB-INF/lib/axis.jar

Ø         Found Jakarta-Commons Discovery ( org.apache.commons.discovery.Resource ) at D:/apache-tomcat-5.5.25/webapps/axis/WEB-INF/lib/commons-discovery-0.2.jar

Ø         Found Jakarta-Commons Logging ( org.apache.commons.logging.Log ) at D:/apache-tomcat-5.5.25/bin/commons-logging-api.jar

Ø         Found Log4j ( org.apache.log4j.Layout ) at D:/apache-tomcat-5.5.25/webapps/axis/WEB-INF/lib/log4j-1.2.8.jar

Ø         Found IBM's WSDL4Java ( com.ibm.wsdl.factory.WSDLFactoryImpl ) at D:/apache-tomcat-5.5.25/webapps/axis/WEB-INF/lib/wsdl4j-1.5.1.jar

Ø         Found JAXP implementation ( javax.xml.parsers.SAXParserFactory ) at an unknown location

Ø         Found Activation API ( javax.activation.DataHandler ) at D:/apache-tomcat-5.5.25/webapps/axis/WEB-INF/lib/activation.jar

可选组件 ( 用于附件、安全 )

Ø         Found Mail API ( javax.mail.internet.MimeMessage ) at D:/apache-tomcat-5.5.25/webapps/axis/WEB-INF/lib/mail.jar

Ø         Found XML Security API ( org.apache.xml.security.Init ) at D:/apache-tomcat-5.5.25/webapps/axis/WEB-INF/lib/xmlsec-1.4.0.jar

Ø         Found Java Secure Socket Extension ( javax.net.ssl.SSLSocketFactory ) at an unknown location

如果以上组件都存在，那么 Axis 将提示如下信息。

The core axis libraries are present.The optional components are present.

如果以上组件有缺少的，或者 Apache Axis 没有找到的，那么将会有警告信息。

( 笔者将 mail.jar 、 activation.jar 、 xmlsec-1.4.0.jar 都拷贝到了 %TOMCAT_HOME%/webapps/axis/WB-INF/lib 目录下，所以可以找到这三个软件包，实际上，这三个软件包并不是必须的，只是在一些例子程序中需要，但是如果缺少的话，在 tomcat 控制台会打印警告日志，提示找不到文件或者不能完成某些操作。 )

最后在该页面显示一些 Apache Tomcat 服务器的信息以及系统属性信息，诸如操作系统、浏览器、 Java 版本等等。

4. 测试 Axis 服务

查找服务

在开始页 (http://localhost:8080/axis) ，选择 List 链接，查看已经注册的 Web Services 。在这个页面可以点击 wsdl 的链接来查看 Web Service 是否正在运行。注意， Axis 支持的 JWS Web Service 并没有在这里列出。

测试 SOAP Endpoint

下面来测试一个服务。虽然 SOAP 1.1 使用 HTTP POST 来提交一个 XML 请求到 endpoint ，但是 Axis 也支持强制的 HTTP GET 方法来访问，这对测试很有帮助。首先测试一下获取 Axis 的版本这个服务，需要调用 getVersion 方法：

http://localhost:8080/axis/services/Version?method=getVersion

这个例子返回的值应该与下面的结果类似：

 <?xml version="1.0" encoding="UTF-8" ?>
 <soapenv:Envelope
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <soapenv:Body>
      <getVersionResponse
          soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <getVersionReturn
              xsi:type="xsd:string">
              Apache Axis version: 1.1 Built on Apr 04, 2003 (01:30:37 PST)
          </getVersionReturn>
      </getVersionResponse>
      </soapenv:Body>
 </soapenv:Envelope>

不同的 Axis 的版本显示也不同。

测试 JWS Endpoint

现在测试一个 JWS Web Service 。 Axis 的 JWS Web Service 就是 java 文件，保存在 Axis webapp 的目录树中，但是不能保存在 WEB-INF 目录中，并且文件扩展名为 .jws 。当通过 URL 请求 .jws 文件的时候，它会被编译并执行。

通过请求样例程序 EchoHeaders.jws ( 这个文件保存在 axis 目录下 ) 。

在浏览器中访问 http://localhost:8080/axis/EchoHeaders.jws?method=list

这时会返回如下 XML 格式的消息，显示了应用程序 Headers 的信息：

<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <listResponse
            soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
            <listReturn xsi:type="soapenc:Array"
                soapenc:arrayType="xsd:string[6]"
                xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
                <item>accept:image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*</item>
                <item>accept-language:en-us</item>
                <item>accept-encoding:gzip, deflate</item>
                <item>user-agent:Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)</item>
                <item>host:localhost:8080</item>
                <item>connection:Keep-Alive</item>
            </listReturn>
        </listResponse>
    </soapenv:Body>
</soapenv:Envelope>

到目前为止， Apache Axis 安装完成，并正常工作。

5. 安装新的 Web Service

安装新的 Web Service 的过程主要分以下两个步骤：

(1)     将新的 Web Service 的类和类库放到 Axis WAR 目录树中

(2)     将新的文件通知 AxisEngine

后者是通过 Admin web 服务来提交一个 XML 部署描述符给 Axis 来完成的，通常是通过 AdminClient 来完成或者 <axis-admin> 这个 Ant 任务来完成。两者实现的功能是一致的：执行 Axis SOAP 客户端来和 Axis 管理服务通信 (Axis web service 是一个 SOAP service 。 ) 。同时它也是一个特殊的 SOAP service ，因为只能在本地调用，并且是密码保护的，这样可以阻止远程调用和防止任何人使用管理程序。客户端知道一个默认的密码。当修改这个密码时，需要告诉客户端。

第一步是将代码添加到服务器。在 WEB-INF 目录中，查找 ( 或者创建 )classes 目录。在这个目录中，将编译后的 Java 类文件拷贝到这里，注意 Java 包层次结构。

如果类文件已经打包成 JAR 文件，那么可以将其放在 WEB-INF/lib 目录中。其他的第三方类库 (jar) 也放在这个目录中。

当添加完类文件或者类库文件后，需要重新启动 axis web 应用程序，使用 Tomcat 管理控制台重启 webapp 或者重启 Tomcat 服务器。

6. 发布 Web Service

在 (5) 中已经完成安装 Web Service ，现在需要做的就是告诉 Axis 如何发布这个 Web Service 。 Axis 使用 Web 服务部署描述符 (WSDD) 文件 (XML 格式的文件 ) 来描述 Web 服务：服务方法和 SOAP endpoint 的其他内容。

在 Apache Axis 的用户指南中详细描述了 WSDD 文件，现在来运行一个 Axis 样例： Stock Quote 服务。

根据前面的内容，已经设置 AXIS_HOME 、 AXIS_LIB 、 AXISCLASSPATH 环境变量，并将其添加到 CLASSPATH 中。 ( 在 Apache Axis 的安装指南中没有将其添加到 CLASSPATH 中，而是使用 java –cp %AXISCLASSPATH% JavaClass 的形式来使用 ) 。

在 AXIS_HOME/sampes/stock 目录下，包含了 deploy.wsdd 文件，这就是需要告诉给 axis 的部署描述符。如下图所示文件位置：

         不是描述符是 Axis-specific 的 XML 文件，用于告诉 Axis 发布或者卸载一个 Web Service ，以及如何配置 Axis 自身的文件。 Axis Administration Web Service 允许 AdminClient 程序或者它对应的 Ant 任务提交一个用于说明的 WSDD 文件。 Axis “engine” 会更新配置信息，并保存状态。

         默认情况下， Axis 将状态保存到一个全局的配置文件 TOMCAT_HOME/webapps/axis/WEB-INF/server-config.wsdd 。有的时候在服务器启动的时候会看到一个警告信息，说 server-config.wsdd 文件不存在，没有关系，因为 Axis 在部署任意服务后就会自动的创建这个文件。部署完成后可以查看这个文件的内容。

         进入 AXIS_HOME/samples/stock 目录，执行以下命令：

         java org.apache.axis.client.AdminClient –lhttp://localhost:8080/axis/services/AdminService deploy.wsdd

         运行结果如下： ( 由于笔者先前已经部署过这个 web service ，所以先 undeploy 一下，然后再进行 deploy)

( 如果在执行的时候发生 java 客户端异常，比如 ClassNotFoundException ，需要检查 AXISCLASSPATH 及 CLASSPATH 是否设置正确，是否写错了类名或者其他的一些错误。 )

         执行后，在 TOMCAT_HOME/axis/WEB-INF/ 目录下生成了 server-config.wsdd 文件，其内容的说明，在用户指南有详细的介绍，这里不做介绍。

         测试客户端访问：

         返回到 AXIS_HOME 目录，执行下面的命令：

         java –cp .;%AXISCLASSPATH% samples.stock.GetQuote –lhttp://localhost:8080/axis/servlet/AxisServlet –uuser1 –wpass1 XXX

         运行结果如下：

 

7. 高级安装：将 Axis 添加到应用程序中

如果对于 Web 应用程序开发很熟悉的话，那么可能需要将 web services 添加到一个已经存在的 web 应用程序中，可以通过这种办法来运行 Axis 。与安装 web service 到 Axis 不同，需要将 Axis 添加到 Web 应用程序。

¨         将 axis.jar 、 wsdl.jar 、 saaj.jar 、 jaxrpc.jar 以及其他依赖的 jar 文件添加到自定义的 WAR 文件中。

¨         将 Axis Servlet 的声明从 TOMCAT_HOME/webapps/axis/WEB-INF/web.xml 文件中拷贝到自定义的 web.xml 文件中。

¨         构建并部署 webapp 。

¨         运行 Axis AdminClient 来访问 webapp ，而不是 Axis ，这时需要修改访问的 URL 。

8. 启用 SOAPMonitor

SOAPMonitor 允许通过 Web 浏览器来监视 SOAP 请求和响应。关于 SOAPMonitor 的使用，可以参考用户指南中的相关部分。

默认情况下， SOAPMonitor 是禁用的。启用它的基本步骤如下：编译 SOAP Monitor java applet 、发布 SOAP Monitor web service 、在需要监视的 web service 中添加请求和响应的处理流。

(1) 进入到 AXIS_HOME/webapps/axis 目录，然后编译 SOAPMonitorApplet.java 程序：

javac –classpath %AXIS_HOME%/lib/axis.jar SOAPMonitorApplet.java

运行结果如下：

D:/axis-1_4/webapps/axis>javac -classpath %AXIS_HOME%/lib/axis.jar SOAPMonitorAp

plet.java

         将编译后的 SOAPMonitorApplet*.class 文件拷贝到 TOMCAT_HOME/webapps/axis 目录下。

(2) 发布 SOAPMonitorService

将下面的内容拷贝到一个文件中，并保存为 deploy-monitor.wsdd 文件，作为 SOAPMonitorService 的部署描述符，将其保存在 AXIS_HOME/webapps/axis 目录下 ( 文件名和目录任意 )

<deployment xmlns="http://xml.apache.org/axis/wsdd/"

    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

 <handler name="soapmonitor"

      type="java:org.apache.axis.handlers.SOAPMonitorHandler">

    <parameter name="wsdlURL"

      value="/axis/SOAPMonitorService-impl.wsdl"/>

    <parameter name="namespace"

      value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/>

    <parameter name="serviceName" value="SOAPMonitorService"/>

    <parameter name="portName" value="Demo"/>

 </handler>

 <service name="SOAPMonitorService" provider="java:RPC">

    <parameter name="allowedMethods" value="publishMessage"/>

    <parameter name="className"

      value="org.apache.axis.monitor.SOAPMonitorService"/>

    <parameter name="scope" value="Application"/>

 </service>

</deployment>

进入到 deploy-monitor.wsdd 保存的目录，执行如下程序：

java –cp %AXISCLASSPATH% org.apache.axis.client.AdminClient –lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd

运行结果如下：

(3) 对于每个要监视的服务，在服务部署描述符中添加请求和响应的 flow 定义并部署 ( 或者重新部署 ) 服务。 requestFlow 和 responseFlow 定义在 <service> 元素后面，如果一个服务已经发布了，那么首先 undeploy ，之后使用修改后的部署描述符 deploy 。下面是一个例子：

...

<service name="xmltoday-delayed-quotes" provider="java:RPC">

    <requestFlow>

      <handler type="soapmonitor"/>

    </requestFlow>

    <responseFlow>

      <handler type="soapmonitor"/>

    </responseFlow>

    ...

(4) 使用 Web 浏览器输入 http://host:port/webapp/SOAPMonitor 就可以 SOAP 请求和响应消息了。
例如，重新访问stock这个样例服务时，可以看到如下消息：
SOAP Reuqest:
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <ns1:getQuote soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="urn:xmltoday-delayed-quotes">
      <symbol xsi:type="xsd:string">XXX</symbol>
    </ns1:getQuote>
  </soapenv:Body>
</soapenv:Envelope>
SOAP Response:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <ns1:getQuoteResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="urn:xmltoday-delayed-quotes">
      <getQuoteReturn xsi:type="xsd:float">55.25</getQuoteReturn>
    </ns1:getQuoteResponse>
  </soapenv:Body>
</soapenv:Envelope>

 

总结： Axis 是 SOAP 的一个简单实现，可以添加到可以操作 web 服务的应用程序中。