EUROPEAN COMMISSION
DIRECTORATE-GENERAL
INFORMATICS
Information systems Directorate
European Commission
Central Catalogue Management System
Software Architecture Document
Date:
07/10/2010
Version:
1.0
Authors:
Fausto Rubino, Marco Fichera
Revised by:
Sandro D'Orazio, Tanya Chetcuti
Approved by:
Public:
Reference Number:
Commission européenne, B-1049 Bruxelles / Europese Commissie, B-1049 Brussel - Belgium. Telephone: (32-2) 299 11 11.
Commission européenne, L-2920 Luxembourg. Telephone: (352) 43 01-1.
TABLE OF CONTENTS
1. INTRODUCTION .................................................................................................................................... 3
1.1. Purpose .................................................................................................................................................... 3
1.2. Scope ....................................................................................................................................................... 3
1.3. References ............................................................................................................................................... 3
1.4. General Overview .................................................................................................................................... 3
1.5. Document Content Overview................................................................................................................... 5
2. USE-CASE VIEW..................................................................................................................................... 5
2.1. Use Cases Selection ................................................................................................................................. 5
2.2. Architecturally significant Use Cases Diagram........................................................................................ 6
3. LOGICAL VIEW ..................................................................................................................................... 7
3.1. Overview.................................................................................................................................................. 7
3.2. Architecturally Significant Design Packages ........................................................................................... 7
4. IMPLEMENTATION VIEW .................................................................................................................. 9
4.1. Use-Case Realizations ............................................................................................................................. 9
4.1.1. The Catalogue Provider submits a Catalogue ..................................................................................... 10
4.1.2. The End-User consults the information concerning the Catalogue ..................................................... 14
Central Catalogue Management System Software Architecture Document
Page i
Document History
Version
Date
Comment
Modified Pages
0.01
01/10/2010
First Version
All
0.02
05/10/2010
Added references and revised by Sandro D'Orazio
As required
1.00
07/10/2010
Revised by Tanya Chetcuti
As required
1.01
16/09/2011
new High level diagram added
4
Central Catalogue Management System Software Architecture Document
Page ii
1. INTRODUCTION
1.1. Purpose
This document provides a comprehensive architectural overview of the system, using a number
of different architectural views to depict different aspects of the system. It is intended to capture
and convey the significant architectural decisions which have been made on the system.
1.2. Scope
The architecture described in this document concerns the Central Catalogue Management
System.
1.3. References
#
Document
Contents outline
[REF1] Spring Framework
http://www.springsource.org/
[REF2] Data Access Object
http://java.sun.com/blueprints/corej2eepatterns/Patterns/
DataAccessObject.html
[REF3] EJB 3.0 / JPA
http://jcp.org/aboutJava/communityprocess/final/jsr220/
[REF4] Hibernate
http://www.hibernate.org/
[REF5] UBL 2.0
http://docs.oasis-open.org/ubl/cs-UBL-2.0/UBL2.0.html
[REF6] XMLBeans
http://xmlbeans.apache.org/
[REF7] Spring Transaction Management
http://static.springsource.org/spring/docs/3.0.x/springframework-reference/html/transaction.html
[REF8] DOJO
http://www.dojotoolkit.org/
[REF9] Javascript
https://developer.mozilla.org/en/JavaScript
[REF10] Spring MVC
http://static.springsource.org/spring/docs/3.0.x/springframework-reference/html/mvc.html
1.4. General Overview
The Central Catalogue Management System (CCMS) is an application that provides several
services for storing, handling, querying and consulting electronic Catalogues.
The CCMS provides services both to end-users, who can access the application via a web
interface and to external systems, such as e-PRIOR, which want access e-Catalogues
information. Access is provided using standard interoperable interfaces such as web-services
and JMS queues.
CCMS is designed to manage UBL 2.0 e-Catalogues, and all data formats (services contracts,
XML documents) comply with this standard.
The CCMS includes an internal database to store e-Catalogues data, which reflects UBL 2.0 data
structure.
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 3 / 17
The following table shows the services provided to end-users and external applications by the
CCMS:
Service
Import Catalogue
External Application
Human End-Users
X
View Catalogue
X
The following diagram provides a high level view of the CCMS arhitecture:
Figure 1 CCMS architecture overview
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 4 / 17
1.5. Document Content Overview
This document details the architecture of the CCMS using several architectural views:
 Use Case view: architecturally significant use cases are shown via a use case diagram
 Logical view: the main layers and components are explained, with the aid of a package
diagram
 Implementation view: This view gives implantation details on the selected use cases. Lowlevel package diagrams, class diagrams and sequence diagrams are used at this stage.
2. USE-CASE VIEW
This section provides a representation of the architecturally significant Use Cases.
2.1. Use Cases Selection
The architecturally significant Use Cases have been selected based on the following criteria:
 Use Cases affecting multiple components of the system, thereby providing a cross-cutting
view of the system architecture.
 Use Cases representing critical parts of the architecture, thereby addressing the technical
risks of the project at an earlier stage.
The following Use Cases have been selected.
 Use Cases addressing the submission of documents by external applications (Submit
Catalogue use case)
 Use Cases involving end users accessing e-Catalogue information via the web interface
(View Catalogue Use Case)
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 5 / 17
2.2. Architecturally significant Use Cases Diagram
Figure 2: Use Cases Diagram
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 6 / 17
3. LOGICAL VIEW
3.1. Overview
This chapter describes the main application packages, how they interact and how they implement
system Use Cases.
In subsection 3.2 we describe the main packages of the system, how they are called by the
system users and how they interact with each other.
3.2. Architecturally Significant Design Packages
The following diagram provides a high level view of the main packages composing the system.
This diagram shows also the system users (represented as UML actors).
Figure 3: System Users and Main Packages
 Catalogue Provider Integration System: the Catalogue provider, in order to submit
Catalogues to the system, uses an external integration system which is capable of sending
UBL 2.0 documents to the CCMS using a standard JMS interface.
 Presentation Layer: responsible for the presentation of the data to the end-user via a web
user interface. When the users want to have access to the catalogue data, they can log in the
web application provided by the CCMS and submit a request to the system specifying the
needed search parameters. The presentation layer is in charge of transforming the user request
into a representation compliant with the business layer interfaces, sending the data to the
business layer and showing the response to the end user through a human readable format.
 Integration Layer: the CCMS integration layer is responsible of receiving, transforming and
submitting to the business layer the requests coming from external applications. For example,
for the Import Catalogue Use Case, the integration layer reads the message containing the
Catalogue from a JMS queue, checks the validity of the message and calls the business layer
for document processing.
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 7 / 17
 Business Layer: the business layer is the core layer of the application which performs all the
business activities related to requests coming from human users or external applications. It is
in charge of:
o
Transforming the incoming requests into an internal business model;
o
Processing the different elements of the catalogue and handling their persistence in the
database by calling the data access layer;
o
Processing incoming requests for information retrieval and handling the related database
calls by calling the data access layer;
o
Handling the database transactions for preserving data integrity.
The business layer can be split in the following tiers:
o
Façade: this tier provides the interfaces towards external systems. The classes belonging
to this tier provide simple interfaces which hide all the complex interactions amongst
business components. The façades are responsible for orchestrating the interactions
between classes belonging to the underlying tier.
o
Service: this tier centralizes the transaction control in a coarse-grained way and interacts
with the classes belonging to the handler tier. The transaction management is completely
delegated to the Spring Framework [REF1] which provides a consistent programming
model to deal with transactions.
o
Handler: this tier contains the implementation of the business logic and exposes atomic
and fine-grained interfaces. Moreover, the handler tier is responsible for interacting with
the data access layer in order to execute atomic operations on the central catalogue
repository.
 Data Access Layer: This layer has the responsibility for providing the interfaces access to
data stored in the database repository. The Data Access Layer is composed of the following
two main components:
o
Data Access Object (DAO) [REF2]: The DAO implements the logic required to access
and to perform atomic operations on the central catalogue repository. The business
classes use the interface exposed by the DAO so that the implementation details are
completely hidden. CCMS provides a DAO implementation based on the JPA [REF3]
specification and Hibernate [REF4] implementation;
o
Entity [REF3]: The Entity objects are Java Classes mapping the database structure. The
state of the Entity objects can be persisted in the database.
 Logging Layer: the Logging layer is used across all the other layers to log all the technical
operations performed by the application.
 Security Layer: the Security layer provides to the interface layers (Integration and
Presentation) the means to check authentication and authorization of the human end-user or
of the external application.
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 8 / 17
4. IMPLEMENTATION VIEW
4.1. Use-Case Realizations
The following architecturally relevant Use Cases have been chosen, to describe how software
components behave:
 A Catalogue provider submits a Catalogue using its integration system;
 A Customer views the information of a catalogue.
The implementation of these two Use Cases involves all of the components and all the layers of
the architecture. The description of the realization of these Use Cases will then be sufficient to
explain how all the components of the CCMS architecture interact with each other.
The following sections provides :
 High-level class diagrams which explain the relationship between the classes of different
layers of the architecture.
 High-level sequence diagrams to emphasize interactions between components and layers.
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 9 / 17
4.1.1. The Catalogue Provider submits a Catalogue
A catalogue provider can submit a catalogue via its integration system capable of sending UBL
2.0 [REF5] documents to the CCMS using a standard JMS interface. The import process starts
when a new JMS message is enqueued in the CCMS queue.
The two following diagrams provide a more detailed view of the different layers composing the
system.
Figure 4: Package diagram
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 10 / 17
Figure 5: Class diagram
The import of a Catalogue, due to the complexity of the XML document itself and of the
underlying database table, takes advantage of the different layers of the architecture, grouping
together fine-grained operations which involve the different objects that compose the Catalogue.
In detail, the following tasks are performed during the import of a Catalogue:
 Saving into the database the data about the catalogue header information: catalogue id,
catalogue version, parties' involved, referenced contract. This is the first step, since the
subsequent catalogue lines will be associated with the newly created catalogue;
 Saving the catalogue lines one by one into separate transactions. At this stage, the lines
contained in the catalogue are stored into the database. Transactions are separated, since
correct catalogue lines have to be imported even if errors are raised by other lines;
 Updating the version information concerning the items. A comparison is done with the
previous version of the Catalogue (if it exists): deleted and updated lines are removed, new
items and the unchanged items are associated with the new version of the catalogue;
 Creating the relationships among the items;
 Associating the available language translations to the catalogue version. Textual descriptions
inside the catalogue can indeed be stored in different languages, which can then be chosen by
the user when viewing the catalogue;
 Processing report. A report is created about the processing of the import of the catalogue, in
which errors or alerts on single Catalogue lines are logged.
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 11 / 17
The following sequence diagram describes the main possible interactions amongst the
components described above.
Figure 6 Sequence Diagram
4.1.1.1. Submit Catalogue in the Integration Layer
When a Supplier submits a Catalogue to the CCMS system via the JMS queue, the integration
layer reads the message using a Message Driven Bean, which validates it against the Catalogue
UBL 2.0 XSD and transforms it into objects compliant with the interfaces exposed by the
business layer (Data Transfer Objects - DTO). Messages are validated using the XMLBeans
[REF6] validation features and transformed into DTO using a Message Transformer which is a
Java Class aware of the objects representation.
4.1.1.2. Submit Catalogue in the Business Layer
The Catalogue Facade class exposes a coarse-grained interface to import the catalogue.
The method submitCatalogue() starts the business logic for importing the catalogue. The import
is split into different transactions which can be summarized as follow:
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 12 / 17
 Catalogue level transaction: in this transaction the catalogue entity is created and versioned.
Moreover all of the information directly connected to the catalogue such as parties and
framework contract associations are created in this transaction. The transaction is managed by
Spring [REF7] when the method saveAndVersionCatalogue() of the ImportCatalogueService
class is called;
 Catalogue Line transactions: for each catalogue line a separate transaction is executed. In
detail, for each line one of the following action code is specified:
o
ADD, for adding a catalogue line to the specified catalogue;
o
DELETE, for removing a catalogue line from the specified catalogue;
o
UPDATE, for updating a catalogue line from the specified catalogue;
The transactions are managed by spring when the method saveAndVersionCatalogueLine() of
the ImportCatalogueService class is called.
When the transactions are executed the ImportCatalogueService coordinates the calls to methods
of specialized handlers which contain fine-grained logic. For the Import of the catalogue we have
different handlers playing different roles:
 CatalogueHandler: contains the business logic to create or update the catalogue entity;
 VersioningHandler: contains the business logic to version the catalogue and its catalogue
lines;
 PartyHandler: contains the business logic to save and update the parties and link them to the
catalogues/catalogue lines;
 ItemHandler: contains the business logic to save and update the catalogue lines.
The handlers interact with the classes responsible for performing the atomic operations on the
database. These classes belong to the underlying layer called Data Access Layer described
below.
4.1.1.3. Submit Catalogue in the Data Access Layer
As described in 3.2, the Data Access Layer is composed of the following two main components:
 Data Access Object (DAO) [REF2]
 Entity [REF3]
An entity is a lightweight persistent domain object. Each entity represents a table in a relational
database, and each entity instance corresponds to a row in that table.
In addition to the entities, each table has a DAO class linked to it. Each of these DAO classes
extends a generic DAO class called JpaDAO. The JpaDAO implements the DAO interface using
Jpa and spring technology. The DAO exposes the following methods for performing atomic
operations on the database:
 persist(): persists the entity
 delete(): deletes an existing entity
 findByPk(): finds an entity based on the primary key passed as parameter
 findAll(): finds all the entities stored in the database
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 13 / 17
4.1.2. The End-User consults the information concerning the Catalogue
When the end user wants to consult the catalogue information, he must log into the system using
the web application provided by the CCMS presentation layer. Once the user rights have been
verified, the web application provides the following features:
 Search Catalogue: the user can retrieve catalogues specifying the following search
parameters:
o
Catalogue ID
o
Catalogue Version
o
Framework Contract
o
Lifecycle status
 View Catalogue: once the user identifies the catalogue, the following details are provided:
o
Customer header information
o
Supplier header information
o
Catalogue line classification information
o
Catalogue line details information
Below are some sample screens referring to the information described above:
Figure 7: Search Catalogue Screen
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 14 / 17
Figure 8: Catalogue Details Screen
Figure 9: Item Details Screen
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 15 / 17
4.1.2.1. View Catalogue in the Presentation Layer
The presentation layer handles the user's search requests and shows the required Catalogue
information.
Authentication is required for the user, who has to provide a username and a password before
using the CCMS functionalities. Credentials are checked using the services provided by the
Security Layer of the architecture.
The web pages of the application use DOJO [REF8] JavaScript [REF9] libraries and requests are
handled using the Spring MVC (Model, View, Controller) framework [REF10].
The Controllers validates the request coming from the View and transforms it into a format
ready to be passed to the underlying Business Layer. The transformed request is then submitted
to the Façade tier of the Business Layer and, when the response is received, data is transformed
back into a format ready to be shown by the View.
Three main controller classes are used by the application to handle the requests for the view
catalogue use case:
 SearchCatalogueController: this controller is used when the user search for a catalogue
providing the search parameters via the web interface;
 ViewCatalogueController: this controller is in charge of getting the Catalogue Details by
calling the services of the Business Layer, when the user selects a Catalogue to consult
from the list of the available ones;
 CatalogueItemDetailsController: this controller is called when a user selects an item from
the catalogue lines list of a specified Catalogue.
4.1.2.2. View Catalogue in the Business Layer
The CatalogueFacade class exposes an interface for both searching catalogues (based on search
parameters) and fetching the details of a specific catalogue (based on its primary key). The
CatalogueFacade class exposes the following tree methods:
 findCatalogues(): orchestrates the calls to the service tier in order to find the catalogue
information according to the provided parameters;
 getCatalogueSynopsis(): orchestrates the calls to the service tier in order to find the catalogue
synopsis information. The catalogue synopsis contains all the catalogue information except
for the information concerning the catalogue lines;
 getItemDetails(): orchestrates the calls to the service tier in order to find the catalogue line
information.
The CatalogueQueryService coordinates the calls to the methods of the handlers containing a
more fine-grained logic used to fetch the information linked to the catalogues and catalogue
lines. The CatalogueQueryService interatcs with the following handlers:
 CatalogueQueryHandler: contains the business logic to fetch the information concerning the
catalogue entities;
 ItemQueryHandler: contains the business logic for fetching the information concerning the
catalogue lines entities.
The handlers interact with the classes responsible for executing atomic queries on the database.
These classes belong to the Data Access Layer described in 4.1.1.3.
Central Catalogue Management System Software Architecture Document –
Document Version 1.0 dated 13/02/2016
Page 16 / 17