Technical design

From Complete Cyclos documentation wiki
Jump to: navigation, search

Cyclos overview

Cyclos 3 arquitecture

MVC Structure

Cyclos is build according to the Model-View-Controller concept. There are 3 layers:

  1. 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.
  2. The View is located in the cyclos3_web project, those are the jsp's showing the pages.
  3. 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.

Workflow

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.

Development files

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

Create menu item			in menuMember.jsp or menuAdmin.jsp
					cyclos3_web/pages/general/layout

Create or edit struts-configs file	e.g. struts-config_ads.xml
					cyclos3_web/WEB-INF/struts-configs
                                        (if a new config file is created you will have to add an                              
                                        entry in the general struts-config.xml file that is located   
                                        in the same directory)

Create or edit tiles defs file		e.g. tiles-defs_ads.xml
					cyclos3_web/WEB-INF/tiles-defs

Create jsp page				e.g. searchAds.jsp
					cyclos3_web/pages/pages

Create JavaScript page			e.g. searchAds.js
					cyclos3_web/pages/pages

Create translation keys			in ApplicationResources_en_US.properties
					cyclos3_web/WEB-INF/classes

Create help files			e.g. search_ads_by_member.jsp
					cyclos3_web/pages/general/translation_files/help_windows

Create form class			e.g. Se	archAdsForm.java
					cyclos3_web/WEB-INF/classes/nl/strohalm/cyclos/controls/ads

Create action class			e.g. SearchAdsAction.java
					cyclos3_web/WEB-INF/classes/nl/strohalm/cyclos/controls/ads

Model
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

JSP pages

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

JavaScript libraries

We do not use JavaScript directly in JSP pages but for each JSP page exists a JavaScript file with the same name of the JSP page (but with the .js extension). The JavaScript page can contain JavaScript code and call the JavaScript libraries that are available in Cyclos (in cyclos3_web/pages/scripts). Cyclos makes use of custom JavaScript libraries like virtualKeyboard.js and open JavaScript frameworks like scriptaculous.js and prototype.js. It is not necessary to include the JavaScript libraries because they are included in the (hidden) head.jsp file that is part of the main layout.

Tiles

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: /cyclos3_web/WEB-INF/tiles-defs.
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)

Translation files

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/

Help files
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 classes

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:

  • BaseQueryAction

This Action is for handling query actions on the database (for showing data), navigation, and other query-related actions.

  • BaseCsvAction

This Action is used to generate CSV format reports.

  • BaseAjaxAction

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.

  • BaseFormAction

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

Entity classes

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

Services layer

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.

Aspects (AOP)

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

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

Scheduling

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

Setup

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.