# Canigó (framework)

Canigó is the name chosen for the Java EE framework of the Generalitat de Catalunya.

## Purpose and architecture

Canigó is defined as a "common technological framework for development and execution of web applications for corporative systems and departments of the Generalitat de Catalunya".
It covers various functionalities:
* A common architecture for Java EE application building.
* Supplies a workspace, documentation, support and maintenance of its components.
* Simplifies the complexity inherent to Java EE, offering a referent framework.
* Offers a solution in keeping with the de facto standards all over the open source community.
* Offers an open solution that enables the possibility of adding and exchanging any piece of software with reduced costs.
* Offers an interconnectivity solution with the corporative services of the Generalitat de Catalunya.
Canigó's architecture is based on Model–View–Controller. There is an abstraction process that allows the division of the application logics in three main components able to be developed by different roles of a team.
Actually Canigó's architecture, as a MVC structured framework, is divided in 3 layers and 4 cross-cutting modules:

### Layers

* Presentation layer
* Business Logic layer
* Data Persistence/Integration layers

### Modules

* Framework Core
* Security modules
* Support module
* Operation module
Canigó's a modular structure gives to developers the option to use only the needed modules to cover project requirements. Those modules are defined through interfaces, isolating them from chosen implementations.
Canigó is based on a series resources, API's integration as JPA, and open source packages (Spring, Swagger, ...). It also offers extensions for those packages, adding a wide catalog of reusable components.
One of the most important architectural basis is decoupling frontend and backend using REST API's. This architecture allows independent development teams to work on the frontend and backend.
The framework consists of the blocks specified below:

## Framework architecture base components

Spring is an open source framework written for the Java platform. The first version was created by Rod Johnson in October 2002 and the last release version is 5.0.9, published on the first week of September 2018. Canigó is designed to help with the configuration of web applications, and also to simplify systems construction in different pieces (easily interchangeable and visible between them), service integration, security services, database connection, transactionality, etc... Spring provides a complete testing system, it's possible to develop unitary tests uncoupling objects from its context making easier the execution of the test cases. The external data access, through Spring, is an easy task because this framework manages the resources by itself. It also has support APIs and it's able to bear the vast majority of Java industry data access technologies like: JDBC, Hibernate, JPA, JDO or iBatis.
The main basis of Canigó's architecture is a completely integrated group, also modular, of the best practices in Java web applications developing technologies. These are the actual components that constitute the system:
* Swagger is an open source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test case generation.
* Spring4 Framework as a centralised object and services container, completely configurable through XML files or Java annotations. Dependency injection allows the configuration of objects out of application's code with a non-intrusive approach. It reduces application's code dedicated to configurations and resources localisation. It also facilitates best practices like programming against interfaces instead of classes, allowing the uncoupling of services and the rapid change of a given implementation for another one. It also allows managing transactions without using specific APIs by the use of Aspect Oriented Programming.
* JPA provides a persistency model based on POJOs to map the Java relational data bases. Also MongoDB, the most popular non-relational database, is supported.
* AOP (Aspect Oriented Programming) for application's event interception without modifying the source code.

## Framework core

This module is the core of the framework, here is where the main features are located:
* Multi-Environment Configuration: Based on the PropertyPlaceHolder provided by Spring3. With the difference that it allows the existence of environment-dependent properties without any extra beans or properties configuration.
* Multi-Language (i18n): Its objective is helping in the application development phase by facilitating the support of multiple languages.
* Trace Service: Based on Log4j. It allows the definition of the tracing level, outputs, minimum trace level, output format, context information.
* Exception Service: Generates information about any error existence during the execution of a request. Canigó offers a series of exceptions by default (BaseException, CoreException, ...). It also has an exceptions interception mechanism to avoid the excessive use of "try-catch".

## Security module

It is the user's authorisation and authentication applications access management system.
* Security Module: Based on Spring Security 4.x. It's able to manage the authorisation and authentication of applications users.
* Security Backends: The security service is integrated with GICAR, SACE, LDAP, Data Bases and Inmemory.

## Presentation (UI) module

Since Canigo 3.2.0, JSF has been deprecated as a presentation layer technology. Presentation layer responsibility has been delegated outside the framework to another teams specialized on front-end technologies as Angular or React.

## Integration module

Its goal is providing simple access to the different services offered by the Generalitat de Catalunya.
* PICA: Provides an integration Java interface to access the 'Plataforma d'Integració i Col·laboració Administrativa' (PICA). This module is able to execute synchronous and asynchronous requests.
* GECAT: This module has a set of functionalities for invoice management offered by the SAP service of the Gecat.
* PSIS: It is a digital signatures and digital certificates service offered by the Catcert.
* SARCAT: Is a series of methods to execute the services offered by S@rcat, through WebServices, FTP/SFTP for planned requests.
* Documentum: Enables the consumption Documentum functionalities like document filing and retrieving, it is also able to manage folders and metadata.
* NT: Is a functional connector for the PICA that simplifies the use of telematical notifications of the Generalitat de Catalunya.
* Antivirus: Is an integration of the CTTI (Information Technologies and Telecommunications Centre) file scanning system of the Generalitat de Catalunya.
* SAP: It is a simplified interface to access the SAP backend of the Generalitat de Catalunya.
* Webservices: Canigó 3 does not have a native webservices module. There is a complete documented guide about how to export, publish and consume webservices with Java. Canigó 3 encourages the use of Spring WS, Jaxb and OXM.
* Queues: Canigó 3 does not have a queue management module. There is a guide about how to generate and consume messages from a queue. The use of Spring JMS is recommended.

## Persistence module

This module enables the application with data persistence and retrieval between application and database management systems.
* JPA: Java Persistence API Unifies the tools for the ORM (Object-Relational Mapping). The default JPA implementation in Canigó 3 is Hibernate. Spring Data JPA makes it easy to easily implement JPA based repositories. It makes it easier to build Spring-powered applications that use data access technologies.
* MongoDB: easily integration with MongoDB document database thanks to Spring Data MongoDB.

## Support module

This module delivers some additional features to the framework.
* File Transfers: Enables the server to receive enclosed files in an HTML form.
* Mail notification: Enables the server to send emails to multiple addresses. It handles plain text and html message content format. It also can enclose multiple files.
* Task Planner: Based on Spring and Quartz. Enable the option to execute deferred tasks based on predefined time schedule rules.
* OLE: It can manipulate MS Excel and Word OLE document formats. It enables the possibility to create, read and modify documents. It is based on the POI library.
* Merging: Document fusion in WordML format. Starting from a tagged document, those variables are exchanged by a group of values defined in a dictionary.
* SFTP: Enables the file transmission between the server where the application is deployed and other servers through a secured protocol. It is based on JSCH and Commons-VFS libraries.

## Operations module

This module adds a feature to applications to generate execution and instrumentation data. This data is ready to be mined and processed by monitoring tools.
* Instrumentation: Enables the application with the capability to generate instrumentation data (Queries count, errors count, ...), this data comes from the execution of the application.
* Monitoring: Enables the application to show a screen to get access to the instrumentation module generated data.
* Logging: Enables the application to administer log appenders (activate, deactivate, change log level) and view logs on real time with WebSockets.