Framework developement

1. Introduction

This document is an overview of the architecture. The goal is to provide a general idea of what is each layer/component for, and the extension points it provides. This is not a reference document. Detailed technical information will be provided in another document.

back to top

2. Technologies

This section gives a short overview on the used technologies in the basic sample.

• Annotations

• Aspect Oriented Programming (AspectJ)

• Hibernate

• iText

• Java 6

• Javadoc

• jQuery

• JSON

• JUnit

• Log4J

• Maven

• Spring (Framework, MVC, Security)

• Tiles

• Tomcat

• XML API

back to top

3. Architecture

This section gives a short overview on the architecture.

back to top

3.1 Architectural Layers

Our application has a layer architecture. Layers is an architectural design pattern that structures applications so they can be decomposed into groups of subtasks such that each group of subtasks is at a particular level of abstraction. Our application has a layers architecture exactly like on picture below.

back to top

3.2 Layers Description

• Database

  • Application database. There is stored all application data. Database consists of framework tables and plugins tables which have accurate plugin prefixes. In this version application use Postgres database. In next version we consider support for other database engine (Oracle, MySQL, MSSQL).

• Data layer and generic entity

  • Data layer in our application use DAO pattern to operate on database. The DAO design pattern provides a technique for separating object persistence and data access logic from any particular persistence mechanism or API, making it ideal for a data access layer. The DAO approach provides flexibility to change an application's persistence mechanism over time without the need to re-engineer application logic that interacts with the data access layer. As a base our data acces layer we use Hibernate with hbm files. Hibernate provide us mechanism to simple mapping database tables to persistence entity. Our data acces layer is responsible for transforming hibernate entities and added for table custom fields to one generic entity. This entity has a map where all fields are aggregated into key-value pair. The key is the name of the field from its definition. Generic entity provides accesors for the map values and other usefull methods (details in QCADOO API). Generic entity is the one and only data transfer objects which is used to exchange data between data layer and service layer.

• Service layer

  • Service layer in our application is responsible for provide one common interface to database access within data access layer. This interface in our system is DataAccessService (details in QCADOO API). It also use particular data utility and helpers for data layer like utils for searching, sorting, paging and so on. Other role of the service layer is to provide services to create and manage model and view definitions which are deployed in the plugins. This contract is discharged in interface DataDefinitionService (details in QCADOO API). Service layer is responsible also for all business logic which is provided by QCADOO application. All services in service layer are created and managed by Spring Framework with annotations.

• View layer and DTO's

  • The view layer obtains data from the model and presents it to the user, shortly it represents the output of the application. We use Spring MVC to create and manage views. Spring's Web MVC framework is designed around a DispatcherServlet that dispatches requests to handlers, with configurable handler mappings, view resolution, locale and theme resolution as well as support for upload files. The DispatcherServlet is an expression of the "Front Controller" design pattern (this is a pattern that Spring Web MVC shares with many other leading web frameworks). Spring Web MVC allows you to use any object as a command or form object - there is no need to implement a framework-specific interface or base class. Spring's data binding is highly flexible: for example, it treats type mismatches as validation errors that can be evaluated by the application, not as system errors. All this means that you don't need to duplicate your business objects' properties as simple, untyped strings in your form objects just to be able to handle invalid submissions, or to convert the Strings properly. Instead, it is often preferable to bind directly to your business objects. Our view layer can present view as a web pages, pdf or xls documents. CrudController is our main component responisble for manage requests to generic form views. We also use Tiles framework and JQuery library to build our views. For better separation layers we use DTO's object (design pattern used to transfer data between software application subsystems) build with using JSON format.

• Crud Controller
  • This is a controller responsible for CRUD views creation and managment. This controller manage application standard views consists of generic application components (grids, forms, inputs and so on). 

• Client browser

  • Client browser is a web browser responsible for all client side operations. Operations which are executed on the client side: initial validation, simple logic between elements of the view, some drawing and styling operations, some simple logic responsible for handling communiation with the server. Most of our client side logic is developed with using JavaScript JQuery library. Client browser has to support handling JavaScript, AJAX, Common style sheet. Our application support following browsers: Firefox 3.0+, Internet Explorer 7+, Safari 4+, Opera 9+, Chrome 5+.

• Security

  • Security in QCADOO application is provided by Spring Security. Spring Security is a powerful and highly customizable authentication and access-control framework. It is the de-facto standard for securing Spring-based applications. For authentication we use Form-based authentication mechanism with AuthenticationManager using database to store users details. For authorization we use global method security mechanism provided by Spring Security. There is also many filters and components responisble for session management, requests filtering, SSL management and hierarchical roles provided by Spring Security.

back to top

3.3 Qcadoo framework and framework plugins

Qcadoo application has a very modular architecture. Every business functionality can be added to application with new plugin. This extensibility and configurability is achieved using the Spring Framework, a de-facto standard enterprise open source framework. Qcadoo has made Spring the core foundation of its architecture. Qcadoo components are declaratively configured and bound together using Spring configuration. Aspect-oriented programming features of Spring allows the weaving of infrastructure concerns such as Transactions and Security into components without duplicating functionality. Our plugin architecture is shown on the picture below.

back to top

3.4 Qcadoo framework and framework plugins description

Framework

Framework is a basic part of the system which provides global security mechanism, transaction mechanism, data access common services, view and data definition common services, message translation mechanism, report core funcionalities, plugin management and communication between plugins.

• Transactions

  • To provide transaction management we use Spring Framework mechanisms. More infromations you could find at this link Transaction Management

• Qcadoo model

  • Qcadoo model is Qcadoo framework system plugin responsible for Hibernate entities and mappings preparation based on our model defintions. It also is one common interface to database access in our system. More infromations you could find in QCADOO API.

• Qcadoo view 

  • Qcadoo view is Qcadoo framework system plugin responsible for creation and management views and menu definitions which are deployed in the plugins. More details you could find in QCADOO API.

• Qcadoo localization

  • Qcadoo localization is Qcadoo framework system plugin responsible for message transaltion and number or date format localization. To provide message translation mechanism we extend ReloadableResourceBundleMessageSource class which is a part Spring Framework. Our extension works exactly in the same way like parent class with one diffrance. Our component read translations from multiple translation files (framework and other plugins translations). More infromations you could find at this link Resource Bundle Message Source

• Qcadoo plugin 

  • Qcadoo plugin is Qcadoo framework system plugin which provided functionality to manage plugins state flow and every operations connected with this functionality. More details you could find in QCADOO API.

• Qcadoo report
  • Qcadoo report is Qcadoo framework system plugin responsible for base functionalities need for report data preparation and report creation.

• Qcadoo security
  • Qcadoo security is Qcadoo framework system plugin responsible for security. Security mechanism is described above in Layers Description chapter.

• Qcadoo mail
  • Qcadoo mail is Qcadoo framework system plugin responsible for sending emails.

Plugin management

This is a plugin responsible for plugin management. We could download plugin file to application tmp directory. We also could enable, disable, update existing plugin. There is a possibilty to uninstall plugin from application space. First activation, update and deinstallation process include server restart, so it can take more time then usually action. It isn't a system plugin so it can be uninstalled or deactivated.

Menu management

This is a plugin responsible for menu management. We could create, edit and remove first level menu items in this plugin forms. There is also possibility to create, edit and remove second level menu position with it view. We could also change order or activity menu position. It isn't a system plugin so it can be uninstalled or deactivated.

User management

This is a plugin responsible for user management. We could create, edit and remove user in this plugin forms. We could also view user roles and change it for user. It isn't a system plugin so it can be uninstalled or deactivated. Deinstallation process remove user management functionality but doesn't remove user and roles from the system. Users nad roles objects are used in spring security layer which provides us authentication and uthorization mechanisms.

Dictionary management

This is a plugin responsible for dictionary management. We could create, edit and remove dictionary items in this plugin forms. It isn't a system plugin so it can be uninstalled or deactivated. Deinstallation process remove dictionary management functionality but doesn't remove dictionaries from the system.

Other application plugins

Other application plugins should be described in Qcadoo Store.

back to top

Qcadoo application plugin is a ordinary Maven project.

Project structure

Please find attached file as a base of the new plugin. 

• src/main/java/pluginpackage/
• src/main/resources/pluginidentifier/locales/pluginidentifier_en.properties
• src/main/resources/pluginidentifier/model/*.xml
• src/main/resources/pluginidentifier/view/*.xml
• src/main/resources/pluginidentifier/public/css/
• src/main/resources/pluginidentifier/public/img/
• src/main/resources/pluginidentifier/public/js/
• src/main/resources/WEB-INF/jsp/pluginidentifier/
• src/main/resources/root-context.xml
• src/main/resources/web-context.xml
• src/main/resources/qcadoo-plugin.xml
• pom.xml 

Plugin inner structure

There is a plugin inner structure on the picture below.

Plugin state flow

There is a plugin state flow on the picture below.

Plugin state transitions

All operations below check plugin dependencies, framework version and other conditions. When all conditions are met then operation succeed, otherwise failed and appropriate state is returned. More infromations you could find in QCADOO API.

• Download

  • This operation download plugin jar file to the application tmp directory and create database record on the data in plugin descriptor with state "temporary". After this operation jar views aren't active.

• Install

  • This operation move plugin jar file from the application tmp directory to the application context and change database record state to the "enabled". After this operation server is restarted. When server starts up plugin jar file is deployed. After this operation jar views are active.

• Disable

  • This operation change database record state to the "disabled". After this operation jar views aren't active.

• Enable

  • This operation change database record state to the "enabled". After this operation jar views are active.

• Uninstall

  • This operation remove plugin jar file and its deployed resources from the application context and delete database record.
    After this operation server is restarted and jar views aren't active.

• Update

  • This operation check the plugin version, if its version is lower than in plugin jar file, operation can update plugin. After this check old plugin jar file and its deployed resources are removed from the application context. New plugin jar is downloaded to the application context and database record version is changed to this from plugin jar file. Plugin state is exactly the same as before update. After this operation server could be restarted. When server starts up plugin jar file is deployed. After deploy jar views are active if state is "enabled".