runsamples.txt.
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.
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.
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.
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.
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.
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.
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.
Games is another demonstration of Forms.
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.
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.
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.
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
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.
The Locale sample shows how to produce locale dependent output, even using mixed locales in a single page.
This is essentially the same application as generated by the scaffold tool.
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.
The Upload sample demonstrate how to configure Civilian to allows upload of files using the multipart/form-data content-type.