mule in action翻译15 : 3.3  使用HTTP传输

3.3  使用HTTP传输

    本节讲mule对HTTP和web service的支持。对HTTP的支持，使从web站点或应用接受或发送数据变的更简单。mule支持 JAX-RS和JAX-WS，提供了对REST和SOAP的API支持。

3.3.1 使用HTTP发送和接受数据

    HTTP传输允许你使用HTTP协议进行发送和接受数据。你可以通过outbound endpoint使用HTTP的POST方法发送数据，或在请求-响应式的inbound endpoint 以GET返回返回数据。表2.3列举了 HTTP 连接器和 endpoint的的一些常用的配置元素。

     来看如何使用 HTTP outbound endpoint向一个URL发送POST数据。Arnor Accounting公司开发人员同意

了Prancing Donkey公司以 XLS文件方式上传支出报表。如果他们还没使用mule，这将是一个大问题。

他们的开发人员将会删掉一片代码--拷贝文件到会计人员目录的代码，而替换为以POST 方式把文件内容

发送到远程的URL.

使用mule 他们只需要简单的改变outbound endpoint，像如下列表以及图3.6所示。

Listing 3.2 Posting data with the HTTP transport

<flow name="postExpenseReports">
    <file:inbound-endpoint path="./data/expenses/2/in"
               pollingFrequency="60000">
    <file:filename-regex-filter pattern=".*xls$"
                          caseSensitive="false"/>
    </file:inbound-endpoint>
    <--!使用HTTP endpoint把支出报表POST出去-->
    <http:outbound-endpoint host="${http.host}"
                            port="${http.port}"
                            path="expenseReports"
                          method="POST"/>
</flow>      

    把file:outbound-endpoint 替换为  http:outbound-endpoint就够了。数据不再需要写向文件，而是需要发送到远程web应用。

   使用一个HTTP作为一个消息是相当容易的。既然处理支出文件会花费一些时间，那么 SaaS应用可以异步的处理文件。Arnor Accounting的开发人员已经添加了一个功能：当报表被处理完成后会向一个特定的URL发送一个通知。现在  Prancing Donkey公司想接收这个通知并写入到文件系统，之后监控系统可以解析其中的错误。（你将这在3.4节是如何改进的）。

下面列表说明了如何配置，图3.7是图形化表示

Listing 3.3 Using an HTTP inbound endpoint to POST data to a file 

<flow name="expenseReportCallback">
<!--注释1  在 http://${http.host}/expenses/status   接收HTTP请求-->
<http:inbound-endpoint host="${http.host}"
                      port="${http.port}"
                      path="expenseReportCallback"
                    method="POST"
          exchange-pattern="one-way"/>

<!--注释2   把支出报表处理状态写到 ./data/expenses/status 目录-->
<file:outbound-endpoint path="./data/expenses/status"
               outputPattern="#[java.util.UUID.randomUUID().toString()]
                               -#[org.mule.util.DateUtils.getTimeStamp
                               ('dd-MM-yy_HH-mm-ss.SSS')]
                         .xml"/>

</flow>      

    注释1处  配置的HTTP inbound endpoint 接收HTTP POST请求，将包含状态通知。

这些传送的payload 将被写到配置的目录中。注意之前的流和当前的流，都使用的是 单向交换方式。

这允许你使用HTTP模拟异步请求，但HTTP是一个同步协议。本案例中，mule将返回 200 OK的响应给

客户端，除非流跑出了异常。第9章你会看到异常处理。

  HTTPS   你将看到的所有的HTTP例子都是默认的未加密的。第10章讨论HTTPS 和 SSL .

  异步处理HTTP请求是一个有用的技术。它允许你通过HTTP实现消息的API.

  你处理最多的HTTP请求还是请求-响应式的。

  3.3.2 mule使用 web services 

      Prancing Donkey公司有一个叫做BrewService的服务类，开发人员想他它暴露给外部客户端使用。

  这个服务当前一个方法 getBrews()，它会返回前的啤酒列表。这个方法返回一个List， list的每个元素是一  个Brew的实例--这是他们域模型的一部分。列表 3.4 、3.5 、3.6详细  列出了BrewService接口和实现以及域  模型类Brew.

  JAX-RS AND JAX-WS   本节的例子中将使用JAX-RS 和 JAX-WS标准，对这两个标准的讨论

      超出了本书的范畴。要了解其详细信息，包括怎样在模型类使用注解控制序列化，

 请参考 http://jersey.java.net  和 http://cxf.apache.org/ 。

  Listing 3.4 The BrewService interface

package com.prancingdonkey.service;
public interface BrewService {
    List<Brew> getBrews();
}  
           

Listing 3.5 The BrewService implementation

package com.prancingdonkey.service;
public class BrewServiceImpl implements BrewService {
    List<Brew> getBrews() {
       return Brew.findAll();
    }
}
           

Listing 3.6 The Brew domain model

package com.prancingdonkey.model;
public class Brew implements Serializable {
    String name;
    String description;
    public Brew(String name, String description) {
        this.name = name;
        this.description = description;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getDescription() {
        return description;
    }
    public void setDescription(String description) {
        this.description = description;
    }

    static public List<Brew> findAll()
    {
       // Returns a List of Brews
        return ...
     }
}
           

  我们现在看如何使用REST和SOAP暴露getBrews() 方法给外部用户。

REST 和  JAX-RS

    JAX-RS是 RESTful风格的web service 的java API。mule支持Jersey，它是JAX-RS的一个实现，允许你在mule流中使用JAX-RS注解开发RESTfull风格的web service。来注解BrewServiceImpl以JSON 方式返回啤酒目录。

Listing 3.7 The JAX-RS annotated BrewService

package com.prancingdonkey.service;
@Path("/brews")  //注释1 URI路径的root
public class BrewServiceImpl implements BrewService {

    @GET  //注释2  接受的 HTTP 方法
    @Produces("application/json")  //注释3  方法的返回值类型
    List<Brew> getBrews() {

      return Brew.findAll();
    }
}
           

  注释1 处  @Path注解指定了本类中你暴露的方法的根URI（你也可以在方法上指定@Path来

                  进一步限定路径）

  注释2处  @GET注解指明这个方法只对HTTP GET请求进行响应。

  注释3处  @Produces注解表明将返回JSON格式的响应。

  现在BrewServiceImpl已别注解好，来把它放到流中。下面的列表说明了如何在流中配置。

Mule studio中图见 图3.8

Listing 3.8 Expose the brew listing over REST using JAX-RS 

<flow name="brewRestService">
<!--注释1  HTTP inbound endpoint接受REST请求-->
<http:inbound-endpoint address="http://localhost:8091/rest"
exchange-pattern="request-response"/>
<jersey:resources>
<!--注释2  要暴露为Jersey资源的类-->
<component class="com.prancingdonkey.service.BrewServiceImpl"/>
</jersey:resources>
</flow>
      

注释1处  设置拦截RESTfull请求。

注释2处  暴露注释的JAX-RS类

现在你可以启动mule，执行你的请求了。

来使用curl调用下这个服务看看会发生什么。

Listing 3.9 Using curl to invoke the web service

% curl

http://api.prancingdonkey.com/rest/brews/list

[ {"name":"Frodo's IPA", "description":"Indian Pale Ale" }, {

"name":"Bilbo's Lager", "description":"Indian Pale Ale" }, {

"name":"Gandalf's Barley Wine", "description":"Indian Pale Ale" } ]

curl对 rest/brews/list URI的请求返回 方法的响应，元素时Brew的list，序列化为JSON.

你可以通过JAXB定制如何生存JSON.

现在来看 如何根据mule对JAX-WS的支持把同样的服务暴露为SOAP方式访问的服务。

调用 REST 服务的工具   Curl是一个可以用来与REST 服务进行交互的命令行工具。

可以在 http://curl.haxx.se/ 进行下载。另外一个强大的工具是 google chrome浏览器

的 REST  Console。可用chrome连接http://restconsole.com. 安装。

SOAP 和 JAX-WS 以及 APACHE CXF 

    JAX-WS是java 对 xml web service 的API 。JAX-WS提供了一系列的注解来简化 SOAP驱动的

 web service的开发。 Mule通过apache的CXF支持JAX-WS. 要BrewService为可用通 SOAP方式

 访问，你需要注解实现类 BrewServiceImpl ，就像你使用JAX-RS时一样。你也需要抽出并注解

 一个接口--BrewService。

  APACHE CXF  APACHE CXF是一个构建web service的开源框架。mule多数对SOAP的支持通过使用

          APACHE CXF实现。 CXF是一个非常强大 ，而且比较复杂，对它的讨论超出的本书的范围。

         读者去http://cxf.apache.org/docs/index.html 查看用户手册。

 CXF使用接口生成 web service 的 WSDL。这是客户端连接的契约。

列表 3.10 和 3.11 展示了如何注解 BrewService和 BrewServiceImpl以生成WSDL以及

如何注解实现类。

Listing 3.10 The JAX-WS annotated BrewService interface 

package com.prancingdonkey.service;
@WebService
public interface BrewService {
   List<Brew> getBrews();
}  
           

Listing 3.11 The JAX-WS annotated BrewService implementation 

package com.prancingdonkey.service;
@WebService(endpointInterface ="com.prancingdonkey.service.BrewService",
                  serviceName = "BrewService")
public class BrewServiceImpl implements BrewService {
    List<Brew> getBrews() {
        return Brew.findAll();
    }
}
           

现在把 SOAP串联在mule中 。和Jersey类似 见下列表以及 图 3.9

Listing 3.12 Expose the brew listing over SOAP using CXF 

<flow name="brewSoapService">
<!--注释1   HTTP endpoint接受SOAP请求-->
<http:inbound-endpoint address="http://localhost:8090/soap"
exchange-pattern="request-response"/>

<cxf:simple-service
<!-- 要暴露的服务接口-->
serviceClass="com.prancingdonkey.service.BrewService"/>
<!--实现类-->
<component class="com.prancingdonkey.service.BrewServiceImpl"/>
</flow>
      

web service的地址是http://api.prancingdonkey.com/soap?wsdl

来使用 SOAPUI客户端，指向这个WSDL并生成请求，看到返回才响应如图 3.10 。

3.10 图左边部分显示了 WSDL的操作，本例中只有一个 getBrews。

点击左边的 getBrews 将生成一个简单的请求如图中间部分。

点击绿色的运行按钮，将发送请求到mule，并会在图右侧部分显示响应。

Figure 3.10   Using SOAP UI to invoke the SOAP service

JAXB  你可以使用 JAXB控制CXF和 Jersey的序列化。更多细节参看 http://jaxb.java.net/tutorial/

CXF也可以用来调用web service 。假设Arnor Accounting提供了一个WSDL 描述他们的 SAOP API .

你可以把列表3.1 的流修改为通过这种机制提交支持报表，如下所示：

Listing 3.13 Submit expense reports using SOAP

<flow name="brewListingOverSOAP">
<file:inbound-endpoint path="/data/expenses/in"
pollingFrequency="60000"/>
<cxf:jaxws-client
<!--注释1  CXF生成的客户端类-->
clientClass="com.arnor.api.AccountingService"
<!--注释2  WSDL端口-->
wsdlPort="SoapPort"
<!--注释3  WSDL位置-->
wsdlLocation="classpath:/wsdl/services.wsdl"
<!--注释4  要调用的操作-->
operation="submitExpenses"/>
</flow>      

 采用CXF的wsdl2java生成客户端类后 ，就可以使用mule调用web service了。

 生成的类配置在注释1处。WSDL的端口和位置配置定义在注释2和注释3处。

 调用的操作在注释4处。

 在本节机学习了如何使用HTTP 调换数据。你看mule的HTTP如何传输可以发送和接受消息，

 以及如何进行异步HTTP请求的处理。你看到了依据mule对JAX-RS 和JAX-WS的支持来暴露使用

 REST和SOAP方式访问的服务。

 简单服务模式   你将在第6章看到简单服务方式可以用来把POJO暴露为REST和SOAP访问的服务，

               这仅仅只需要一行配置。如果你的服务很简单 ，或者你没必要使用JAX-RS 及 JAX-WS标准的话这

              种方式可能更合理。