- 1 Cyclos overview
- 2 Cyclos view layer
- 3 Cyclos Control Layer
- 4 Cyclos Model Layer
Cyclos is build according to the Model-View-Controller concept. There are 3 layers:
- The Model is located in the cyclos3 project. It is the layer that connects to the data. This project defines the entities, which are mapped to the database, and it defines the services that respond to calls from the control layer. Services are defined by a service interface (used by the web layer) and a local interface (used by other services). There is also a security layer for services, which implement the service interface and is responsible of checking the permissions for each method being invoked.
- The View is located in the cyclos3_web project, those are the jsp's showing the pages.
- The Controller is also located in the cyclos3_web project; those are the java (action) classes of this project especially the ones under nl.strohalm.cyclos.controls. The connection to the model layer is done via the service interfaces.
The Cyclos workflow (through all layers) can be summarized as follows: JSP > Struts/Spring > Service > DAO
There are two ways to interact with a web application: by selecting a link, which in most cases will be a menu item (GET request) or by clicking the submit button of a form (POST request). On these requests the following happens:
- Any request will be caught by Struts and passed to its related action (Control) class (it gets this information from the struts-config files).
- All control classes extend the BaseAction class that takes care of the authentication and handles common exceptions.
- When a form is filled in and submitted Struts puts it into a form object (a class that extends the Struts ActionForm class).
- The control class will put the form object into an object that is prepared for the model layer like a query parameter object or entity object. DataBinders are used to convert strings into proper data types like numbers, dates, entities, collection and the other way around (result data that need to be put back from objects to strings that will be shown in the jsp pages).
- The control class will pass the data objects to the services layer that handles the business logic.
- To store or retrieve data from the database the services layer uses the DAO (data access object) layer. The DAO layer accesses the database via the Hibernate framework.
- When all these actions are done Struts will forward the request with result data (in the request object) to Tiles and Tiles will compose the correct jsp result page.
When adding a new functionality various files need to be created and configuration files edited. Here is a list of the files. The Cyclos development files are listed below in blocks per project. The name of an example file is listed first and the location (directory) below.
View & Control
Cyclos project: Cyclos3_web
Cyclos project: Cyclos3
Create entity class and hibernate mapping file e.g. Ad.java and Ad.hbm.xml cyclos3/src/nl/strohalm/cyclos/entities/ads Create service interface and local interface e.g. AdService.java and AdServiceLocal.java cyclos3/src/nl/strohalm/cyclos/services/ads Create service security e.g. AdServiceSecurity.java cyclos3/src/nl/strohalm/cyclos/services/ads Create service implementation e.g. AdServiceImpl.java cyclos3/src/nl/strohalm/cyclos/services/ads Create DAO interface and implementation e.g. AdDAO.java and AdDAOImpl.java cyclos3/src/nl/strohalm/cyclos/dao/ads Create DTO (Data Transfer Object - optional) e.g. StatisticalResultDTO.java cyclos3/src/nl/strohalm/cyclos/services/reports Create exceptions (optional) e.g. NotEnoughCreditsException.java cyclos3/src/nl/strohalm/cyclos/services/transactions/exceptions Map DAO, Service Security and Service aop.xml, dao.xml, persistance.xml, service.xml, security.xml implementation in Spring config files cyclos3/src.nl.srtohalm.cyclos.spring
Cyclos view layer
The JSP pages are straightforward. In order to keep the JSP code readable please do not use word wrapping in your editor. For the same reason (readiblity) we use the JSTL core tags in favor of the Struts logic tag (for example c:if, c:choose etc.)
The JSP pages can make use of some Cyclos custom tags, defined (and described) in the cyclos-core.tld. The Tag libraries are located in cyclos3_web/WEB-INF/classes/nl/strohalm/cyclos/tablibs
Tiles is a framework that composes the layout from components (jsp pages) in a hierarchial structure. The Tiles framework allows the reuse of pages (components) what reduces the amount of code that needs to be maintained and makes it easier to change the look and feel. The JSP layout pages are located in the directory: cyclos3_web/pages/general/layout
The Cyclos layout consists mainly of three components (pages). These are:
- top.jsp (logo and other fixed text in the top bar)
- menuAdmin.jsp, menuMember.jsp and menuOperator.jsp (the member or admin menu at the left)
- layout.jsp: the main page that composes the entire layout.
The layout of Cyclos is defined in the tiles-definitions files that are located in the directory:
When adding a new function you mostly will create a new function window (in a jsp page). After this you you will need to inform Tiles how the page fits in the Cyclos layout. This is quite simple, you will just need to create a menu item and add a tiles definition that extends either the member menu or admin menu tag. An example of the detailed working of Tiles is given in Example 1. View layer (Tiles / JSP)
The translation of Cyclos in other languages can be in found in the following files:
Main translation file
This is the file that contains all text in the application. That means all the text in the menus, windows and messages. There is one file per language. The name of the file contains the ISO standard language code name. For example: the English (US) one is ApplicationResources_en_US.properties
Database setup translation file
When the embedded database creation option is used Cyclos will create a default database with an account, group and permission structure and will populate the database with default settings. The setup process will create the database acording to the language locale set in the cyclos.properties file. There is one setup language property file per language. The files are located in cyclos3/src/nl/strohalm/cyclos/setup/
Every function window has its own help file. A help file can be included in the JSP page using the <cyclos:help> custom tag, for example: <cyclos:help page=”search_ads_by_member”/> The help file names do not contain the language ISO code in the names (like the main translation file). The files get their language from the directory they reside in. For example: /pages/general/translation_files/help_windows/en_US/search_ads_by_member.jsp
Note1: All translations can be modified directly from the administration section (in content ‘Content Management’ menu)
Note2: In the properties files we use unicode for all special caracters and caracters with accents. The cyclos development team uses Eclipse with Jinto plugin to manage the language properties files. The plugin converts all special characters and accents to unicode.
Cyclos Control Layer
Action is the standard Struts Action class that controls the requests and outputs and acts as a bridge for controlling and passing data (forms and attributes) between the JSP pages and the business logic layer (model). The Struts Action class is implemented by the Cyclos BaseAction, which is responsible for general behavior like initialization and it will check if the logged user has a valid session. It has four descendants for different types of usage. These actions are described below:
This Action is for handling query actions on the database (for showing data), navigation, and other query-related actions.
This Action is used to generate CSV format reports.
This Action can be used for showing some user interface changes in case you don't want to reload the whole page. The BaseAjaxAction is the common class for Actions that just render content into Ajax requests.
This Action handles common form-input pages, with 3 states: display, validation and submit
The cyclos programming team encapsulated all calls that are received by the Struts Action classes (ActionMapping, ActionForm, HttpServletRequest e HttpServletResponse) in one object of the type ActionContext. This class extends AbstractActionContext, an extract class that contains also the logged user and some utility methods.
Cyclos Model Layer
All entity classes in Cyclos extend the main Entity and are located in subpackets of nl.strohalm.cyclos.entity. Each entity objeto has acces to the instance ID of the entity and some common methods like equals(), hashcode() etc.
Object – relational mapping (ORM) using Hibernate
The Cyclos entities need to mapped the database tables. This is done in the hibernate mapping files. The hibernate mapping files are located in the same packages as the entity classes that they map. For example in the directory as the ad entity cyclos3/src/nl/strohalm/cyclos/entities/ads you will find the ad entity Ad.java and the related mapping file Ad.hbm.xml
DAO (Data Access Object) layer
The DAO classes are the classes that are responsible for basic access (crud create/remove/update/delete) to the database. They are located in the package cyclos3/src/nl/strohalm/cyclos/dao For each entity there is a DAO interface that defines the methods and a class with the implementation. For example AdDAO.java and AdDAOImpl.java
All business logic of Cyclos resides in the services. They have 2 interfaces: the "remote" service interface, used by the web layer and a "local" interface, which extends the remote and adds methods used only by other services (they can be seen as internal methods). Then there are 2 implementations: a security layer, which implements the remote interface and is solely responsible of enforcing the access of the logged user to the current method and the service implementation itself, which is responsible of performing the business logic. Services are located in cyclos3/src/nl/strohalm/cyclos/services and are grouped in logically named packages (e.g. access, accounts). Some of these packages contain a package called exceptions where the exceptions related to the group are located.
DTO (Data Transfer Objects) objects
DTO objects are used in cases where complex parameters needed to be passed from view to the model layer and somethimes within the model layer. The DTO objects are located in the same location as its related service.
The aspect classes are intercepting specific service methods and will add functionality and behavior based on aspect rules. Typical aspect uses are permissions checks, logging and notifications.
The aspect classes are located in cyclos3/src/nl/strohalm/cyclos/aop
Util classes are helper classes used by the services layer for all kind of common needed functions. Date convertions etc. The Util classes are located in cyclos3/src/nl/strohalm/utils
The scheduling classes are used to execute tasks that need to run periodically. Tasks can be registred in the config file cyclos3/src/nl/strohalm/spring/scheduling.xml The scheduling classes are located in cyclos3/src/nl/strohalm/scheduling
When the embedded database creation option is used Cyclos will create a default database with an account, group and permission structure and will populate the database with default settings. If you want anything within a new function be part of the default database (field, permissons) you will have to add them to the Setup.java file located in cyclos3/src/nl/strohalm/setup
Dependency injection using Spring
The communication between the model, data and control/view layers in Cyclos3 is not hardcoded. The Spring framework is used to ‘tie’ the interface layers dynamically together. The ‘binding’ of the layers is specified in the Spring configuration files.