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:
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.
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-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.
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.
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:
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.