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.

Introduction

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

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

Path

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.

Method

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

Parameters

Civilian gives you access to normal paramters, matrix-, and path parameters in a request. Given a request to the URL:
https://example.org/apps/crm/customers/1345;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 the id of database entity. 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.

Headers

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

Content

The content of the request is described by its content type, encoding, 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. request 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 sub-objects of the request.

Response

The Response contains a status, headers and content.

Status

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

Headers

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

Content

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.

TemplateWriter

The writer returned by Response.getContentWriter() is an instance of class TemplateWriter.
Besides being a java.io.PrintWriter, TemplateWriter provides additional functionality:
  • TemplateWriter allows to produces pretty indentend output (think HTML).
  • A TemplateWriter can be {@link #addContext(Object) associated} with multiple context objects.
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.

sendError

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().

sendRedirect

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 a 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 format such Java models into response content or parse them from request content. The following methods enable such one-liners:

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.