add Filters section

Author: decebals

_posts/2015-05-05-routes.md

@@ -56,14 +56,3 @@ If you want to be more riguros you can use something like:
 ```java
 GET("/contact/{id: [0-9]+}", (routeContext) -> { ... });
 ```
-
-**Note:** If you want to add a filter for all routes you **MUST** use `/.*` and **NOT** `/*`:
-
-```java
-// audit filter
-ALL("/.*", (routeContext) -> {
-	log.info("Request for {} '{}'", routeContext.getRequestMethod(), routeContext.getRequestUri());
-	routeContext.next();
-});
-```
-

_posts/2015-06-18-filters.md

@@ -0,0 +1,67 @@
+---
+layout: page
+title: "Filters"
+category: doc
+date: 2015-06-18 17:31:52
+order: 27
+---
+
+A filter can be any regular `Route` that doesn't commit the response.
+
+For example we can create an `AuditFilter` (a __before filter__) with this code:
+
+```java
+// audit filter
+ALL("/.*", (routeContext) -> {
+	log.info("Request for {} '{}'", routeContext.getRequestMethod(), routeContext.getRequestUri());
+	routeContext.next();
+});
+```
+
+In above snippet we added a before filter on all requests, this filter logs the request method and the request URI.  
+At the end of the filter we __MUST__ call `routeContext.next()` to jump to the next route/filter from the chain.
+
+**Note:** If you want to add a filter for all routes you **MUST** use `/.*` and **NOT** `/*`:
+
+Another __before filter__ can be an `AuthenticationFilter`:
+
+```java
+// authentication filter
+GET("/contact.*", (routeContext) {
+	if (routeContext.getSession("username") == null) {
+		routeContext.redirect("/login");
+	} else {
+		routeContext.next();
+	}
+});
+```
+
+In above snippet we protected all contact pages. If the current session doesn't contain an attribute `username` 
+then our filter redirects the request to the `login` page.
+
+Now we want to propose you a most complicated scenario where we are getting a Database instance to be shared 
+throughout a request-response cycle:
+
+```java
+// before filter that create a database instance
+ALL("/.*", (routeContext) -> {
+    routeContext.setLocal("database", getDatabase());
+    routeContext.next();
+}); 
+
+// insert data in database
+POST("/{id}", (routeContext) -> {
+    Database database = routeContext.getLocal("database");
+    database.insert(something); // this line can throws an error
+});
+
+// after filter that release the database instance
+ALL("/.*", (routeContext) -> {
+    Database database = routeContextremoveLocal("database");
+    database.release();
+}).runAsFinally(); 
+```
+
+Please notice that we must mark the last filter with __runAsFinally__ that are guaranteed to execute 
+at the end of the `Request-Response` cycle despite exceptions within the chain.
+