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.
A Civilian deployment consists of the application classes, third-party libraries (e.g.
Civilians primary (and right now only) runtime environment is a servlet container, therefore
the directory layout of the application is that of a
WEB-INF directory contains a
web.xml file and a configuration file
civilian.ini. Both are described in the
|Civilian config file
|classes, Java resources
To deploy to a servlet container your build process must be able to produce a WAR file with these directory layout.
During development we usually embed that structure into a IDE project.
|project root dir
|compiled application classes
|corresponds to $web in the previous table
|same as the WEB-INF directory in the previous table
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.
Each Civilian application has an application class derived from Application
You can freely choose its package and name:
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:
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
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:
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:
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.
- Take care of application security.
- Enjoy rapid development using special Civilian development features.