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