使用CXF附件的注意事项

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"）。因此我们需要将CXF3505 https://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(); 
}