Bindings and Servers

The core module unfiltered-library does not depend on or reference any particular server backend. It defines internal abstractions for requests and responses, with higher level abstractions on top.

An application or library that depends only on the core library could be used with any backend that Unfiltered supports, but in most cases it will depend on a binding module.

Binding Modules

These bind Unfiltered’s generic request and response interfaces to a given implementation, as well as intent types and plan traits.

Servlet Filters (unfiltered-filter)

The Java Servlet API enables you to write applications that run on servlet containers, anything from Tomcat to Google App Engine. Its plan trait is a servlet filter.

Asynchronous Servlet Filters (unfiltered-filter-async)

Asynchronous Servlet Filters are using jetty-continuation under the hood which should provide a general purpose API that will work asynchronously on any servlet-3.0 container, as well as on Jetty 6, 7 or 8 (Continuations will also work in blocking mode with any servlet 2.5 container.)

copysourceimport unfiltered.request.{Path => UFPath, _}
import unfiltered.response._

object AsyncPlan extends unfiltered.filter.async.Plan  {
  def intent = {
    case GET(UFPath("/pass")) => Pass
    case req@GET(UFPath("/async")) =>
      //"respond" is usually called from an asynchronous callback handler
      req.respond(ResponseString("test") ~> Ok)
  }
}
//then you can register this plan with jetty as usual
unfiltered.jetty.Server.http(8080).plan(AsyncPlan).run()

Netty Channel Handlers (unfiltered-netty)

Netty defines channels for network I/O and implements them using Java’s Native I/O (NIO) interface. Its plan traits are upstream channel handlers, and the module defines intents and plans in separate cycle and async subpackages, the former for traditional request-response cycles and the latter for open-ended interaction.

Server Modules

Server modules define runnable servers to execute your plans. They are entirely optional. Applications can instead use Unfiltered’s binding modules with external containers, or they can interface directly with server libraries.

unfiltered-jetty

Includes builders for Jetty servers that implement the HTTP and HTTPS protocols. With this server it is particularly easy to serve a web browser interface for a local process. Unfiltered even gives you a shortcut to open a browser window, if the user is on a 1.6+ JVM that supports it.

copysourceimport unfiltered.response._
val hello = unfiltered.filter.Planify {
  case _ => ResponseString("hello world")
}
unfiltered.jetty.Server.anylocal.plan(hello).run { s =>
  unfiltered.util.Browser.open(
    s.portBindings.head.url
  )
}

unfiltered-netty-server

Bootstraps and binds a server for your channel handlers.

copysourceimport unfiltered.response._
val hello = unfiltered.netty.cycle.Planify {
  case _ => ResponseString("hello world")
}
unfiltered.netty.Server.http(8080).plan(hello).run()