Samples

Civilians includes sample applications which demonstrate its features.

Introduction

Civilian includes a set of sample applications which demonstrate the framework features.
To run the samples you may either download
  • the samples WAR file, ready to be deployed in a servlet 3.0+ container, or
  • the distribution and follow the instructions in its runsamples.txt.

The samples

Below we provide a short description of each sample:

Civilian Admin

Admin App Assets CSP Resource Constants Resource Linking Resource Service

The admin application of Civilian is part of the core distribution but also enabled in the samples. It gives you an overview of the configurations and resources of each deployed sample app.

CDI

CDI ControllerFactory DI

The CDI samples demonstrates Dependency Injection (DI) using CDI.
At startup the application installs the CdiControllerFactory, in order to inject CDI managed beans via javax.inject.Inject annotations into Controllers.
CDI support is experimental. If you look into the CdiControllerFactory code and compare with GuiceControllerFactory you will understand why.
The CDI app is disabled by default since it requires a JEE environment. To activate, set app.cdi.enabled = true in civilian.ini, save it back to the sample war and deploy in a JEE server, such as TomcatEE or JBoss Wildfly.

Chat

Async Response

The chat app demonstrates asynchronous response. After you chose a user name you can write messages to the chat board which are broadcasted to all participating users.

Client

Client Resource Constants WebResource WebUrl

The Client sample is not a server-side application but demonstrates how to build URLs to access resources of a server application from a Java client program.
Its CrmRoot class describes the resource tree of CRM app and was generated using ClientConstGenerator.
Given the resource constants in CrmRoot one can easily construct WebUrl objects, add path and query parameters and finally create a URL string from the WebUrl. You could then use a HTTP library like Apaches HTTP Client or a JAX-RS client to send requests.

CRM

Ajax Angular JS Assets Controller Hierarchy CSP JSON L10N REST Security

The CRM sample is the most complex sample on the block.
It is a proof of concept application how to build a Rich Internet Application (RIA) using a MVC/MVVM Javascript on the client (here Angular JS) and a REST-based server (you guessed it: Civilian).

The navigation design of the sample CRM allows the user to build an arbitrary complex state: Opening multiple modules to handle CRM core objects like customer, opportunities, etc.

The client is realized with AngularJS. Therefore the server will provide HTML page fragments containing Angular code. Beyond that all data is exchanged between server and client in JSON form. Both templates and data requests are done with Ajax calls.

To not crucify startup time we use transparent lazy loading for HTML templates and Javascript code: This is implemented in the angular module civLoad, located in civassets/angular/civ-load.js in the core source.

The sample also demonstrates several security related solutions:
The client should not switch to a login page, when its server side session has a timeout, since it would loose all its client state. Therefore it uses a transparent login popup which is shown when a Ajax call returns with a 401 error: The login popup is shown and then the original request is repeated. Again the solution is implemented in an angular module civLoad, located in civassets/angular/civ-auth.js in the core source.
Users in the CRM sample have different access rights: We use the Controller class hierarchy to implement and enforce security checks.

Even if the CRM is a single-page application, it allows to access single modules or objects in own windows, as explained on the CRM landing page. Again controller inheritance was heavily used to implement this feature.

Error

Development Error Messages

The error sample has a vandalizing nature and deliberately throws various kinds of runtime exceptions.
This is just a demonstration of how Civilian tries to give meaningful insight in what is going wrong during development time. If you switch the Civilian context to production mode, and revisit the sample, you will see how the error messages change accordingly.

Form

CSP Forms Mixin FormTable

The Form sample demonstrates the use of the form package. Roundtrip applications can use Form objects to print HTML forms and read the values from a submitted form in a typesafe way.

Game

CSP Forms Session

Games is another demonstration of Forms.

Guice

ControllerFactory DI Guice

Guice is another Dependency Injection sample, this time using Guice. Just create an Guice Injector during application startup and install a GuiceControllerFactory to insert dependencies into your controllers.

Helloworld

Classic Minimal Art Must Have

The smallest possible sample: It justs consists of a single Controller, and does not have an application class instead uses a package entry in its application config.

Inject

Controller Action Arguments Annotations Forms

The inject sample demonstrates how to inject request values into the parameters of a controller action method. It also demonstrates how to define an own custom annotation: @RemoteIp injects the IP of the caller into a controller action parameter.

JPA / JTA

CDI JPA JTA

The sample demonstrates use of the Java Persistence API (JPA) and JTA in a Civilian application. Data services are injected into Controllers using CDI. This requires the installation of a CdiControllerFactory during application startup.
The data services uses JPA and JTA managed transactions.

The sample is disabled by default since it requires a JEE environment. To activate, set app.jpa-jta.enabled = true in civilian.ini, rebuild the sample WAR and deploy in a JEE server, like TomcatEE or JBoss Wildfly

JPA / Resource Local

Controller Hierachy Controller Lifecycle JPA Resource Local Transactions

The sample demonstrates use of the Java Persistence API (JPA) in a Civilian application, setting the transaction type attribute to resource local.
It introduces the helper class org.civilian.samples.jpa.reslocal.model.JpaContext, which provides an JPA EnitityManager to data services. It possesses a EntityManagerFactory, created by the application at startup.
JpaContext associates the EntityManager with the current thread, therefore the same EntityManager is used when processing a request. To cleanup correctly we use Controller.exit() to free the threadlocal EntityManager. Since it is defined in a common controller base class, it will work for all exposed resources.

Locale

CSP L10N Lang Mixin ResMsgBundle ResBundleCompiler

The Locale sample shows how to produce locale dependent output, even using mixed locales in a single page.

Quickstart

Scaffold

This is essentially the same application as generated by the scaffold tool.

Test

Test

The test sample demonstrate how to use TestContext, TestRequest and TestResponse to write automated tests for your application. It does not need a servlet environment and invokes requests on an application without the overhead of HTTP calls.

Upload

Form Upload

The Upload sample demonstrate how to configure Civilian to allows upload of files using the multipart/form-data content-type.