README.md.
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 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.
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.
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: 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.
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.
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 the Form class.
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.
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 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 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.
The Upload sample demonstrate how to configure Civilian to allows upload of files using the multipart/form-data content-type.