Introduction This document covers the following: Brief description of the project, context, business goals, and constraints for the system being developed. Requirements and prioritized utility tree. Architecture presented by various architectural viewtypes. Architecture trade-off analysis based on architectural alternatives. This document is intended for the following audience: Stakeholders of the ZEN Tool Project: client, mentors, and development team. Those who want to understand the architecture of the ZEN Tool. Every image with the icon represents an image which maps to other architectural views. [edit] Project Overview [edit] ZEN Tool The ZEN Tool Project is sponsored by the Integration of Software Intensive Systems (ISIS) initiative at the Software Engineering Institute (SEI). The intention of the project is to automate a portion of the Service Migration and Reuse Technique (SMART) that helps organizations analyze legacy systems to determine whether their functionality, or subsets of it, can be reasonably exposed as services in a Service- Oriented Architecture (SOA). The portion that needs to be automated is the data collection process guided by the Service
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Introduction
This document covers the following:
Brief description of the project, context, business goals, and constraints for
the system being developed.
Requirements and prioritized utility tree.
Architecture presented by various architectural viewtypes.
Architecture trade-off analysis based on architectural alternatives.
This document is intended for the following audience:
Stakeholders of the ZEN Tool Project: client, mentors, and development
team.
Those who want to understand the architecture of the ZEN Tool.
Every image with the icon represents an image which maps to other architectural
views.
[edit] Project Overview
[edit] ZEN Tool
The ZEN Tool Project is sponsored by the Integration of Software Intensive Systems
(ISIS) initiative at the Software Engineering Institute (SEI). The intention of the
project is to automate a portion of the Service Migration and Reuse Technique
(SMART) that helps organizations analyze legacy systems to determine whether
their functionality, or subsets of it, can be reasonably exposed as services in a
Service-Oriented Architecture (SOA). The portion that needs to be automated is the
data collection process guided by the Service Migration Interview Guide (SMIG).
The process is currently manual and time-consuming. With the tool support, SEI
expects to see some fundamental improvement on efficiency and quality when they
conduct SMART engagements.
[edit] Business Goals
Author's note: this set of goals was used for quality attribute workshop.
Sign In SMART Member needs to sign in the system before performing any other operations.
Sign Out SMART Member can sign out from the system during any give time.
Acquire Engagement Data
Prior to any interview phases of a given engagement, the interviewer obtains a copy of the engagement setup data prepared in the Setup Engagement Data use case.
Choose Question
During an interview, the interviewer chooses a question in the system as the focus of the discussion. The interviewer browses through the categories of topics, and from which a desired question is located. To quickly locate a question, the interviewer can enter keywords and instruct the system to search the matching questions. The interviewer can also follow a predefined sequence of questions that facilitates a smoother interview session.
Record Answer
During an interview, the interviewer records annotations to a selected question. The possible types of annotations include predefined answers, comments, and tags. One possible predefined answer can be "not-applicable". For the purpose of status, a question is considered to be "answered" if one of two mutually exclusive conditions are met. First, if there are one or more predefined answers associated with a particular question, then the question is considered to be "answered" if and only if at least one of the predefined answers has been selected or a comment has been entered. Second, if there are no predefined answers associated with a particular question, then the question is considered to be "answered" if and only if there is a comment entered for that question. A question may be annotated with one or more tags, but applying tags has no effect on the question's "answered" status. The purpose of the tags is for generating templates (Authors' note: Should we distinguish answer from annotation?)
Consolidate Interview Data
After each interview phase of a given engagement, the interviewers submit their individual interview data for consolidation. Each interviewer associated with a specific engagement is expected to upload the data they took, however this is not mandated. Once at least two sets of data has been submitted, anyone of the interviewers can explicitly trigger the consolidation. This consolidated interview data can then be obtained by the interviewers.
Generate Report
This use case applies to two circumstances: First, during an engagement, the analyst instructs the system to generate reports based on interview data collected so far. The analyst first chooses a report type, such as Current SMIG or Migration issues table, and then the system generates the report. Second, in between engagements, the analyst instructs the system to generate reports based on historical engagements. The analyst selects one report type, such as Draft of final report or List of questions per tag, and then the system generates the report accordingly.
Generate Template
Analyst generates two kinds of templates: service table or component table. The format of the templates must be editable. The preferred format is xls but csv is also acceptable. The system is given the templates that are used during interview, and then the system adds new columns to them. The columns are the short names of questions marked with specific tags.
Setup Engagement Data
Administrator prepares an engagement by entering information obtained prior to an engagement. The information includes the engagement client organization, type of system under evaluation, profiles of interviewees, the version of the SMIG which will be used, and the set of tags that will be used.
Update SMIG Information
Administrator updates SMIG information. It includes the basic create, read, modify and delete operations. The administrator can also promote the updated SMIG into a new version. The system has to keep the old versions of SMIG in order to maintain data consistency for old engagement data.
Update Tag List Administrator updates the default tag list, which is used during Setup Engagement Data. It includes the basic create, read, modify, and delete operations.
Register User Account
Administrator registers user account, which can be used in the Sign In use case. Additionally, administrator can modify, delete and reset user account.
[edit] Quality Attributes
The following quality attributes, represented with the utility tree, drive the design of
architecture.
The quality attribute scenarios in a six-part format can be found in Six-Part Quality
Attribute Scenarios section.
This table is derived from quality attribute scenarios.
Each quality attribute scenario is ranked with importance (I) defined by the client,
and estimated level of difficulty (D). Both values are based on a scale of high(H)-
medium(M)-low(L).
Color scheme:
← Red: High importance scenarios with high level of difficulty.
← Yellow: High importance scenarios with low to medium level of difficulty.
Attributes Concerns Scenario# Description
Rank
(I, D)
Reliability Data integrity #1
At the end of an interview day, the system generates a consolidated report based on the input data of three team members that shows the risk factors that reflect correctly what was captured.
(H, L)
Usability Smartness #2 When a report is generated, then the report includes risks based on historical data.
Modifiability Flexibility #3 When Dennis, a non-technical person, generates a report, he can specify the information printed within 10 minutes.
(M, M)
Usability Input correctness
#4
Entering New SMIG information (offline)
← Question
← Answers
← Risk factor
← Recommendation
← Related questions
← Category
can be entered consistently and that the tool provides
hints when inconsistent inputs are received. The
process should be termed complete only when all
inconsistencies have been resolved.
(H, M)
Usability User's mental model
#5 When entering a new thought-about SMIG question, Dennis will find and enter the question in the right place in not more than 5 minutes.
(M, H)
Usability Navigation #6
Client provides information not related to current question, the person using the tool will navigate to the related topic within 15 seconds and then be able to return to the previous question with one push of button.
(H, L)
Modifiability Flexibility #7 A developer is able to add the generation of the migration issue template within 1 person-week effort.
(H, M)
Modifiability Flexibility #8 A developer will be able to add a new risk analysis capability reflected in report with only changing 1 component.
(M, H)
Modifiability Flexibility #9 A developer will be able to add new fields specific to a question or an engagement via modifications to the GUI within 2 person-days per field.
(M, H)
Modifiability Flexibility #10 A developer will be able to create new specified report type within 5 person-days
(H, M)
Security Integrity of SMART process
#11 Unauthorized access to the application, and all these attempt are recognized and denied.
(H, M)
Security Integrity of SMART process
#12 Unauthorized access to the data in to database and all such attempts are recognized and denied.
(H, M)
Security Integrity of SMART process
#13 Eavesdropping on any communications is not possible based on current technical standard.
(H, L)
Performance UI Response Time
#14 During the interview, the status will be updated within 1 second of a change occurring.
(H, L)
Availability Robustness #15 During an interview, the interview module will be available at 99.9%.
(M, H)
Availability Downtime #16 In the event of a system crashes, the application will return to former state within 30 seconds from application start.
(H, H)
Usability Intuitiveness #17 While entering information to a question, this question can be tagged with multiple tags in less then 1 second per tag
(H, L)
[edit] Six-Part Quality Attribute Scenarios
Quality Attribute Scenario #4
Stimulus: Administrator enters new SMIG information
Source of Stimulus:
Administrator
Environment: At runtime
Artifact: ZEN Server
Responses: New SMIG information can be entered consistently and that the tool provides hints when inconsistent inputs are received. The process should be termed complete only when all inconsistencies have been resolved.
Response Measure:
Inconsistent inputs are rejected with hints showing where the inconsistency is.
Quality Attribute Scenario #6
Stimulus: Client (interviewee) provides information not related to current question
ZEN Client ZEN Client is a standalone application that can be used during an interview. ZEN Client can operate in an environment without network access.
ZEN Server
ZEN Server is a standalone application that keeps track of all SMART engagements.
[edit] Allocation Architectural Viewtype
[edit] ZEN Tool Physical Deployment View
This view shows the physical elements of the ZEN Tool system and how they
ZEN Server This is the physical server located at the SEI. It receives connections from multiple offsite Zen Client machines via a VPN connection. The communication can be either a direct data transfer or a web browser-based transfer.
ZEN Client Computer
This is the physical laptop in use at the SEI and at client locations. It can communicate with the ZEN Server. When at a client location, it does so in a direct data transfer or a
This is the physical server located at the SEI. It contains a web server which contains the ZEN Server software component. It also contains a MySQL database.
Web Server This is the web server software component. It contains the ZEN Server and provides remote access to it.
ZEN Server This is the ZEN Server software component. It performs all of the critical repository functionality.
MySQL Database
This is the primary data repository for the ZEN Server. It contains all of the engagement information and all of the SMIG information.
Rationale
The ZEN Server is partitioned into these components due to the following:
Business Constraint: SMART Engagements involve SEI personnel traveling to
client locations and performing interviews. Data taken in these engagements
must be consolidated into a central repository. Thus to support a client-server
Business Constraint: The SMART team has no budget for professional
database software. Therefore the database choice must be free.
Quality Attribute: To promote modifiability, a database with complaint JDBC
drivers, such as MySQL, is used because it is common and well-documented.
[edit] ZEN Client Deployment View
This view shows the primary components of the ZEN Client. It includes the Zen
Client software component and a database being used as the primary local
repository.
Element Catalog
Element Description
ZEN Client Machine
This is the physical laptop used by SMART personnel to perform engagements. It can be used both at the SEI (without VPN access) and at client locations, using a VPN connection to communicate with the ZEN Server. It contains both the ZEN Client software component and a database.
ZEN Client This is the ZEN Client software component. It performs all of the critical interview functionality.
Database This is the primary data repository for the ZEN Client. It contains sets of Engagement data.
Rationale
The ZEN Server is partitioned into these components due to the following:
Personal Laptop One or more laptops installed with ZEN Client communicate with the Central Server through HTTPS protocol.
Eclipse RCP Eclipse Rich Client Platform (RCP) provides the runtime environment for ZEN Client.
ZEN Client In this view, ZEN Client is more precisely defined as a plugin deployed inside Eclipse RCP. The binaries of ZEN Client have to be obfuscated to prevent reverse engineering.
Embedded This is an optional plugin that is intended to be the default database for ZEN Client.
Database See ZEN Client Data Store for the trade-off analysis.
Eclipse BIRT Eclipse BIRT is a reporting engine that can be used as a set of plugins in Eclipse RCP and a servlet in JBoss Web (Tomcat). Eclipse BIRT handles directly the JDBC connections.
External Database
ZEN Client can be configured to use an External Database with a compliant JDBC driver.
Central Server Central Server is located inside SEI. It has been specified that the server will run on Windows XP, but in fact, the deployment applies to any OS with a standard JDK/JRE.
Apache HTTP Server
The most popular web server. It communicates with JBoss Web using the Apache JServ Protocol (AJP).
MySQL The most popular open source database.
JBoss Application Server
JBoss Application Server is a J2EE 1.4 compliant application server.
JBoss JCA JCA stands for J2EE Connector Architecture. JBoss JCA is the implementation of JCA specification. The Data Source is deployed into JBoss using the JBoss JCA.
Data Source Data Source represents a JDBC data source that is available through a JNDI (Java Naming and Directory Interface) repository.
JBoss Naming Server
JBoss Naming Server (JBossNS) is implemented as a JNDI repository. ZEN Server looks up a JDBC data source from JBossNS.
JBoss Web (Tomcat)
JBoss Web is in fact an embedded Tomcat, a servlet container that ZEN Server is deployed into.
Struts 2 Struts 2 is a web application framework on which that ZEN Server is based. Its runtime behavior can be found in the ZEN Server With Struts 2 section.
ZEN Server In this view, ZEN Server is more precisely defined as a component (or a set of actions, interceptors, etc.) that resides in Struts 2. Detail run-time behavior can be found in ZEN Server With Struts 2 section.
ZEN Server Directory Structure
The following is a list of packages that comprise the server:
← All packages ending with .test are test cases while others are described in the
individual Zen module pages.
← All .builder packages are related with building the source code
← All packages follow the Eclipse project conventions
[edit] Work Assignment View
Element Catalog
Component
Notes (Note: All components include UI, logic and data access wherever applicable)
Allen Marc Sajjad Session Somakala
ZEN Server
Authentication This component includes role based management aspects
×
SMIG Maintenance
Creating SMIG and exposing an interface to communication component for creating an XML structure of SMIG data
×
Reporting This includes report creation and report generation
× ×
Engagement Setup
Creating new engagement setup and exposing an interface to communication component for creating an XML structure of engagement setup data
×
Communication
This ensures secure ports listening for information. There should be a single point of entry
×
Consolidation This module consolidates the interview data from multiple users
×
Data Access Layer
This task involves ensuring that common tasks for database access like establishing connection etc. is provided as a utility. This task also involves verifying that the data model is normalized and does not have redundant information.
that the UI developed by all team members integrates well and it looks like one well developed UI
Installation and Configuration
This component is for installing the component and configuring it for use. Configuration should be available wherever applicable for later use during the lifetime of the tool
×
Administration Interface for creating roles, usernames and passwords on the server
×
ZEN Client
Authentication This component includes role based management aspects
This includes generating templates, component table and service table on the client. This is the Excel table (can be CSV)
×
Administration
Interface for connecting to server, downloading engagement setup, uploading interview data, downloading interview consolidated data
×
Communication
This ensures secure ports communicating with the server. There should be a single point of contact
×
Data Access Layer
This task involves ensuring that common tasks for database access like establishing connection etc. is provided as a utility. This task also involves verifying that the data model is normalized and does not have redundant information.
×
UI Layer
This task involves ensuring that the UI developed by all team members integrates well and it looks like one well developed UI
×
Installation and Configuration
This component is for installing the component and configuring it for use. Configuration should be available wherever applicable for later use during the lifetime of the tool
×
[edit] Module Architectural Viewtype
[edit] ZEN Tool Decomposition View
ZEN Tool is composed of two major modules: ZEN Client and ZEN Server.
Key: UML
Element Catalog
Element Description
edu.cmu.sei.smart.zen The module represents the ZEN Tool.
edu.cmu.sei.smart.zen.client The module represents the ZEN Client, which is a standalone GUI application.
edu.cmu.sei.smart.zen.server The module represents the ZEN Server, which is a centralize server.
The ZEN Tool is composed of the a number of modules illustrated below.
NB: For both the client and server, two modules (more accurately, tasks) are not
shown:
The UI module, which consists of harmonizing the UI across multiple modules
on the client or server.
The installation and configuration task, that involves deploying the system to
the SEI environment.
NB: The ZEN Client Administration module currently only consists of the
synchronization of data between the client and the server, but in the future it may
take on added functionalities.
Element Catalog
Component
Notes (Note: All components include UI, logic and data access wherever applicable)
Allen Marc Sajjad Session Somakala
ZEN Server
Authentication This component includes role based management aspects
×
SMIG Maintenance
Creating SMIG and exposing an interface to communication component for creating an XML structure of SMIG data
×
Reporting This includes report creation and report generation
× ×
Engagement Setup
Creating new engagement setup and exposing an interface to communication component for creating an XML structure of engagement setup data
×
Communication
This ensures secure ports listening for information. There should be a single point of entry
×
Consolidation This module consolidates the interview data from multiple users
×
Data Access Layer
This task involves ensuring that common tasks for database access like establishing connection etc. is provided as a utility. This task also involves verifying that the data model is normalized and does not have redundant information.
×
UI Layer
This task involves ensuring that the UI developed by all team members integrates well and it looks like one well developed UI
×
Installation and Configuration
This component is for installing the component and configuring it for use.
This includes generating templates, component table and service table on the client. This is the Excel table (can be CSV)
×
Administration
Interface for connecting to server, downloading engagement setup, uploading interview data, downloading interview consolidated data
×
Communication
This ensures secure ports communicating with the server. There should be a single point of contact
×
Data Access Layer
This task involves ensuring that common tasks for database access like establishing connection etc. is provided as a utility. This task also involves verifying that the data model is normalized and does not have redundant information.
×
UI Layer
This task involves ensuring that the UI developed by all team members integrates well and it looks like one well developed UI
×
Installation and Configuration
This component is for installing the component and configuring it for use. Configuration should be available wherever applicable for later use during the lifetime of the tool
×
[edit] ZEN Server Layered View
This view shows the ZEN Server in a layered style.
It depicts three key architectural properties:
1. Higher-level layers are allowed to use any lower-level layers, but not the
reverse.
2. Higher-level layers depend on the services provided by the lower-level layers.
3. Higher-level layers may hide certainly functionalities in the lower-level layers,
ZEN Server ZEN Server represents the web application layer that is based on JBoss Application Server.
JBoss Application Server
JBoss Application Server is a J2EE 1.4 compliant application server, but only the following modules will be used by the ZEN Server.
JBoss JMX JMX stands for Java Management Extension. JBoss JMX is the implementation of JMX specification. All the services in JBoss, such as JBoss Web and JBoss JCA are implemented as ManagedBean (MBean) that can be added to the JMX kernel.
JBoss JCA JCA stands for J2EE Connector Architecture. JBoss JCA is the implementation of JCA specification. The Data Source is deployed into JBoss using the JBoss JCA.
Data Source Data Source represents a JDBC data source that is available through a JNDI (Java Naming and Directory Interface) repository. JBoss has a bounded JNDI implementation, which is not shown in the view.
JBoss Web JBoss Web is in fact the Tomcat wrapped as a MBean. It's a servlet container that ZEN Server is deployed into.
Struts 2 Struts 2 is a web application framework that ZEN Server is based on. Its runtime behavior can be found in the ZEN Server With Struts 2 section.
JVM The Java Virtual Machine layer provides the Java Runtime Environment for the ZEN Client to run.
OS The Operation System layer provides the memory management, file I/O and other functionalities that are essential for the ZEN Client to run.
[edit] ZEN Client Layered View
This view shows the ZEN Client in a layered style.
It depicts three key architectural properties:
1. Higher-level layers are allowed to use any lower-level layers, but not the
reverse.
2. Higher-level layers depend on the services provided by the lower-level layers.
3. Higher-level layers may hide certainly functionalities in the lower-level layers,
ZEN Client ZEN Client represents the rich client application layer that is based on Eclipse Rich Client Platform.
Eclipse Rich Client Platform
ZEN Client relies heavily on Eclipse Rich Client Platform. It extends the Generic Workbench to provide the views, editors and perspectives as described in the ZEN Client UI Decomposition View section.
Generic Workbench
The Generic Workbench manages the editors, views and perspectives. It provides the selection service for transmitting events between views and editors. One example of its runtime behavior can be found in the ZEN Client Interview Perspective section.
SWT SWT stands for the Standard Widget Toolkit. ZEN Client uses SWT to construct the user interface.
JFace JFace is a UI toolkit for handling common UI programming tasks. It is designed to work with SWT without hiding it. ZEN Client uses its data binding framework to decouple model from UI presentation.
Optional Plug-ins
Optional plug-ins such as help and update can be added to ZEN Client with ease.
Platform Runtime
The Eclipse's core platform runtime module provides the fundamental functionalities for the rich client application to run.
Equinox OSGi The Eclipse Equinox implements the OSGi R4 Framework.
JVM The Java Virtual Machine layer provides the Java Runtime Environment for the ZEN Client to run.
OS The Operation System layer provides the memory management, file I/O and other functionalities that are essential for the ZEN Client to run.
ZEN Server Decomposition View
The decomposition view represented here is the highest level of decomposition of
functionality of the ZEN server. The different functions have been grouped together
based on the activity they perform.
Key: UML
Element Catalog
Element Responsibilities
Authentication Authentication is responsible for verifying that the user or application accessing the server is a valid user of the system.
SMIG Maintenance
This process is responsible for modifications to the SMIG by supporting the following
Adding a question to the SMIG (and answers, risks, mitigation strategies)
Modifying an existing SMIG question (and answers, risks, mitigation
This process is responsible for creating the initial data setup for a particular engagement. This includes
Enter preliminary information about the engagement
Enter tags to be used for the engagement
Allow the user to download SMIG data for that engagement
Allow the user to download tag data for that engagement
Allow the user to download setup data for that engagement
Reporting This process is responsible for allowing the user to view reports on a browser. (TBD: And what else?)
Consolidation This process is responsible for consolidating the interview data across the interviewers per each engagement. This process will allow the user to upload the interview data and download the consolidated interview data.
Communication This process is responsible for communication between any outside component with the ZEN server. The outside component includes the ZEN client and browser access. This process must provide secure communication.
[edit] ZEN Server Reporting Decomposition View
The decomposition view splits reporting into two main functionalities, one for viewing
the reports (report generation) and the other for creating new reports (report
customization). Report generation and report customization use the Model-View-
Controller (MVC) pattern. This pattern allows us to separate the presentation layer
Report generation is used for generating reports and rendering it on the browser. This will use the MVC pattern. The functionality which needed to be provided for reports are
Filtering the data based on queries
Sorting (TBD)
Exporting to PDF and HTML (TBD)
Printing data
Report Customization
This process can be used to customize reports (TBD)
[edit] ZEN Server JSP Decomposition View
This view enumerates all the JSP pages.
See ZEN Server With Struts 2 for its runtime behavior.
Index.jsp This is the default page that is displayed to users who enter the web site's URL; it provides an authentication form with username and password fields for users to enter.
Main_Menu.jsp This is the main menu of functionalities that a user can choose from depending on the role he is authenticated in.
Error_Page.jsp This is a dynamically generated page that gives feedback to the
user about improper or inconsistent information entry (i.e. bad username or password), or server processing error.
Generate_Report.jsp
This page provides the user with a list of engagements to choose from, and a list of reports to generate for the chosen engagement. Note that only one type of report is generated at a time.
Report.jsp This is the resulting report generated by the server and displayed to the user, who can then print it from his browser.
Manage_SMIG.jsp
This page lists out all of the SMIG questions, and allows the user to choose to:
← add additional ones (which directs them to
Add_SMIG_Question.jsp).
← edit existing ones (which directs them to
Edit_SMIG_Question.jsp).
← mark a question as inactive for a particular version of the
SMIG.
← reactivate a question that was inactive for a particular
version of the SMIG.
Add_SMIG_Question.jsp
This page provides the following fields to add a new question:
← the SMIG version in which the question should be
activated.
← the text of the question.
← potential answers for the question with their associated
risks. Additional answers can be added or existing ones can
be removed.
← a multi-choice selection list of existing questions to which
the new one will be related.
The question ID will be automatically generated by the server.
The user will be returned to Manage_SMIG.jsp, and the
confirmation of the addition will be displayed on that page.
Edit_SMIG_Question.jsp This page provides the following fields to edit an existing
question:
← the SMIG version in which the question should be
activated.
← the text of the question.
← potential answers for the question with their associated
risks. Additional answers can be added or existing ones can
be removed.
← a multi-choice selection list of existing questions to which
the new one will be related.
The user will be returned to Manage_SMIG.jsp, and the
confirmation of the edits will be displayed on that page.
Manage_Engagement.jsp
This page lists out all of the engagements, and allows the user to choose to:
← add additional ones (which directs them to
Add_Engagement.jsp).
← edit existing ones (which directs them to
Edit_Engagement.jsp).
← delete existing ones (which directs them to
Delete_Engagement_Confirmation.jsp).
Add_Engagement.jsp This page provides the following fields to add a new engagement:
← engagement title.
← engagement description.
← the SMIG version associated with the engagement.
← customized tags associated with the engagement.
Additional tags can be added or existing ones can be
removed.
← a multi-choice selection list of current users that will
participate in the given engagement.
The engagement ID will be automatically generated by the
server, and the engagement's creation date and creator will be
deduced by the server as well.
The user will be returned to Manage_Enagement.jsp, and the
confirmation of the addition will be displayed on that page.
Edit_Engagement.jsp
This page provides the following fields to edit an existing engagement:
← engagement title.
← engagement description.
← the SMIG version associated with the engagement.
← customized tags associated with the engagement.
Additional tags can be added or existing ones can be
removed.
← a multi-choice selection list of current users that will
participate in the given engagement.
The user will be returned to Manage_Enagement.jsp, and the
confirmation of the edits will be displayed on that page.
Delete_Engagement_Confirmation.jsp
This page asks the user to confirm his choice to delete the selected engagement. Because an engagement, unlike a tag, consists of many pieces of data, and it is an important part of the interview process, the user must really be sure that he wants to delete one.
Manage_Users.jsp
This page displays all of the users of the ZEN Server and allows an administrator to:
← add users
← remove users
← change the information of a user (name, type, ...)
← reset the password of a user
Manage_Tags.jsp
This page displays all of the default tags and allows a user to:
← add more tags one at a time.
← select a single tag and edit it.
← select one to many tags and remove them.
The confirmation of the addition, edits, or removals will be
displayed on this page.
Consolidate_Interview_Data.jsp
This page displays all of the engagements and the users who have uploaded their interview reports for a particular engagement, and it allows the user to select an engagement with more than one interview report to consolidate all of them.
Download_Consolidated_Data.jsp This page displays that the consolidation process was successful and gives the user the ability to download the resulting consolidated report.
Download_ZEN_Client.jsp This page allows the user to download the ZEN Client tool onto his computer.
ZEN Client Decomposition View
The decomposition view represented here is the highest level of decomposition of
functionality of the ZEN client. The different functions have been grouped together
based on the activity they perform.
Key: UML
Element Catalog
Element Responsibilities
Authentication Authentication is responsible for verifying that the user or application accessing the server is a valid user of the system.
Interview This process is responsible for allowing the user to interview and capture data.
This process generates a file (Microsoft Excel or CSV (TBD)) which will create the Service and Component Tables with default columns initially. When columns are tagged to be added to the template files, this process will be run by the user again. The original data will be retained and the new columns will be appended wherever applicable.
Reporting
Reporting on the ZEN client involves on report generation. Report generation is used for generating reports and rendering it on the client. The functionality which needed to be provided for reports are
Filtering the data based on queries
Sorting (TBD)
Exporting to PDF and HTML (TBD)
Printing data
Communication
This process is responsible for connecting to the server and uploading and downloading data. This includes
Downloading engagement setup data
Uploading interview data
Downloading consolidated data
Download system updates (TBD: For now this includes newly created reports)
[edit] ZEN Client Interview Decomposition View
The decomposition view represents the decomposition of the interview process of
the ZEN client. The different functions have been grouped together based on the
Answer The UI process gets the answer from the user. This will follow the MVC pattern
Tag This process captures user's tag updates. This will follow the MVC pattern
Comment The process captures comment information stored by the user. This will follow the MVC pattern
Status The status of the answers which have been completed so far will be displayed to the user. This will follow the MVC pattern
[edit] ZEN Client Communication Decomposition View
Provide a rationale as to why a particular pattern, or the given architectural
representation is used.
Key: UML
Element Catalog
Element Responsibilities
Communication
This process is responsible for allowing the ZEN client to communicate with the ZEN server and transfer data. This data includes
← Engagement setup data
← Interview data
← Consolidated interview data
Engagement Setup Download
This process is responsible for downloading the engagment setup data from the server
Interview Data Upload Download
This process is responsible for uploading interview data from the Zen client to the ZEN server and downloading the consolidated interview data from the ZEN server
Workbench The Workbench class is responsible for creating, managing and navigating its workspace resources, which include perspectives, views and editors. This class is part of the Eclipse RCP.
InterviewPerspective This InterviewPerspective class represents the initial user interface layout designed for the Interview Module in the Controller Layer.
AnalysisPerspective This class represents the initial user interface layout designed for the Report Module in the Controller Layer.
SynchronizationPerspective This class represents the initial user interface layout designed for the Synchronization Module in the Controller Layer.
SmigView
This class is responsible for displaying SMIG questions in a hierarchical way. It also provides search feature to assist the Interviewer to find a desired question quickly. The Interviewer selects a question and opens an AnswerEditor to record information.
AnswerEditor This class allows the Interviewer to record interview information, such as answer choices, comments and tags.
TagsView This class is responsible for displaying the tags. The state of checked tags changes according to what question is selected in the SmigView and in the editor area.
RiskView This class is responsible for displaying the associated risks to a selected answer choices in the AnswerEditor.
StatusView This class is responsible for showing the interview status. It displays the progress of each SMIG category.
TemplateView This class is responsible for displaying available report templates for the Analyst to choose from.
ReportEditor
This class is responsible for producing report according to the chosen template and the collected interview information. It uses the Ecliipse BIRT, an reporting engine chosen according the rationale documented in the Architecture Trade-off Analysis section.
EngagementView This class shows the locally available engagements. See Issues section for issues related to this class.
MessageConsole This class shows the communication between ZEN Client and ZEN Server.
ZEN Tool Data Model
This diagram shows how different data entities relate to each other.
Represents a state where client data for the subject engagement has been submitted by one or more client(s). Stored assumes that the engagement has been downloaded.
8 CLOSED_WITHOUT_DOWNLOADING Represents a state where a "new" engagement has been closed i.e. it was NOT downloaded or stored prior to closure.
10 CLOSED_AFTER_DOWNLOADING Represents a state where an engagement has been closed after it was DOWNLOADED by one or more clients.
14 CLOSED_AFTER_STORING Represents a state where an engagement has been closed after it was STORED by one or more clients.
SelectionService SelectionService is part of the Eclipse RCP. It acts as an event bus that propagates events between view and editor objects.
Views/Editors Views provide users with a graphical representation of data and editors allow users to interact with that data.
Adapter Factories Adapter Factories are objects that link views and editors to the data access objects on which they depend to display and edit data for the user.
JFace Actions JFace Actions are the actions to be implemented to link ZEN client functionalities with services offered on the ZEN server.
Data Access Objects
Data Access Objects extract data out of the database, based on the specific command which is received. For example, download engagement setup would result in engagement data being extracted. On the other hand download consolidated data would return the user's data along with the consolidated data of all other users.
BIRT Reporting Engine
The Eclipse BIRT reporting engine generates the report display by contacting the database and using the report template file (*.rptdesign) for generating the report.
Report Templates (*.rptdesign)
These are the report design files which contain details about the report structure, namely what columns to show and how, the tables they communicate with in the database, database connection details (password is encrypted) and other presentation related details. It has an XML structure. (TBD: See how database communication details can be overriden with application's data).
Data This is the data store that holds the data of the ZEN Tool. This will be accessed via a JDBC connector.
XML-RPC over HTTPS
XML-RPC is a specification written to address sharing XML data irrespective of the operating system or the environment. Using HTTPS ensures secured communication between ZEN Client and ZEN Server.
Browser This is a standard web browser.
Https Secure connection over port 443.
Tomcat Request Dispatcher
The Request Dispatcher parses and executes http requests containing servlet commands. It determines which requests should be handled by the BIRT reporting engine and which ones should be sent to the Struts 2 actions.
Struts 2 FilterDispatcher
The Filter Dispatcher determines whether a request should invoke an action, and delegates control to the appropriate action if required.
Java Server Pages The JSP pages displayed to the browser upon authentication and authorization.
Struts 2 Actions The Actions are user-defined objects that implement the functionalities that are to be expressed. They may access database through the Data Access Object.
Business Objects These Business Objects are implemented as POJOs (Plain Old Java Objects), which can be invoked by the XML-RPC over HTTPS .
Client CPU Computer The client CPUs run the ZEN Client and communicate with the ZEN Server to accomplish a number of server specific tasks.
Browser Browser Browsers communicate with the ZEN Server to accomplish a number of tasks.
Firewall Application The Firewall filters incoming traffic to the applications and databases residing on the server, in order a higher level of network security.
Tomcat Web Server
Web Server Tomcat is a servlet filter container that processes JSP tag commands from client or web page requests, and displays the result of those requests to the client or browser.
Tomcat Components
Web Server components
Contains a number of modules (servlets) provided by Tomcat, and that will be used to communicate with the Struts 2 Server.
Struts 2 Application Server
Struts 2 contains the ZEN Server functional components and processes requests that require an action to be executed (this may involve the database).
Database Database The database is a repository of all of the ZEN Server data.
[edit] ZEN Server With Struts 2
This view shows the runtime behavior of Struts 2, a web application framework that
The browser submits the following requests to the server:
Interview consolidation requests to merge all of the
interview data for a given engagement.
Requests for engagement reports.
Modification requests for the SMIG.
Modification requests for tags.
Download requests for data.
Setup requests for new engagements.
SEI Firewall Application The Firewall filters incoming traffic to the applications and databases residing on the server, in order a higher level of network security.
Tomcat Web Server Web Server Tomcat is a servlet filter container that processes JSP tag commands from web page requests, and displays the result of those requests to the browser.
Tomcat Components Web Server components
Contains a number of modules (servlets) provided by Tomcat, and that will be used to communicate with the Struts 2 Server.
Servlet filters Objects
The servlet filters parse and execute http requests containing servlet commands. These filters are optional. If the ActionContextCleanUp filter is present, the FilterDispatcher will not clean up the ThreadLocal ActionContext once the Result is returned. If the ActionContextCleanUp filter is not present, the FilterDispatcher will cleanup all ThreadLocals.
FilterDispatcher Object The FilterDispatcher checks the ActionMapper to determine whether a request should invoke an action, and delegates control to the ActionProxy if an action is require. This filter IS required.
web.xml File The web.xml file describes all necessary framework components for web deployment, including servlet filters. This is a required configuration file.
Struts 2 Application Server
Struts 2 contains the ZEN Server functional components and processes requests that require an action to be executed (this may involve the database).
ActionMapper Object The ActionMapper determines whether a request requires an action to be invoked.
ActionProxy Object The ActionProxy refers to the ConfigurationManager to
determine which ActionInvocation to create to process the action, and it creates that ActionInvocation object.
ConfigurationManager Object The ConfigurationManager uses the information from struts.xml to tie an ActionInvocation with the action that it handles.
struts.xml File The struts.xml file initializes the ConfigurationManager and contains result/view types, action mappings, interceptors, and so forth. This is an optional configuration file.
ActionInvocation Object
The ActionInvocation is responsible for the command pattern implementation of Struts 2, which includes invoking interceptors and actions, and looking up the proper report type to create based on an Action's result code (mapped in struts.xml).
Interceptors Objects
Interceptors apply common functionality to the requests before or after an Action is executed, like validation and file upload handling. Interceptors act like listeners on an event bus, and they are called as soon as an action to which they are associated is "fired". The number and type of interceptors to run can be set for each Action individually or across all of them.
Action Objects The Action is a user-defined class that implements the functionality that is to be expressed. It may access database through the Data Access Object.
Data Access Object Objects The Data Access Object is responsible for accessing database through JDBC connection. Modification to database must be transactional, i.e., it's either all or nothing.
Database Database The Database is the central repository of the ZEN Server Tool (including engagement data, SMIG version, interview reports, ...).
Result Object The Result is an (optional) object that is created after the Action executes, and returned to the browser. The Result may optionally use a rendering Template (JSP, FreeMarker, ...).
Template File The Template is a file that is used to describe how the Result data should be rendered.
[edit] ZEN Client Initial Configuration
This view shows the ZEN Client's runtime behavior during initial configuration.
The view depicts three key architectural properties:
1. To enforce security, a secret (Authentication Text) is stored instead of actual
password.
2. The call-return connectors represent function calls inside one JVM. There is
3. The security is implemented with random number generator (using
SecureRandom), cryptographic hash function (using MessageDigest) and
encryption/decryption (using Cipher).
The behavior information is expressed using a sequence diagram in the end of this
section.
Element Catalog
Element Description
ConfigurationDialog ConfigurationDialog allows the user to enter information during initial configuration. The information depicted here is focused on enabling the authentication process.
SecureRandom A secure random number generator. This is part of the JDK.
MessageDigest This object implements the one-way cryptographic hash function. Possible hash functions are SHA-256 and SHA-512. MD5 and SHA-1 are ruled out because of identified security flaw.
Cipher This object encrypts Authentication Text and Encryption Key #1 into the Encryption String by using Encryption Key #2.
AccountDAO AccountDAO is responsible for accessing the actual database table using JDBC.
AccountModel AccountModel stores the Username, Random Number and Encryption String in a database table.
[edit] Sequence Diagrams
The sequence of the initial configuration process is as follows:
← The user enters Username and Password through the
ConfigurationDialog.
← The Username is stored in plain text in the database.
← The system generates a Random Number and stores that number in the
database, associating it with the Username.
← The system now generates an encryption key (Encryption Key #2) using a 1-
way encryption algorithm based on the entered Password and the Random
Number associated with the Username. i.e., encryption_key =
Algorithm(password + random#)
← The system then takes the Encryption String (consisting of the
Authentication Key and the Encryption Key #1) and encrypts it using
Encryption Key #2.
← Finally, the system saves the encrypted Encryption String into the database,
This is the key generated from a 1-way encryption algorithm based upon the entered Password and the Random Number.
Encryption String
This is the concatenation of the Authentication Text and Encryption Key. The two elements are concatenated in plain text format, then the entire string is encrypted using Encryption Key #2.
[edit] ZEN Client Authentication
This view shows the ZEN Client's runtime behavior during authentication.
The view depicts three key architectural properties:
1. To enforce security, only the components that are required for performing
authentication are loaded into JVM.
2. The call-return connectors represent function calls inside one JVM. There is
no inter-process communication.
3. The security is implemented with cryptographic hash function and
encryption/decryption (using Cipher).
The Authentication module will compare user entered information with encrypted
keys stored in the database. The behavior information is expressed using a
Username This is the username the user uses to log into the ZEN Client. It is recorded in the database in plain text. It is initially created during installation, when the user selects login information.
Password This is the password the user uses to log into the ZEN Client. It is never recorded in the database, at all. However, it is used to create an encryption key which IS stored in the database (this will be explained later).
Random Number This is a random number, called the "Salt", which is associated with a particular username. It is stored in the database in plain text.
Authentication Text This is a text string which is stored in the database in an encrypted format. It is used to verify that the user has entered the correct password.
Challenge Authentication Text
This is the text extracted from Encryption String using Encryption Key #2'. It should match the original Authentication Text for a successful authentication.
Encryption Key #1' This is the key that is extracted from the Encryption String using the Encryption Key #2'.
Encryption Key #2' This is the key generated from one-way encryption algorithm based upon the entered Password and the Random Number retrieved from database.
Encryption String This is the Encryption String produced during initial configuration.
[edit] ZEN Client Interview Perspective
This architectural view shows the interaction between objects in the
InterviewPerspective of ZEN Client using an implicit invocation style.
The view depicts three key architectural properties:
1. The interaction between parts (the view and editor objects in Eclipse's term) is
decoupled by using the SelectionService, which is part of the Eclipse RCP.
2. The model is decoupled from view and editor objects by using the
ModelEventBus.
3. The view and editor objects do not directly access the model but through the
controller objects.
The behavior information is expressed using sequence diagrams in the end of this
section.
The related module decomposition view can be found in ZEN Client UI
SelectionService SelectionService is part of the Eclipse RCP. It acts as an event bus that propagates events between view and editor objects.
SmigView SmigView is responsible for displaying SMIG data model using a tree. It announces selection events to the event bus indicating which question is selected.
AnswerEditor
AnswerEditor is responsible for providing the answering form and accepting response information. It announces activation events indicating an AnswerEditor has been activated. NavigationHistoryAction listens to these events to keep track the navigation history. It's possible to have multiple instances of AnswerEditor opened at the same time.
StatusView StatusView is responsible for displaying the progress of an interview. (To be refined)
SmigFilter SmigFilter is responsible for matching questions to key words. The matching results are then presented in the SmigView.
NavigationHistoryAction
NavigationHistoryAction keeps track of the navigation history. This object directly addresses the quality attribute scenario #6: Client provides information not related to current question, the person using the tool will navigate to the relate topic within 15 seconds and then be able to return to the previous question with one push of button.
AnswerAction
This object listens to the selection events from SmigView. If a question, instead of a category, is selected, the action is enabled. It uses the ResponseDAO object to retrieve responses from the database. The information is then passed to the AnswerEditor. It also activates the AnswerEditor.
SmigAdaptorFactory This object hooks up the SmigView object with the SMIG data model. It uses the SmigDAO object to retrieve SMIG data model from the database.
StatusAdaptorFactory This object hooks up the StatusView object with the response data model. It uses the ResponseDAO object to retrieve data from database and construct the status data model for the StatusView.
SaveAction This object is responsible for saving information gathered by the AnswerEditor to the database. The actual database access is done by the ResponseDAO object.
SmigDAO SmigDAO is responsible for accessing the actual database table using JDBC.
ResponseDAO ResponseDAO is responsible for accessing the actual database table using JDBC. Modification to ResponseModel must be transactional, i.e., it's either all or nothing.
Cipher ResponseDAO uses Cipher object to encrypt/decrypt data before storing it into database.
ModelEventBus ModelEventBus is an event bus that propagates model change events from model to view and editor objects.
SmigModel SmigModel is a set of database tables that represent the SMIG data model.
ResponseModel ResponseModel is a set of database tables that represent the responses to the SMIG questions.
[edit] Sequence Diagrams
[edit] Browse and Search
The Browse and Search sequence diagram shows the behavior of Interviewer
SelectionService SelectionService is part of the Eclipse RCP. It acts as an event bus that propagates events between view and editor objects.
TemplateView TemplateView is responsible for displaying the reports available using a tree. It announces selection events to the event bus indicating which report is
ReportAction ReportAction listens to the selection events from TemplateView. If a report, instead of the report group, is selected, the action is enabled. It instantiates a ReportEditor and passes the associated report object.
TemplateAdapterFactory
TemplateAdapterFactory hooks up the TemplateView object with the list of reports available. It reads the report list file (in xml format) and extracts the report category and report user friendly name, and the actual report name and instantiates a TemplateView object.
ReportEditor
ReportEditor is the UI page on which the report is rendered. The editor initializes a browser window where the generated report is displayed. It retrieves the name of the report file (stored as a part of the report object) and calls the PreviewBirtAction. It is possible to have multiple instances of ReportEditor opened at the same time, enabling multiple reports to be open at a time.
PreviewBirtAction PreviewBirtAction instantiates Eclipse BIRT report viewer with the link to the report design file and the browser which is instantiated in ReportEditor.
BIRTWebViewer BIRTWebViewer is the Eclipse BIRT reporting engine which generates the report display by contacting the database and using the report template file (*.rptdesign) for generating the report.
Report Template (*.rptdesign)
This is the report design file which contains details about the report structure, namely what columns to show and how, the table it communicates to in the database, database connection details (password is encrypted) and other presentation related details. It has an XML structure. (TBD: See how database communication details can be overriden with application's data)
Report List (*.xml) This is the file which contains details about the list of reports, the names of the files on the file systems, the names which will be used during display and the category under which they are listed. It has an XML structure.
ZENToolModel ZENToolModel holds the entire data of the ZEN Tool on which reports have to be generated. This will be accessed via a JDBC connector.
[edit] Usage on client side and server side
The Eclipse BIRT engine allows reports to be generated using a browser. On the
client side, this browser is embedded within the Eclipse RCP and uses the HTML
server functionality provided by the Eclipse BIRT engine internally.
The advantage is that the same report template file (*.rptdesign) can be used on the
server side as well with the same functionality as provided on the client side. This is
assuming that data model between the client and server for common functionality
Eclipse Workbench manages the editors, views and perspectives. It provides the selection service for transmitting events between views and editors.
JFace Actions JFace Actions are the actions to be implemented to integrate the ZEN client functionality, specifically here, the synchronization tasks using the JFace library provided within Eclipse.
Tomcat Tomcat is a servlet filter container that processes HTTP/HTTPS commands from client or web page requests, and returns/displays the result of those requests to the client or browser. .
Business Objects
Business Objects are implemented as POJOs (Plain Old Java Objects), which can be invoked by the XML-RPC over HTTPS.
XML-RPC over HTTPS
XML-RPC is a specification written to address sharing XML data irrespective of the operating system or the environment. Using HTTPS ensures secured communication between ZEN Client and ZEN Server.
Data Access
Data Access extracts data out of the database, based on the specific command which is received. For example, download engagement setup would result in engagement data being extracted. On the other hand download consolidated data would return the user's data along with the consolidated data of all other users.
Data This is the data store that holds the data of the ZEN Tool. This will be accessed via a JDBC connector.
[edit] Architecture Trade-off Analysis
[edit] Rich Client Platform
ZEN Client, a standalone desktop GUI application, has been identified as
possessing many important quality attributes, such as usability, security, availability
and performance. To efficiently build the GUI application, a readily available
framework is preferred. Rich Client Platform (RCP) is the realization of such
framework for building desktop GUI application. There are two notable RCPs in the
market: NetBeans Platform and Eclipse RCP.
In deciding which one to adopt, an evaluation based on quality attributes is conducted with the
following outcome.
RCP Usability Security Availability Performance
Eclipse Both are able to support creating usable UI.
Both have no build-in features for security. (Supported by underlying JDK/JRE.)
Both are proven and stable solutions in the market.
Good with it's native SWT approach.
NetBeans Not as good; depending on the implementation of JRE.