Request & Response
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.
/.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
| 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) |
/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.
Headers
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.
Content
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-typemultipart/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.Response
The Response object 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 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.
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 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:
- Request.readContent(Class)
- Request.readContent(Class, Type)
- Response.writeContent(Object)
- Response.writeContent(Object, ContentType)
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.