Play 2.0 用户指南 － 异步HTTP编程 －－针对Scala开发者

处理异步结果

    为何须要异步结果？

   
    目前为止，咱们可以直接向客户端发送响应。

    然而状况不老是这样：结果可能依赖于一个繁重的计算和一个长时间的web service调用。

    缘于 Play 2.0 的工做方式，action代码必须尽量的快（如，非阻塞）。那，未能生成最终结果前，应该返回什么呢？答案是返回一个 promise(承诺？) of response！
    A Promise [Result] 最终会赎回一个Result类型的值。使用 Promise[Result] 替换正常的Result，咱们能够无阻塞的快速生成结果。该响应是一个返回Result的承诺（Promise）。

    等待响应的时候，web客户端將会被阻塞，但服务器不会被阻塞，空闲资源能够移作它用。
   

    怎样建立Promise[Result]

   

    为了建立Promise[Result]，咱们首先须要另外一个promise：该promise將为咱们计算实际的结果值。

val promiseOfPIValue: Promise[Double] = computePIAsynchronously()
val promiseOfResult: Promise[Result] = promiseOfPIValue.map { pi =>
  Ok("PI value computed: " + pi)    
}

    全部的 Play 2.0 的异步调用API会返回 Promise。无论你是使用 play.api.libs.WS API调用外部web服务，仍是借助Akka分配异步任务，亦或使用 play.api.libs.Akka 在actors间通讯。

    一个简单的异步执行代码块并获取一个 Promise 对象的方法是使用 play.api.libs.concurrent.Akka助手：

val promiseOfInt: Promise[Int] = Akka.future {
  intensiveComputation()
}

    注意：该intensiveComputation计算单元將运行在另外一个线程中，或者运行位于Akka集群的远程服务器中。
   

    异步结果

    迄今为止，咱们都使用 SimpleResult 来发送一个异步响应，咱们须要一个 AsyncResult 类来封装实际的 SimpleReslut：

def index = Action {
  val promiseOfInt = Akka.future { intensiveComputation() }
  Async {
    promiseOfInt.map(i => Ok("Got result: " + i))
  }
}

    注意：Async { ... }是一个助手方法，用于从Promise[Result]中构建AsyncResult。
   

    处理超时

    超时处理，经常用于避免浏览器因某些错误而遭长时间阻塞。这种情形很容易处理：

def index = Action {
  val promiseOfInt = Akka.future { intensiveComputation() }
  Async {
    promiseOfInt.orTimeout("Oops", 1000).map { eitherIntorTimeout =>
      eitherIorTimeout.fold(
        timeout => InternalServerError(timeout),
        i => Ok("Got result: " + i)    
      )    
    }  
  }
}

    HTTP流响应

    标准响应和Content-Length

    从HTTP 1.1开始，为保证单个打开的链接能服务于多个HTTP请求和响应，服务器必须针对响应发送适当的Content-Length请求头。
    默认状况，当发回一个响应结果时，你并无指定Content-Length头信息，例如：

def index = Action {
  Ok("Hello World")
}

    然而，由于该内容是已知的，Play可以自行计算该长度并产生适当的响应头信息。
    注意：基于文本的内容不像表面看上去哪么简单， Content-Length 头须要根据字符编码计算，并把字符转换成字节。

    实际上，咱们前面已经看到，response body 被指定使用一个play.api.libs.iteratee.Enumerator：

def index = Action {
  SimpleResult(
    header = ResponseHeader(200),
    body = Enumerator("Hello World")
  )
}

    意味着，为了正确计算Content-Length，Play必须消耗整个enumerator，并把内容所有加到内存中。

    大数据发送

    若是对于简单的Enumerators，把内容所有加载到内存不是问题，那么大量数据怎么办呢？比方说咱们要给客户端返回一个大的文件。
    咱们首先看看如何建立Enumerator [Array[Byte]]列举该内容：

val file = new java.io.File("/tmp/fileToServe.pdf")
val fileContent: Enumerator[Array[Byte]] = Enumerator.fromFile(file)

    它看起来正确吗？咱们仅使用enumerator指定 response body：

def index = Action {

  val file = new java.io.File("/tmp/fileToServe.pdf")
  val fileContent: Enumerator[Array[Byte]] = Enumerator.fromFile(file)    
    
  SimpleResult(
    header = ResponseHeader(200),
    body = fileContent
  )
}

    实际上这是有问题的。咱们没有指定Content-Length长度，Play必须自行计算。惟一的方法是消耗整个enumerator，并將内容所有加载到内存中，最后方能计算响应的长度。
    对于大文件，这是有问题的。咱们不但愿内容都加载到内存中。为了不这种状况，咱们须要手动指定Content-Length的长度。

def index = Action {

  val file = new java.io.File("/tmp/fileToServe.pdf")
  val fileContent: Enumerator[Array[Byte]] = Enumerator.fromFile(file)    
    
  SimpleResult(
    header = ResponseHeader(200, Map(CONTENT_LENGTH -> file.length.toString)),
    body = fileContent
  )
}

    经过这种方式，Play將以懒加载的方式使用enumerator，一块一块的將可用数据拷贝到HTTP响应中。

    处理文件

    Play为处理本地文件提供了一个便利方法：

def index = Action {
  Ok.sendFile(new java.io.File("/tmp/fileToServe.pdf"))
}

    该方法也会根据文件名肯定Content-Type内容，并添加Content-Disposition元素来指定浏览器的处理方式。默认是经过添加Content-Disposition : attachment ; filename =fileToServe.pdf 响应头信息，指定浏览器下载该文件。
    你也能够自定义文件名：

def index = Action {
  Ok.sendFile(
    content = new java.io.File("/tmp/fileToServe.pdf"),
    fileName = _ => "termsOfService.pdf"
  )
}

    你也能经过不指定文件名，避免浏览器下载该文件，而仅让浏览器显示该文件内容，如text，HTML或图片等这些浏览器原生支持的文件类型。

    分块响应

    目前为止，发送响应前，咱们就计算好响应体长度，一切都工做得很好。可是，须要动态计算的长度怎么办？长度没法获取的状况下怎么办？
    这种类型的响应，咱们必须使用Chunked transfer encoding。

    Chunked transfer encoding是HTTP 1.1提供的一种数据传输机制，服务器將内容分红多块传送。它使用Transfer-Encoding HTTP响应头替代Content-Length， 以跳过长度限制。因为Content-Length再也不使用，数据在发送给客户端（一般是web浏览器）前，不须要提早计算长度了。在得知内容的总长度前，服务器能够动态的生成并传输内容。

    每一个块大小在发送前被正确的指定，以便浏览器通知什么时候该块数据接收完成。数据传输將在最后一个长度为零的块处中断。

    这种机制的优势是咱们能够实时的传送数据。只要块数据可用，咱们就发送它。缺陷是，既然内容长度没法获知，浏览器没法显示正确的下载进度。
    比方咱们有某个服务，利用InputStream流动态的操纵数据。首先咱们为该流建立一个Enumerator：

val data = getDataStream
val dataContent: Enumerator[Array[Byte]] = Enumerator.fromStream(data)

    咱们如今能够经过ChunkedResult处理这些数据：

def index = Action {

  val data = getDataStream
  val dataContent: Enumerator[Array[Byte]] = Enumerator.fromStream(data)
  
  ChunkedResult(
    header = ResponseHeader(200),
    chunks = dataContent
  )
}

    一如既往，咱们提供了便利方法完成一样工做：

def index = Action {

  val data = getDataStream
  val dataContent: Enumerator[Array[Byte]] = Enumerator.fromStream(data)
  
  Ok.stream(dataContent)
}

    固然咱们也能够用任何的Enumerator指定块数据：

def index = Action {
  Ok.stream(
    Enumerator("kiki", "foo", "bar").andThen(Enumerator.eof)
  )
}

    Tip：Enumerator.callbackEnumerator and Enumerator.pushEnumerator convenient ways to create reactive non-blocking enumerators in an imperative style.

    咱们能够查看服务器发回的响应：

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked

4
kiki
3
foo
3
bar
0

    咱们接收到了三块数据，最后在接到到空块后关闭该响应。

    Comet sockets

   
    使用 分块 response 建立Comet Socket

    Chunked responses的其中一个用处是建立Comet sockets。一个Comet响应不过是一个包含<script>元素的 text/html 响应。每一个响应块写入的<script>标签都被浏览器 当即执行。经过这种方式，咱们能够实时的为浏览器发送事件：每一段消息，咱们均可以包装入<script>标签中，声明一个JavaScript回调函数，并写入响应块中。

    让咱们开始写第一个简陋的协议：一个enumerator生成几个<script>标签，调用浏览器的 console.log 方法：

def comet = Action {
  val events = Enumerator(
     """<script>console.log('kiki')</script>""",
     """<script>console.log('foo')</script>""",
     """<script>console.log('bar')</script>"""
  )
  Ok.stream(events >>> Enumerator.eof).as(HTML)
}

    若是你从浏览器中访问该action，你將会在浏览器控制台中看到三个日志记录。
    提示：编写 events >>> Enumerator.eof 只是 events.andThen(Enumerator.eof)的另外一种方式。

    咱们可使用play.api.libs.iteratee.Enumeratee更好的改写该例子。that is just an adapter to transform an Enumerator [A] into another Enumerator
    [B] .让咱们使用它来封装一个标准的消息响应：

import play.api.templates.Html

// Transform a String message into an Html script tag
val toCometMessage = Enumeratee.map[String] { data => 
    Html("""<script>console.log('""" + data + """')</script>""")
}

def comet = Action {
  val events = Enumerator("kiki", "foo", "bar")
  Ok.stream(events >>> Enumerator.eof &> toCometMessage)
}

提示：编写 events >>> Enumerator.eof &> toCometMessage 只是  events.andThen(Enumerator.eof).through(toCometMessage) 的另外一种形式。

    使用 play.api.libs.Comet 助手

    咱们提供了一个Comet助手类来处理这类Comet chunked streams，实现几乎和咱们这里编写的同样。
    注意：实际上他为你作了更多事，考虑到浏览器的兼容性，他会先推送一些空数据来判断浏览器的兼容性，他支持String和JSON两种类型。它也能够被扩展以支持更多消息类型。

    咱们使用它来重写前面的例子：

def comet = Action {
  val events = Enumerator("kiki", "foo", "bar")
  Ok.stream(events &> Comet(callback = "console.log"))
}

    Tip：Enumerator.callbackEnumerator and Enumerator.pushEnumerator convenient ways to create reactive non-blocking enumerators in an imperative style.

    无限使用iframe技术（？？？）

    标准的Comet Socket技术是给一个iframe无限的推送并指定调用父窗口的回调函数数据。

def comet = Action {
  val events = Enumerator("kiki", "foo", "bar")
  Ok.stream(events &> Comet(callback = "parent.cometMessage"))
}

    HTML看起来会像这样：

<script type="text/javascript">
  var cometMessage = function(event) {
    console.log('Received event: ' + event)
  }
</script>

<iframe src="/comet"></iframe>

   

    WebSockets

    使用WebSockets取代Comet sockets

    Comet sockets是一种向浏览器发送实时数据的hack技术。他仅仅提供了服务器和客户端交流的一种形式。给服务器端发送数据，客户端只能发送Ajax请求。

    Note: It is also possible to achieve the same kind of live communication the other way around by
    using an infinite HTTP request handled by a custom BodyParser that receives chunks of input
    data, but that is far more complicated.

    现代的浏览器借助WebSockets原生支持双向实时通讯。
   
    WebSockets是一种经过单一的TCP socket链接提供双向的，全双工链接通道的web技术。WebSockets API被W3C标准化，WebSockets协议也被IEF以RFC 6455形式标准化。
   
    WebSockets被设计于在浏览器和服务器中实现，但它其实可用于任何的服务器端或客户端应用。因为管理员经常拒绝本地环境之外非80端口的普通TCP链接，WebSockets必须找到一种方式规避该限制，还需提供一些相似的功能让单一的TCP链接服务于多个WebSockets请求。

    WebSockets也为那些须要实时，双向通讯的应用提供帮助。WebSockets实现之前，这种双向通讯只能使用Comet通道实现。然而Comet实现的设施并不可靠，缘于TCP的握手机制和HTTP协议开销，对于短消息传输是很是低效的。
    WebSocket协议旨在解决这些问题，而不影响现有的web安全的假设妥协。
    http://en.wikipedia.org/wiki/WebSocket

    处理WebSockets

    如今为止，咱们使用action实例处理标准HTTP请求，发送标准HTTP响应。WebSockets是如些的独特而不能使用常规的Action处理。
    为了处理WebSockets请求，需使用WebSocket替代Action：

def index = WebSocket.using[String] { request => 
  
  // Log events to the console
  val in = Iteratee.foreach[String](println).mapDone { _ =>
    println("Disconnected")
  }
  
  // Send a single 'Hello!' message
  val out = Enumerator("Hello!")
  
  (in, out)
}

    WebSocket具有检索请求头（从HTTP请求头启动一个WebSocket链接）能力，容许你取回标准头消息和session数据。然而它不具有访问 request body 和HTTP response body 的能力。

    当经过这种方式创建WebSocket的时候，咱们必须返回一对in和out频道。
        in频道是一个Iteratee[A,Unit]（A是消息类型，咱们这里使用String），它会被每个消息通知，当客户端关闭socket的时，会收到EOF。
        out频道是一个Enumerator[A]，它將产生待发送给客户端的消息。能够经过服务器端发送一个EOF来关闭它。

    在该例子中，咱们简单的將消息叠代发送给控制台。为了发送消息，咱们建立了个虚拟的简单enumerator来发送 Hello! 消息。
    提示：你能够访问http://websocket.org/echo.html测试WebSockets。只需把地址设为ws://localhost :9000 .

    让咱们编写另一个例子，丢弃输入值，发送Hello!后关闭该socket。

def index = WebSocket.using[String] { request => 
  
  // Just consume and ignore the input
  val in = Iteratee.consume[String]()
  
  // Send a single 'Hello!' message and close
  val out = Enumerator("Hello!") >>> Enumerator.eof
  
  (in, out)
}