Apache Axis配置文件参考指南

Aapche Axis的Web Service Deployment Descriptor(WSDD)文件参考文档。

本部分介绍的所有的 WSDD 元素的名称空间都是 "http://xml.apache.org/axis/wsdd/" 。

<deployment>

告诉 Axis Engine 这是一个部署描述文件。一个部署描述文件可以表示一个完整的 engine 配置或者将要部署到一个活动 active 的一部分组件。

<GlobalConfiguration>

用于控制 engine 范围的配置。可以包含以下子元素：

·   <parameter> : 用来设置 Axis 的各种属性，参考 Global Axis Configuration ，可以配置任意数量的参数元素 .

·   <role> : 设置一个 SOAP actor/role URI ， engine 可以对它进行识别。这允许指向这个 role 的 SOAP headers 成功的被 engine 处理。任意数量 .

·   <requestFlow> : 全局的请求 Handlers 。在调用实际的服务之前调用 .

·   <responseFlow> : 全局响应 Handlers ，在调用完实际的服务后，还没有返回到客户端之前调用 .

<requestFlow [name=" name "] [type=" type "] >

可以放置任意多个<handler> or <chain> 在<requestFlow> 中 ，但是可能只有一个<requestFlow> .

<responseFlow [name=" name "] [type=" type "] >

This is used to configure handlers in response flow. You may put any number of <handler> or <chain> elements (see below) inside the <responseFlow>, but there may only be one <responseFlow>.

<undeployment>

部署文档的根元素，用于指示 Axis 这是个卸载描述文件 .

<handler [name=" name "] type=" type ">

位于顶层元素<deployment> or <undeployment>, or inside a <chain>, <requestFlow>, or <responseFlow>. 用于定义 Handler ，并定义 handler 的类型。 "Type" 可以是已经定义的 Handler 或者是 "java:class.name" 形式的 QName 。可选的 "name" 属性允许将这个 Handler 的定义在其他部署描述部分中引用。可以包含任意数量的<parameter name= " name " value=" value "> 元素 .

<service name=" name " provider=" provider " >

部署 / 卸载一个 Axis 服务。这是最复杂的一个 WSDD 标签。

Options可能通过以下元素来指定 : <parameter name="name" value="value"/>, 一些常用的包括 :

·   className : 后台实现的类

·   allowedMethods : 每个 provider 可以决定那些方法允许 web services 访问

Axis 支持的 providers 有如下几种 :

Java RPC Provider (provider="java:RPC") 默认情况下所有的 public 方法都可以 web service 方式提供

Java MsgProvder (provider="java:MSG")

为了更进一步的限制上面的方法，allowedMethods 选项用于指定一个以空格分隔的方法名，只有这些方法可以通过 web service 访问。也可以将这个值指定为 ”*” 表示所有的方法都可以访问。同时operation 元素用来更进一步的定义被提供的方法，但是它不能决定方法的可见性 .

注意，发布任何web service都有安全含义.

·   allowedRoles : 都好分离的允许访问服务的角色列表。注意，这些是安全角色，和 SOAP 角色相反。安全角色控制访问， SOAP 角色控制哪些 SOAPheaders 会被处理。

·   extraClasses : 指定一个空格或者都好分离的类名称列表，这些类的名字应该被包含在 WSDL 文档的类型定义部分。当服务接口引用一个基类的时候，或者希望 WSDL 文件包含其他类的 XML Schema 类型定义的时候，这个参数很有用。

如果希望为服务定义 handler ，可以在<service> 元素中添加<requestFlow> 和<responseFlow> 子元素。他们的语义和<chain> 元素中的定义时一样的。也就是说，它们可以包含<handler> and <chain> 元素，根据指定的顺序被调用 .

通过服务的 Handlers 来控制角色，可以在服务声明中指定任意数量的<role> 元素。

例如 :

<service name="test">

 <parameter name="className" value="test.Implementation"/>

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

 <namespace>http://testservice/</namespace>

 <role>http://testservice/MyRole</role>

 <requestFlow> <!-- Run these before processing the request -->

    <handler type="java:MyHandlerClass"/>\

    <handler type="somethingIDefinedPreviously"/>

 </requestFlow>

</service>

可以通过使用 <operation> 标签指定关于服务的特殊操作的元数据。这可以将方法的 java 参数名和特定的 XML 名进行映射，为参数指定特定的模式，并将特定的 XML 名字映射到特定的操作。 例如

<operation name="method">

</operation>

<chain name=" name ">
<subelement/>...
</chain>

定义一个链。当 chain 被调用的时候，按顺序调用其中的 handler 。这样就可以构建一个常用功能的模块， chain 元素的子元素可以是 handler 或者 chain 。 handler 的定义形式可以是如下两种方式 :

<chain name="myChain">
 <handler type="java:org.apache.axis.handlers.LogHandler"/></chain>

或者

<handler name="logger" type="java:org.apache.axis.handlers.LogHandler"/>
<chain name="myChain"/>
   <handler type="logger"/></chain>

<transport name=" name ">

定义了一个服务器端的传输。当一个输入请求到达的时候，服务器传输被调用。服务器传输可能定义<requestFlow> and/or <responseFlow> 元素来指定 handlers/chains ，在请求和响应被处理的时候被调用，这个功能和 service 元素中的功能一样。典型的传输请求响应 handler 实现了关于传输的功能。例如转换协议 headers 等等 .

对于任何种类的传输，经常是指 HTTP 传输，当特定的查询字符串传递到 servlet 的时候用户可能允许 Axis servlets 执行任意的动作，以 plug-in 的方式。 ( 参考 Axis Servlet Query String Plug-ins). 当查询字符串 handler 的类名被指导后，用户可以通过在<transport>中 添加合适的<parameter> 来启用它 ( 插件 ) 。

<transport name="http">
  <parameter name="useDefaultQueryStrings" value="false" />
  <parameter name="qs.name" value="class.name" /></transport>
在上面的例子中， AxisServlet 会处理的查询字符串是 ?name ，它调用的类是 class.name 。<parameter> 元素的 name 属性必须加上前缀 qs 来表示这个元素定义了一个查询字符串 handler 。 value 属性值相实现了 org.apache.axis.transport.http.QSHandler 接口的类。默认情况下， Axis 提供了三个 Axis servlet 查询字符串 handlers (?list, ?method, and ?wsdl). 查看 Axis 服务器配置文件来了解它们的定义。如果不希望使用默认的 handlers ，就设置 "useDefaultQueryStrings" 为 false 。默认会被设置成 true.

<transport name=" name " pivot=" handler type " >

定义了一个客户端的传输，当发送 SOAP 消息的时候来调用。 "pivot" 属性指定一个 Handler 来作为实际的传输 sender ，例如 HTTPSender 。请求和响应流和服务器端的设置相同 .

<typeMapping qname=" ns:localName " classname=" classname " serializer=" classname " deserializer=" classname "/>

每个 typeMapping 将一个 XML qualified 名字和一个 Java 类进行映射，使用一个序列器和反序列器。

<beanMapping qname=" ns:localName " classname=" classname ">

讲话的类型映射，使用一个预定义的序列器 / 反序列器来编码 / 解码 JavaBeans 。

<documentation>

在<service> , <operation> 或者操作的<parameter>中使用。 . 是文档说明，生成 wsdl 的 <wsdl:document> 元素 .

Example:
<operation name="echoString" >
  <documentation>This operation echoes a string</documentation>  <parameter name="param">
     <documentation>a string</documentation>
  </parameter>
</operation>

全局的Axis配置参数

服务默认的是通过 server-config.wsdd 文件中的值来进行配置的。但是熟练的 Axis 用户可以写自己的配置 handler ，这样就可以将配置数据保存在 LDAP 服务器，数据库或者远程的 web service 等等。查看源代码来了解如何实现。也可以在 web.xml 文件中使自动的获取配置信息。但是 Axis 不推荐这样使用，因为最好将配置信息放在一个位置。

在 server-config 文件中，有一个全局配置部分，支持以名 / 值对的形式作为嵌套元素使用。

<globalConfiguration>

    <parameter name="adminPassword" value="admin"/>

    <parameter name="axis.servicesPath" value="/services/"/>

    <parameter name="attachments.Directory" value="c:\temp\attachments"/>

    <parameter name="sendMultiRefs" value="true"/>

    <parameter name="sendXsiTypes" value="true"/>

    <parameter name="attachments.implementation" value="org.apache.axis.attachments.AttachmentsImpl"/>

    <parameter name="sendXMLDeclaration" value="true"/>

    <parameter name="enable2DArrayEncoding" value="true"/>

    <parameter name="dotNetSoapEncFix" value="false"/>

</globalConfiguration>

单独的Service(服务)配置

<service name="MyServiceName"

                   provider="java:RPC"

                   style="rpc|document|wrapped"

                   use="encoded|literal"

                   streaming="off|on"

                   attachment="MIME|DIME|NONE">

 <parameter name="className" value="org.apache.mystuff.MyService"/>

 <parameter name="allowedMethods" value="method1 method2 method3"/>

 <parameter name="wsdlTargetNamespace" value="http://mystuff.apache.org/MyService"/>

 <parameter name="wsdlServiceElement" value="MyService"/>

 <parameter name="wsdlServicePort" value="MyServicePort"/>

 <parameter name="wsdlPortType" value="MyPort"/>

 <parameter name="wsdlSoapActionMode" value="NONE|DEFAULT|OPERATION"/>

 <parameter name="SingleSOAPVersion" value="1.1|1.2/>

 <documentation>Service level info</documentation>

 <endpointURL>http://example.com:5050/my/custom/url/to/service</endpointURL>

 <wsdlFile>/path/to/wsdl/file</wsdlFile>

 <namespace>http://my.namespace.com/myservice</namespace>

 <handlerInfoChain>handlerChainName</handlerInfoChain>

 <operation ... />

 <typeMapping ... />

 <beanMapping ... />

</service>

单独的Operation(操作)配置

<operation name="GetQuote"

           qname="operNS:GetQuote"

           returnQName="GetQuoteResult"

           returnType="xsd:float"

           soapAction=""

           returnHeader="true|false">

    <documentation>Operation level documentation here</documentation>

    <parameter name="ticker" type="tns:string"/>

    <fault name="InvalidTickerFaultMessage"

           qname="tickerSymbol"

           class="test.wsdl.faults.InvalidTickerFaultMessage"

           type="xsd:string"/>

</operation>

由于 Service 的配置和 Operation 的配置很容易理解，各个参数也都使用了 self-explanation 的表示，所以这里就不再赘述了。

同时 Axis 还定义日志配置以及一些预定义的 Handler ，详细内容，参考 Axis 的参考文档。