使用CXF附件的注意事项

英文链接http://ext2xhb.wordpress.com/2011/06/08/using-cxf-attachment-safely/

Apache CXF引擎处理附件的机制十分的优化，而且支持大附件的使用模式。不过如果使用时不太注意，可能会引发一些潜在的问题。譬如：临时文件没有删除，http连接没有释放。

最近通过查看了CXF的源代码，以及和CXF社区交流以后。总结了一下CXF附件的使用注意事项，这些事项可以通过以下几个问题分别说明。
1）如何避免残留临时文件/如何避免http连接的没有正确关闭。
2）附件的内容如何重复使用
3）如何处理大附件。

在分析这些问题之前，我们需要了解一下关于CXF处理附件的一些基本知识。
1)CXF的附件具有两个底层的状态："cached" and "delegate";
"cached"意味着附件的内容已经从网络上读取完毕，并且缓冲到内存或者临时文件中。如果附件的大小超过了一个“阈值”，那么CXF使用临时文件保存附件内容，否则使用内存保存。因此在客户端程序中调用DataSource.getInputStream()会返回一个指向内存或者临时文件的InputStream。

"delegate" 意味着附件的内容依然在网络上保持着未读取的状态。此时数据源的输入流最终会关联一个Http-Connection的输入流。

2)只有最后一个附件的状态时“delegate”，其他附件的状态都是“cached”
如果Webservice只有一个附件，那么这个附件的状态是“delegate”。如果有多个，那么只有最后一个是delegate。

到2.4.0的Release版本为止，由于CXF与SUN的Activation 库不兼容，从而导致附件的状态不正确（都是“delegate"）。因此我们需要将CXF3505https://issues.apache.org/jira/browse/CXF-3505的patch自行合并到CXF库中。在未来版本，CXF会将此问题的Patch合并到发布版本中。

3)CXF 重载了"cached" 附件的input stream close方法。关闭附件是关联的临时文件会删除。


下面我们看一下如何解决前面提出的问题。

1）如何避免残留临时文件/如何避免http连接的没有正确关闭。
前面提到过"cached" 附件可能会关联一个临时文件，而"delegate"附件则会关联一个网络输入流。所以如果我们不正确的释放附件，那么可能会导致残留临时文件或者没有管理底层的http连接。
CXF要求用户必须自行维护附件的释放过程。也就是说，即使用户不关心附件内容的时候，他也必须从附件的获得InputStream(DataSource.getInputStream())，然后显示的关闭它(inputstream.close)
注意：CXF3504 https://issues.apache.org/jira/browse/CXF-3504是一个与附件关闭有关的问题。如果我们没有将此问题的补丁合并到cxf，那么在关闭InputStream之前，最好将其中的内容完全读取完毕。
void safeClose(InputStream is) throws IOException{
try{
while(is.read() != -1)
;
}catch(Exception e){
//ignore
}
is.close();
}
CXF3504的问题实际上只影响"delegate"状态的附件，也就是说我们实际上只需要对“delegate”状态的附件的关闭做上述处理。如果我们关心效率并且不介意使用CXF内部API，那么可以参考后面的代码实例，来判断附件是否是“delegate”状态。

1.1) 服务端附件的清理机制
当编写web服务的时候，我们会希望当应答返回完毕后， 请求的附件会被自动清理掉。此时我们可以自己编写一个Interceptor来做自动清理的工作。

注意：这种做法只适用于InOut MEP的webservice方法。

首先我们需要为此Interceptor指定一个合适的Phase。由于请求的附件可能被用在应答中，因此我们指定的Phase必须是在应答发送完毕之后。 因此可以使用PREPARE_SEND_ENDING

public AttachmentCleanInterceptor() {
  super(Phase.PREPARE_SEND_ENDING);
}

接着我们需要使用CXF的底层API来访问附件的输入流并关闭它，从而释放附件。这里判断了CXF附件是否为delegate状态，对于delegate状态的附件会在关闭输入流之前将其中的内容完全读完（原因是我们前面提到的CXF3504问题）。

private void cleanRequestAttachment(Exchange exchange) {
  Collection<Attachment> inAttachments = exchange.getInMessage().getAttachments();
  if(inAttachments != null){
    for(Attachment attachment : inAttachments){
      cleanRequestAttachment(attachment);
    }
  }
}

protected void cleanRequestAttachment(Attachment attachment){
  DataSource ds = attachment.getDataHandler().getDataSource();
  if(ds instanceof LazyDataSource){
    ds = ((LazyDataSource)ds).getDataSource();
  }
  if(ds instanceof AttachmentDataSource){
    InputStream is = ds.getInputStream();
    //input stream maybe still delegate to network, so we need to consume it all then close it
    if(!ds.isCached()){
      while(is.read() >= 0){
      }
    }
    //close will delete resource(etc: temporary file) holded by the input stream;
    is.close();
  }
}

接着我们需要将interceptor配置在webservice的out以及outFault interceptor中: <jaxws:outInterceptors>
<refer bean="attachmentClean"/>
</jaxws:outInterceptors>
<jaxws:outFaultInterceptors>
<refer bean="attachmentClean"/>
</jaxws:outFaultInterceptors>

1.2) 客户端的附件清理机制
在客户端，“清理附件”的问题会更加严重。如果忘记关闭附件，会导致http连接无法关闭。这是因为“delegate”状态的附件关联了http response的输入流。因此如果用户不关闭，那么cxf就没有机会来关闭http连接。
void safeClose(DataSource ds, InputStream is){
  if(ds instanceof AttachmentDataSource){
    if(!ds.isCached()){
      while(is.read() >= 0){
      }
    }
  }
  //close will delete resource(etc: temporary file/) holded by the input stream;
  is.close();
}



2）附件的内容如何重复使用
我是在一个代理服务中首次发现这个问题的。这个代理服务会将请求的附件转发给多个web service。结果有时候，代理程序只能将附件内容成功的发送给第一个webservice，而发送给其他webservice的内容为空。
原因在于：1)"delegate"状态的附件关联底层输入流，因此只能读一次。2)"cached"状态的附件可能关联临时文件，读完关闭以后临时文件将被删除，并且附件的内容被重置为一个空的内容。所以下次读的时候就会为空。

因此为了能够多次读取附件内容，需要我们预先将附件的输入流备份一下。但是这种做法效率不高，尤其是附件内容过大时。而CXF提供了特殊的API，可以将附件的内容“hold”住。“hold”的意思是：附件的内容将被保留，用户可以安全的多次读取附件内容。
需要注意的是，如果我们将附件“hold”住，附件关联的临时文件就无法被删除。当需要删除时，我们需要预先将其"release”。然后在使用关闭流的方式删除附件。

下面的程序演示了如何"hold"和"release"附件：

//locking will avoid to copy data source for reuse;
void lock(DataSource ds) throws IOException {
  AttachmentDataSource ads = getAttachmentDataSource(ds);
  if (ads != null) {
   // tell attachment to hold the temporary file;
   ads.hold();
  }
}

void release(DataSource ds) throws IOException {
  AttachmentDataSource ads = getAttachmentDataSource(ds);
  if (ads != null) {
   // tell attachment to hold the temporary file;
   ads.release();
  }
}
// get underlying attachment data source
protected AttachmentDataSource getAttachmentDataSource(DataSource ds) {
  if (ds instanceof LazyDataSource) {
   ds = ((LazyDataSource) ds).getDataSource();
  }
  if (ds instanceof AttachmentDataSource) {
   return (AttachmentDataSource) ds;
  }
  return null;
}

3）如何处理大附件。

3.1)使用附件保存大批业务数据的情况
当使用webservice的时候，soap xml中包含的业务数据的最大size最好是可以预期的，并控制在一个合理的范围内。如果业务数据的大小不可预计，当过大时会导致webservice的性能很差，严重的还会导致内存溢出。
实际上很难说webservice这种技术是否适合这种场景。不过如果一定需要使用webservice的时候，那么最好使用附件来保存此类业务数据。

下面我们看一个处理此类附件的简单示例：

void largeBusinessDataUpload(..){

InputStream is = attachmentDataSource.getInputStream();

Record businessRecord;

while((businessRecord = parseRecord(is)) != null){

//process a businessRecord . etc: saving it to a database;

}

is.close();

}

上面这个简单的程序存在一个性能瓶颈——服务端的业务数据处理速度比网络传输速度慢的时候。服务端会导致客户端在发送附件的过程中阻塞。此时客户端无法进行其他处理降低了客户端的执行效率，同时网络传输故障的可能性也会增加。

要解决这个问题，我们需要首先将附件的内容备份到下来（比如一个临时文件中），然后在备份内容中读取数据并处理。
不过当使用CXF的时候，我们实际上可以通过强迫附件进入“cache”状态来解决这个问题。
AttachmentDataSource.cache()可以达到此目的。

典型的在下面的场景下，进行上述处理会提高webservice性能
a)one-way模式下，客户端发送大附件到服务端。
b）客户端接收来自服务的大附件。

3.2) 二进制大附件

附件可以用来传输二进制数据——比如图片等。但是当二进制数据过大时，我们需要启用Http的“chuncked”模式来传输附件。
如果不启用，CXF引擎需要复制附件的内容来构成一个完整的MIME 编码的SOAP数据包后才能发送，整个MIME 数据包（包括soap-envelop以及所有附件内容的MIME数据包）。而启用了chunked模式后，CXF可以一边读取附件内容一边发送，无需单独构造一个完整的MIME数据包。

我们必须在客户端启用chunked模式，而服务端会自动在发送应答时确定是否使用chunked模式（几乎所有应用web服务器会在应答数据超过一定大小后，自动启用chunked）。
static private void setChunkThreshold(Object client, int size){
  HTTPClientPolicy httpClientPolicy = getClientPolicy(client);
  httpClientPolicy.setChunkingThreshold(size);
}
private static HTTPClientPolicy getClientPolicy(Object stub) {
  org.apache.cxf.endpoint.Client client = org.apache.cxf.frontend.ClientProxy.getClient(stub);
  HTTPConduit http = (HTTPConduit) client.getConduit();
  if(http.getClient() == null){
    HTTPClientPolicy httpClientPolicy = new HTTPClientPolicy();
    http.setClient(httpClientPolicy);
  }
  return http.getClient();
}