Request & Response
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
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.
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.
and application path
are both prefixes of
the request path.
Context path and applications may both be the root path
gives you the path of the request relative to the application path.
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:
these parameters are recognized:
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
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
Civilian treats these as query parameters as well - if you would use "GET" as form method they also would end up as part of
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.
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 or the
The content of the request is described by its content type
For low-level handling it can be read as byte
Alternatively you can call Request.readContent(Class, Type?)
to easily parse complex objects. This method is based on Civilians content serialization
which allows easy conversion from data-formats such as JSON or XML to application objects.
to security related information of the request is available via the sub-object
. 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
Prior to the servlet 3.0 spec multipart requests (i.e. requests with content-type
) required own processing.
The introduction of
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
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
IP Interface information
Information about the remote
IP interfaces is made available via sub-objects of the request.
object contains a status, headers and content.
allows to set the HTTP response status. Response.Status
for most common HTTP status codes.
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
For low-level handling it can be written via a byte
Alternatively Response provides a
to easily write complex objects. Abbreviations for popular data formats like JSON
These methods are based on Civilians content serialization
which allows easy conversion from application objects to data-formats like JSON or XML.
The writer returned by Response.getContentWriter()
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)
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(*)
to send the client a redirect to another URL.
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
actively commits the request.
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
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
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
And of course you can always add an own implementation or replace the default ones.