Application structure
A Civilian application has the directory layout of a servlet application. Its
package and class structure is aligned with its resource URLS.
This chapter describes how to organize a Civilian application. First we describe
the directory layout of an application, then the Java class structure.
Directory layout
A Civilian deployment consists of the application classes, third-party libraries (e.g.
civilian.jar), configuration files and asset files such as CSS, Javascript, images, etc.
Civilians primary (and right now only) runtime environment is a servlet container, therefore
the directory layout of the application is that of a
servlet application.
Its WEB-INF directory contains a
web.xml file and a configuration file civilian.ini. Both are described in the
configuration chapter.
$web |
(static assets) |
$web/WEB-INF |
configuration directory |
$web/WEB-INF/web.xml |
servlet configuration |
$web/WEB-INF/civilian.ini |
Civilian config file |
$web/WEB-INF/classes |
classes, Java resources |
$web/WEB-INF/lib |
libraries |
To deploy to a servlet container your build process must be able to produce a WAR file with this directory layout.
During development we usually embed that structure into a IDE project.
$project |
project root dir |
$project/bin |
compiled application classes |
$project/src |
application sources |
$project/lib |
third-party libraries |
$project/web |
corresponds to $web in the previous table |
$project/web/WEB-INF |
same as the WEB-INF directory in the previous table |
The
development chapter describes techniques
how to run the application directly from such a project structure, for example using
embedded web servers or Tomcats VirtualWebappLoader, without building a WAR and
deploying to a server.
Package structure
Each Civilian application has an application class derived from
Application.
You can freely choose its package and name:
org.example.petshop.web.PetshopApp
If your application uses
path parameters
they will be defined as constants in a separate class. Optionally you can create a class
which defines constants for every resource URL exposed by your application.
By convention we use the suffixes "PathParams", "Resources" for these classes and place
it in the application package:
org.example.petshop.web.PetshopPathParams
org.example.petshop.web.PetshopResources
As will be described later, you need to implement
a Controller class for each dynamic resource of your application.
Their class names and package structure are used to derive their resource URLs,
so designing your resource URLS will automatically structure your controller classes
and packages.
The name of the root package of your controller classes must be known to the application
base class. By default it equals the application package, else you must explicitly
register it by passing to the Application constructor.
org.example.petshop.web.LoginController → /login
org.example.petshop.web.food.OrderController → /food/order
Controller classes may have helper classes to process their resource. We usually put them
into the controller package and use naming conventions to express that they form a functional group:
org.example.petshop.web.food.OrderController
org.example.petshop.web.food.OrderForm
org.example.petshop.web.food.OrderTemplate
Your application may define any other packages, for instance for accessing the data back-end.
Keeping those separate from the controller packages is a good idea:
org.example.petshop.service
org.example.petshop.text
Main development tasks
Developing a Civilian application has these main tasks.
- Design the URL interface of your application, including parameters, allowed REST methods and content types, etc.
- Design the expected responses when calling these URLs.
- Scaffold a new application.
- Configure the application via the Civilian config file.
- Implement an Application class to
- define all path parameters used by the application
- implement additional programmatic configurations
- initialize and provide application global resources like data back-end services.
- Create Controller implementations for every dynamic resource exposed by the application.
Controllers most probably will rely on a data back-end services to retrieve model, completely in control by your application.
- Implement Templates to be used by controllers to turn models into views.
- Implement Forms to be used by controller to read and write HTML forms.
- Assemble and organize static assets like JavaScript, CSS, image files, etc.
- Take care of application security.
- Enjoy rapid development using special Civilian development features.