Overview
This is a significant upgrade to Dispatch, adding preliminary support for the NIO HttpAsyncClient as a backend. Dispatch's internals have been refactored to provide the needed flexibility, with some breaking changes. And lastly, Scala 2.7.x is not supported in Dispatch 0.8.x.
For these reasons, the Dispatch 0.7 line will continue as long as needed by client applications. Bug fixes will be released in new 0.7 versions (by request) and 0.7 binaries will be back-published for use with new versions of Scala.
Core Module and NIO Support
In previous versions of Dispatch the lowest level HTTP module was dispatch-http, which depends on HttpComponents's HttpClient library. Since 0.8.0 adds support for the HttpComponents's nio-based HttpAsyncClient, there is a new core module that further abstracts request definitions and handlers/callbacks from request executors.
- dispatch-core - Requests, handlers, callbacks, and abstract executors
- dispatch-http - Traditional Dispatch client interface, depends on core, uses threads for futures and callbacks
- dispatch-nio - New Dispatch client interface, depends on core, uses NIO for futures and callbacks
The dispatch-nio module is relatively unproven compared to dispatch-http, and its underlying HttpAsyncClient library is a prerelease version. Just, fyi.
API Refactorings
The module reorganization motivated a number of refactorings that would have been a good idea any, but some of them will require changes to client applications.
import Request._
If you used to import Http._ you will probably need to change that to Request._.
This will enable all the useful implicit conversions that used to be in dispatch.Http (which is not in the core module). Because these are in the Request module, most implicit conversions will happen even if you don't import them. But for migrations the simplest thing is to change your import; there are no implicits on Http so there is no reason to leave that import in code.
Parameters are Traversable[(String, String)]
Sorry, this one's going to sting a little. Parameters used to be Map[String, Any]. Traversable is more general, no problem there, but anywhere that your code is passing in a parameter value (e.g. to << or <<?) whose is type Any you'll get a compiler error. If the value not actually a String just call toString on it, like Dispatch was doing before.
The convenience of the old Any conversion was not worth the bugs it invited into compiled code. Specifically, discovering via a trace that you are POSTing something awful like
[Ljava.lang.Object;@3c9076d
to a remote service.
Simpler Request class, corralled verbs
Request is now a pretty chill class. All of the request verbs, like << and <<?, are implemented in a separate class, as are handler and callback verbs. This puts these on a level playing field with extensions in other modules; the only difference is that Request can not implicitly convert to objects it doesn't know about, so you will still need to import e.g. OAuth._ to use its <@ verb.
Speaking of OAuth, its <<?(token: Token) method has been renamed with_token, and similarly multipart-post methods in Mime are all now <<* instead of <<. (It turns out that implicitly overloaded methods are great for finding compiler bugs and bad for API continuity.)
Callbacks
A new Callback interface serves as an alternative to handlers, for applications that process responses as they arrive, line by line or by some custom division. Callbacks abstract across the implementation differences between the underlying InputStream and NIO interfaces and simply access to streaming APIs.
The dispatch-meetup and dispatch-twitter modules both use callbacks to handle streaming API responses. The example application Twine has been adapted to demonstrate callbacks with Twitter's user stream.
Google App Engine
Dispatch can be used under GAE with the new http-gae module and dispatch.gae.Http executor, contributed by max4f.
Databinder Dispatch is a library for HTTP interaction, from asynchronous GETs to multi-part OAuth-enticated POSTs.
