Request & Response

The Request and Response interfaces represent a HTTP request and response. Writing a web application means to evaluate requests and building responses. ContentSerialization allows to easily convert Java models into/from request or response content.


The interfaces Request and Response model a HTTP request and response.
A web application is essentially something which receives HTTP requests and returns HTTP responses.

Request and Response are functionally equivalent to a HttpServletRequest and HttpServletResponse. If Civilian is running in a servlet container, the Request and Response implementations used are simple wrappers around their servlet counterparts.

Civilian also provides request and response implementations for a test environment. Please read the test chapter for further information.

This chapter gives a short overview about these two classes and its most important methods. The following chapters will introduce the resource concept – requests are requests for resources – and how the application can dynamically build responses to resource requests using controllers.


Request gives you access to the path, method, headers, parameters and content of a HTTP request.


Civilian uses the Path class to represent path strings (which guarantees correct syntactical form). The request path is the absolute path from the server root / to the requested resource. Context path and application path are both prefixes of the request path.

Context path and applications may both be the root path /.
Request.getRelativePath() gives you the path of the request relative to the application path.


Request.getMethod() returns the name of the HTTP method.


Civilian gives you access to normal paramters, matrix-, and path parameters in a request. Given a request to the URL:;mode=list?sel=1&sel=2&sel=3
these parameters are recognized:

Parameter request.getParameter("sel") "1"
request.getParameters("sel") { "1", "2", "3" }
Matrix parameter request.getMatrixParam("mode") "list"
request.getMatrixParams("mode") { "list" }
Path parameter request.getPathParam(MyPathParams.CUSTOMERID) Integer(1345)
Path parameters are not defined by the URL syntax, they are just segments of the path interpreted as parameter. In the example the path segment /1345 is interpreted as an id referencing a data object. Definition and workings of path parameters are explained here.

When a HTML form is posted, the browser send form values as request content with content type application/x-www-form-urlencoded. Civilian treats these as query parameters as well - if you would use "GET" as form method they also would end up as part of the URL.

Values of query and matrix parameters are strings. Manual conversion to other types is tedious and error prone. Civilian includes a Type framework to help with parsing and formatting. Based on that simple and type-safe access to parameters is possible.
Within Controllers the runtime can inject request parameter values into Controller method parameters in a type-safe way, to relieve you from manual type conversion.

Path parameters avoid conversion traps since they are designed as typed values using the PathParam class.

Dealing with parameters in the context of HTML forms is also a huge topic. Civilians form library again helps you with parsing and formatting, including handling of locale dependent values.


Access to the HTTP headers of the request is available via the sub-object RequestHeaders.
The request class also provides specialized methods to access the Cookie header, the Accept header or the Accept-Language header.


The content of the request is described by its content type, encoding and length. For low-level handling it can be read as byte or text stream.
Alternatively you can call Request.readContent(Class, Type?) to easily parse complex objects. This method is based on Civilians content serialization framework which allows easy conversion from data-formats such as JSON or XML to application objects.

Security information

Access to security related information of the request is available via the sub-object RequestSecurity. It is aligned along the security capabilities of a servlet container, namely session management, container based authentication and user management.
The request object also provides access to a servlet container inspired Session object.

Multipart requests

Prior to the servlet 3.0 spec multipart requests (i.e. requests with content-type multipart/form-data) required own processing. The introduction of javax.servlet.http.Part helped a little, but required different handling of simple parameters in normal and multipart requests.

Civilian simplifies multipart processing. All parameters in the multipart request are available as query parameters. Additionally for each parameter which represents an uploaded file a Upload object is provided by the request. The Upload sample demonstrates this feature.

Multipart requests need to be explicitly enabled in the Civilian configuration (for instance look at the upload sample) or during application startup.

Async operations

Asynchronous processing of requests was introduced in the servlet 3.0 spec. Civilian covers this functionality with the AsyncContext available via Request.getAsyncContext(). The Chat sample demonstrates this feature.

Async capabilities need to be explicitly enabled in the Civilian configuration (for instance look at the chat sample) or during application startup.

IP Interface information

Information about the remote, server and local IP interfaces is made available via sub-objects of the request.


The Response object contains a status, headers and content.


Response.setStatus(int) allows to set the HTTP response status. Response.Status defines constants for most common HTTP status codes.


Access to the HTTP headers of the response is available via the sub-object ResponseHeaders. A cookie header can be added through addCookie(Cookie).


The content of the response is described by its content type, encoding, length. For low-level handling it can be written via a byte or text stream.
Alternatively Response provides a Response.writeContent(Class, ContentType?) method to easily write complex objects. Abbreviations for popular data formats like JSON or XML exist. These methods are based on Civilians content serialization framework which allows easy conversion from application objects to data-formats like JSON or XML.


The writer returned by Response.getContentWriter() is an instance of class TemplateWriter.
Besides being a, TemplateWriter allows to produces pretty indentend (HTML) output. Being a PrintWriter the TemplateWriter can be passed to any template system like Velocity or Freemaker. But its additional functionality is especially used by Civilians own template system CSP.


Response provides the sendError(int) and sendError(int,String,Throwable) to send an error to the client. This will commit the response.
Also any uncaught exception during request processing will automatically result in sending an error to the client.
The exact error response sent to the client can be tweaked by overriding Application.createErrorResponse().


Response provides several sendRedirect(*) methods to send the client a redirect to another URL.

Response buffer

The response maintains a buffer for the response content. When this buffer is full, writing of the response to the client is started, and the response is set to committed. Upto this point the you can reset the response or its buffer. Response.flushBuffer() actively commits the request.

Content Serialization

Both request and response can have content payloads, described by HTTP content-type, encoding and length headers.

Oftentimes these payloads can be textual representations of Java objects, e.g. in JSON or XML form.
From the application programmers point of view it should be easy to turn such Java models into response content or parse them from request content. The following methods allow such easy conversions:

Behind the scenes these calls are implemented by using Civilians content serialization framework.
Each application possesses a list of ContentSerializers. A ContentSerializer knows how to to parse and format Java objects from/to representations of a certain content type.

Civilian provides a default ContentSerializer for JSON, based on Google GSON.
Just add the GSON libraries to your project and your are ready to go. We recommend using Gson 2.2.4+ which resolved threadlocal issues.

Also it has a ContentSerializer for XML based on JAXB. In order to use it you need to create an instance passing a suitable JAXBContext for your model classes and register it during application startup.

And of course you can always add an own implementation or replace the default ones.