Samples

Civilians includes sample applications which demonstrate its features.

Introduction

Civilian includes sample applications which demonstrate the framework features.
To run the samples you may either download

The samples

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 sample demonstrates Dependency Injection (DI) using the Context and Dependency Injection framework (CDI) of Java EE 6+.
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.
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 how to create asynchronous responses. After you chose a user name you can write messages to the chat board which are broadcasted to all participants.

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: It is a proof of concept how to build a complex Single Page Application using a modern JS framework on the client (here Angular JS) and a REST-based server.

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 based on AngularJS 1.0 . 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 deliberately throws various kinds of runtime exceptions. When in development mode Civilian tries to maximize insights in what is going wrong, whereas in production mode the error messages are trimmed down to the necessary.

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 the Form class.

Guice

ControllerFactory DI Guice

The Guice sample demonstrates Dependency Injection based one Google 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 params

Controller Action Arguments Annotations Forms

The 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 TestServer, 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.