Architecture - Client
From ZenWiki
Introduction
This document will cover the following information:
- 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.
Project Overview
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.
Business Goals
Author's note: this set of goals was used for quality attribute workshop.
- This tool should reduce the cost of SMART interviews in terms of time by at least one day.
- This tool should reduce the cost of SMART analysis (creating reports) in terms of time and effort by presenting the data in a useful and efficient way for the SEI personnel to use.
- This tool should improve the capability of the SEI to generate a SMART "Standard", which would improve market awareness of the technique, thus expanding the market of potential users for the SMART technique.
- This tool should improve the market's reception of the SMART technique via improving the market's perception of the technique's formality.
Business Context
This view defines the context of the system during normal operation and maintenance.
Related use cases can be found in Use Case View section.
Related quality attribute scenarios can be found in Quality Attributes section.
Constraints
The following constraints are applied to the design of the architecture.
- Java will be the language used. The advantage in writing the code in Java is portability. There is no dependency on the operating system, either during the development process or during deployment. Java has been chosen for the purpose of maintainability as well. The SEI staff is comfortable using Java. [SRS 6-1]
- The ZEN Tool will need to work on a Windows XP machine. [SRS 6-3]
- SMART Engagements involve SEI personnel traveling to client locations and performing interviews. Data taken in these engagements must be consolidated into a central repository.
- The SMART team has no budget for commercial software; any third-party software must be free.
- Connect to SEI requires using virtual private network (VPN).
Requirements Overview
Use Case View
The functional requirements are presented using a use case model.
Detail information can be found in Use Case Specification.
This use case model shows the allocation of requirement between roles (aka, actors).
The relation between roles is generalization. SMART Member is a generalization of Interview, Analyst and Administrator.
Key: UML
| Use Case Name | Description |
|---|---|
| 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. |
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. | (L, H) |
| 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)
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) |
Six-Part Quality Attribute Scenarios
| 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. |
| Stimulus: | Client (interviewee) provides information not related to current question |
|---|---|
| Source of Stimulus: | The person using the tool (interviewer) |
| Environment: | At runtime |
| Artifact: | ZEN Client |
| Responses: | Navigate to the related topic and then be able to return to the previous question |
| Response Measure: | Navigate to the related topic in 15 seconds; return to the previous question with one push of button |
| Stimulus: | A developer wishes to add the generation of the migration issue template |
|---|---|
| Source of Stimulus: | Developer |
| Environment: | At design time |
| Artifact: | Migration issue template |
| Responses: | Locates the migration issue template; makes modification; tests modification; deploys modification |
| Response Measure: | Within 1 person-week effort. |
| Stimulus: | A developer wishes to create new specified report type (template) |
|---|---|
| Source of Stimulus: | Developer |
| Environment: | At design time |
| Artifact: | Report type (template) |
| Responses: | Locates the report type (template); makes modification; tests modification; deploys modification |
| Response Measure: | Within 5 person-days |
| Stimulus: | Tries to access the application |
|---|---|
| Source of Stimulus: | Internal or external individual who are not authorized |
| Environment: | At runtime |
| Artifact: | ZEN Client and ZEN Server |
| Responses: | All these attempts are recognized (recorded) and denied |
| Response Measure: | TBD (Time/effort/resources required to circumvent security measures with probability of success) |
| Stimulus: | Tries to access the data in the database |
|---|---|
| Source of Stimulus: | Internal or external individual who are not authorized |
| Environment: | At runtime |
| Artifact: | ZEN Client |
| Responses: | Stores data in unreadable format |
| Response Measure: | TBD (Time/effort/resources required to circumvent security measures with probability of success) |
| Stimulus: | A change occurs during the interview |
|---|---|
| Source of Stimulus: | Interviewer |
| Environment: | At runtime |
| Artifact: | ZEN Client |
| Responses: | Status is updated |
| Response Measure: | The status is updated within 1 second |
| Stimulus: | System crashes |
|---|---|
| Source of Stimulus: | Internal to the system |
| Environment: | At runtime |
| Artifact: | ZEN Client |
| Responses: | System restarts manually and returns to the last saved state |
| Response Measure: | Return to the last saved state within 30 seconds from system start. |
| Stimulus: | A question can be tagged with multiple tags |
|---|---|
| Source of Stimulus: | Interviewer |
| Environment: | At runtime |
| Artifact: | ZEN Client |
| Responses: | Support for efficient tagging |
| Response Measure: | In less then 1 second per tag |
Matrices
Architecture Views and Quality Attributes
This following matrix shows the mapping between views and high priority quality attributes. A × indicates that a quality attribute is addressed by the mapped views.
| Viewtypes | Views | Quality Attributes | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| #4 | #6 | #7 | #10 | #11 | #12 | #14 | #16 | #17 | ||
| Module | ZEN Server JSP Decomposition View | × | ||||||||
| ZEN Tool Data Model | × | |||||||||
| ZEN Client UI Decomposition View | × | × | × | |||||||
| C&C | ZEN Server High Level View | × | ||||||||
| ZEN Server With Struts 2 | × | |||||||||
| ZEN Client Interview Perspective | × | × | × | × | ||||||
| ZEN Client Analysis Perspective | × | × | × | |||||||
| ZEN Client Initial Configuration | × | × | ||||||||
| ZEN Client Authentication | × | × | ||||||||
Elements and Use Cases
The Element and Use Case Matrix explains the relation between the use cases and the two major elements.
| Elements | Use Cases | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Choose Question | Record Answer | Synchronize Engagement Data | Generate Report | Generate Template | Setup Engagement Data | Update SMIG Information | Update Tag List | Sign In | Sign Out | |
| ZEN Client | × | × | × | × | × | × | × | |||
| ZEN Server | × | × | × | × | × | × | × | |||
Client-Server Architecture
The rationale of choosing the style is as follows:
- A client-side desktop application is needed because the environment of using the application may not have network access.
- A centralize server-side application is needed because potentially large amount of historical data needs to be accumulated for trend analysis.
- The server-side application can be further divided into logic tier and data tier. However, we do not expect heavy loading on the server-side application. The client-server style is sufficient for current performance requirements.
The later sections will provide further decomposition of the architecture with multiple architectural views.
Allocation Architectural Viewtype
ZEN Tool Physical Deployment View
This view shows the physical elements of the ZEN Tool system and how they communicate.
| Element | Description |
|---|---|
| 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 web browser-based transfer via a VPN connection. |
| ZEN Client | This is the client portion of the ZEN Tool; it provides users the ability to conduct SMART interviews in an automated environment. |
| Web Browser | This is a standard web browser. |
Rationale
The system is partitioned into these components and connectors 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 we have chosen to use a client-server system.
- Quality Attribute: As indicated in Quality Attribute Scenario #13, all data captured during a SMART Engagement must be 100% secure during transfer. Therefore we use the HTTPS protocol for communication.
Module Architectural Viewtype
ZEN Tool Module Dependency View
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.
| 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. 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 | × | ||||
| Interview | SMIG Navigation, storing answers, comments, tags, displaying risks | × | |||||
| Interview - Status | Updating status on the UI based on the interview | × | |||||
| Reporting | This includes report generation | × | |||||
| Template | 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 | × |
ZEN Server JSP Decomposition View
This view enumerates all the JSP pages.
See ZEN Server With Struts 2 for its runtime behavior.
| Element | Responsibilities |
|---|---|
| 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_SMIG_Question.jsp | This page provides the following fields to add a new question:
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 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_Engagement.jsp | This page provides the following fields to add a new 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:
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:
|
| Manage_Tags.jsp | This page displays all of the default tags and allows a user to:
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 UI Decomposition View
Eclipse Rich Client Platform (Eclipse RCP) has been chosen as the framework for ZEN Client. The rationale is documented in the Architecture Trade-off Analysis section.
The ZEN Client UI is decomposed according to the Eclipse RCP framework and the two major actors of the ZEN Client, Interviewer and Analyst.
Key: UML
| Element | Description |
|---|---|
| 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.
| Element | Description |
|---|---|
| Engagement table | The table can be aptly described by the following SQL snippet:
Engagement (engagement_ID VARCHAR(64), engagement_Title VARCHAR(100), engagement_Description VARCHAR(400), client_Name VARCHAR(400), creation_Time BIGINT, modification_Time BIGINT, synch_Time BIGINT, repository VARCHAR(400), engagement_State INT, PRIMARY KEY (engagement_ID)) |
| Smig table | The table can be aptly described by the following SQL snippet:
Smig (smig_ID VARCHAR(64), smig_version VARCHAR(20), smig_description VARCHAR(400), creation_Time BIGINT, last_Modification BIGINT, PRIMARY KEY (smig_ID)) |
| Category table | The table can be aptly described by the following SQL snippet:
Category (category_ID VARCHAR(64), category_name VARCHAR(500), category_description VARCHAR(500), PRIMARY KEY (category_ID)) |
| Question table | The table can be aptly described by the following SQL snippet:
Question (question_ID VARCHAR(64), question_Text VARCHAR(500), question_short_name VARCHAR(500), default_next_question_ID VARCHAR(64), isDisabled INT, PRIMARY KEY (question_ID)) |
| Answer table | The table can be aptly described by the following SQL snippet:
Answer (answer_ID VARCHAR(64), answer_Text VARCHAR(400), related_Question_ID VARCHAR(64), PRIMARY KEY(answer_ID)) |
| Risk table | The table can be aptly described by the following SQL snippet:
Risk (risk_ID VARCHAR(64), risk_Text VARCHAR(400), PRIMARY KEY (risk_ID)) |
| Tag table | The table can be aptly described by the following SQL snippet:
Tag (tag_ID VARCHAR(64), tag_Title VARCHAR (400), PRIMARY KEY (tag_ID)) |
| Comment table | The table can be aptly described by the following SQL snippet:
Comment (comment_ID VARCHAR(64), comment_Text VARCHAR (10000), PRIMARY KEY (comment_ID)) |
| MitigationStrategy table | The table can be aptly described by the following SQL snippet:
Tag (tag_ID VARCHAR(64), tag_Title VARCHAR (400), PRIMARY KEY (tag_ID)) |
| User table | The table can be aptly described by the following SQL snippet:
User(user_ID VARCHAR(64), user_description VARCHAR(400), encrypt_String VARBINARY(200), random_Number VARBINARY(200), PRIMARY KEY (user_ID)) |
| Other tables | All other tables are simple M x N mapping tables. |
Component & Connector Architectural Viewtype
ZEN Tool High Level C&C View
This high level C&C view shows the architectural styles employed in the design of ZEN Tool.
- ZEN Tool is divided into two major elements, ZEN Client and ZEN Server.
- There is also an administration tool on the client side; however, it doesn't fit within the RCP model, which is the main framework of the client. Therefore, the administration tool is not represented in this view.
- ZEN Client is based on the Eclipse Rich Client Platform. Its design uses heavily the vocabulary from Eclipse such as views, editors, actions and adapter factories. See Rich Client Platform for the trade-off analysis.
- ZEN Server is based on the Servlet and JavaServer Page technologies. Struts 2 is selected as the implementation framework. See Web Application Framework for the trade-off analysis.
- ZEN Client communicates with ZEN Server using the XML-RPC over HTTPS connector. See ZEN Client Remoting for the trade-off analysis.
- BIRT Reporting Engine is used in both ZEN Client and ZEN Server. See Report Engine for the trade-off analysis.
- Data Access Objects are shared between ZEN Client and ZEN Server.
| Element | Description |
|---|---|
| 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 . |
ZEN Server With Struts 2
This view shows the runtime behavior of Struts 2, a web application framework that ZEN Server uses to handle browser requests.
| Element | Type | Responsibilities |
|---|---|---|
| Browser | Standard web browser | The browser submits the following requests to the server:
|
| 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. |
ZEN Client Initial Configuration
This view shows the ZEN Client's runtime behavior during initial configuration.
The view depicts three key architectural properties:
- To enforce security, a secret (Authentication Text) is stored instead of actual password.
- The call-return connectors represent function calls inside one JVM. There is no inter-process communication.
- 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 | Description |
|---|---|
| ConfigurationDialog | ConfigurationDialog allows the user to enter information during initial configuration. The information depicted here is focused on enabling the authentication process. Other information may be still needed. |
| 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. |
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, associating it with the Username.
Key: UML
| Element | Description |
|---|---|
| Username | This is the username the user uses to log into the ZEN Client. It is recorded in the database in plain text. |
| Password | This is the password the user uses to log into the ZEN Client. It is never recorded in the database, at all. |
| 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. |
| Encryption Key #1 | This is the key used for the encryption and decryption of the actual interview data. It is stored in the database in an encrypted format. |
| Encryption Key #2 | 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. |
ZEN Client Authentication
This view shows the ZEN Client's runtime behavior during authentication.
The view depicts three key architectural properties:
- To enforce security, only the components that are required for performing authentication are loaded into JVM.
- The call-return connectors represent function calls inside one JVM. There is no inter-process communication.
- 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 sequence diagram (seen below this view).
| Element | Description |
|---|---|
| ApplicationEntryPoint | The system starts in this component. It calls the AuthenticationController to enforce security. |
| AuthenticationController | To enforce security, the authentication must be done in the AuthenticationController before loading any other resources. |
| LoginDialog | LoginDialog allows user to enter user name and password. |
| Cipher | This object decrypts 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. |
| MainApplicatoin | This is an abstracted portion of ZEN Client that will be loaded after successful authentication. |
Sequence Diagrams
The sequence of the authentication process is as follows:
- User enters username & password through the LoginDialog.
- The system checks the database for the Username. If it exists, it retrieves the Random Number associated with that Username.
- The system then generates a new encryption key (Encryption Key #2') using a 1-way encryption algorithm based upon the entered Password and the Random Number it retrieved.
- The system now attempts to decrypt the Encryption String using the new encryption key (Encryption Key #2').
- The system then attempts to decouple the Challenge Authentication Text from the Encryption String. If it matches the answer (Authentication Text) it expects, the user is known to be valid.
- The system then decouples the Encryption Key #1' from the Encryption String.
Key: UML
| Element | Description |
|---|---|
| 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. |
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:
- 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.
- The model is decoupled from view and editor objects by using the ModelEventBus.
- 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 Decomposition View section.
| Element | Description |
|---|---|
| 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. |
Sequence Diagrams
Browse and Search
The Browse and Search sequence diagram shows the behavior of Interviewer interacting with the SmigView.
Key: UML
Navigation History
The Navigation History sequence diagram shows the behavior of Interviewer working on various AnswerEdiotr and the NavigationHistoryAction keeps track the navigation history, thus enabling the back and forward actions.
Key: UML
Status Update
The Status Update sequence diagram shows the behavior of saving answers and the corresponding status update.
Key: UML
ZEN Client Analysis Perspective
This view represents the runtime behavior of the AnalysisPerspective specified in the ZEN Client UI Decomposition View section.
It depicts three key architectural properties:
- Eclipse BIRT has been chosen as the report engine. See Report Engine for the trade-off analysis.
- Report format is customizable through modifying the Report Template (*.rptdesign), but ZEN Client itself does not support the modification of Report Template in normal operation context. See Business Context for the representation.
- BIRTWebViewer handles the JDBC connection directly. Customization is needed to support decryption of the data in ZENToolModel.
| Element | Description |
|---|---|
| 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 selected. |
| 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. |
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 are shared.
On the server side, BIRT allows the capability to interact with servlet mechanisms and application servers like JBoss.
ZEN Client Synchronization Perspective
Brief description to be added.
| Element | Description |
|---|---|
| ZEN Client | ZEN Client initiates connection to the server. It provides credentials for authentication. |
| ZEN Server | ZEN Server receives connections from the client. It has a HTTPS port open and listens for requests for clients. |
| Eclipse Workbench | 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. |
Architecture Trade-off Analysis
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. |
Additionally, the following factors are considered:
- Eclipse has a lager market share than NetBeans. (We use Eclipse in two of our core courses.)
- Eclipse has a larger amount of sample projects that we can study and refer to.
In conclusion, Eclipse RCP seems to be more favorable than NetBeans Platform.
Report Engine
The three main open source tools considered were
- JasperReports
- BIRT
- OpenReports
The pros and cons for each are as follows
- JasperReports
- Pros
- This is the most popular open source reporting tool (based on the number of downloads). It supports reporting functionality and exports to a variety of formats like PDF, HTML, XLS, CSV and XML.
- Cons
- Web reporting functionality does not seem to be straightforward. The idea is to export to HTML (or XML) and then use that for rendering.
- Pros
- BIRT
- Pros
- This is a reporting tool provided by Eclipse. It supports reporting functionality and exports to formats like PDF and HTML.
- Web reporting is straightforward. Same code can be used on the client side (within an application) and on server side (to render on a browser)
- Easy to integrate in Eclipse RCP framework
- Cons
- Export to CSV is not straightforward.
- Pros
- OpenReports
- Pros
- This is a web reporting tool. It supports reporting functionality and exports to formats like PDF, HTML, CSV, XLS, RTF, and Image
- It interacts with other reporting engines like BIRT and Jasper to provide one unified reporting framework.
- Cons
- Integrating OpenReports into a standalone application is not straightforward.
- Pros
Since all of the three tools have satisfactory support on modifiability, our decision was based on the integration effort that each tool may require. BIRT turned out to be a more favorable choice because it is easy to integrate into both Eclipse RCP-based client side application and servlet-based server side application.
ZEN Client Authentication
Two significant alternatives are considered:
- Coupled with ZEN Server: The same account and password are used to access both ZEN Client and ZEN Server. This will require the account and password on ZEN Server to be deployed to ZEN Client in a secured and trusted way. This approach promotes usability because the user only needs to remember one account and password. In the Synchronize Engagement Data use case, the user is spared from entering account and password to access ZEN Server.
- De-coupled with ZEN Server: The user uses independent account and password to access ZEN Client.
We chose de-coupled authentication because it greatly simplifies the architecture and the security scenario is acceptable for our client.
ZEN Client Installation
A variety of alternatives are considered:
- Online distribution: The binary file of ZEN Client is stored on the ZEN Server and can be accessed after entering the password. This approach promotes security.
- Offline distribution: The binary file of ZEN Client is distributed manually, through direct copying of the file. This approach is convenient but prohibits security because there is no control on the binary file.
- Automatic installation program: ZEN Client is packaged as an automatic installation program. This approach promotes usability because it's easy for the user to use. However, it is difficult to develop and test.
- Archived file: ZEN Client is packaged as a archived file, such as a zip file. This approach requires the user to unpack the archived file, so intuitively it can also be easy the user to use. What's more, it's easier to develop and test.
- Java Web Start: A fairly sophisticated mechanism for automatic and secured application deployment. However, our experiment showed that the integration between Java Web Start and Eclipse RCP still requires significant hacking.
We chose online distribution with an archived file because online distribution provides superior security control, and archived file is easier to develop and test.
ZEN Client Data Store
Three significant alternatives are considered:
- Flat file in XML format: Using flat file in XML format is extremely lightweight. XML supports easier migration from one version to another, so it promotes modifiability. Flat file can be easily encrypted, so it also promotes security. However, using flat file will require the data to be decrypted and loaded into memory, it prohibits scalability if there is a significant capacity requirement.
- Embedded database: Embedded database promotes security because other processes are not allowed to access the database. It also promotes usability because there is no upfront setup for the user. However, using embedded database also has the scalability limitation, unless we can justify there won't be a significant capacity requirement in ZEN Client.
- External database: External database promotes modifiability because database can be easily switched as long as a compliant JDBC driver is used. It also (indirectly) promotes scalability because sophisticated database can be used. However, it requires some upfront setup tasks, which may be challenging for nontechnical users.
We have decided that ZEN Client should support any database with a compliant JDBC driver. Optionally, we should be able to bundle an embedded database as the default database and give users an option to use an external database if so desired.
ZEN Client User Interface
See ZEN Client UI Decomposition View section to gain an overview of this tradeoff analysis.
Two significant alternatives are considered:
- Integrate tags and risks into the AnswerEditor: tags and risks become an integral part of the AnswerEditor.
- Separate tags and risks into viewers: Put tags into TagsView and risks into RiskView.
We chose to separate tags and risks into viewers because it promotes both modifiability and usability.
Database Record Id Generation
Two significant alternatives are considered:
- Automatic id generation: This method depends on the database providing such functionality. It reduces implementation effort and promotes performance in creating a new record.
- Universally Unique Identifier (UUID): This method decouple the dependency on any specific database implementation; therefore, it promotes modifiability in that any database can be used.
We chose to use UUID because modifiability outweighs ease of implementation and performance in this particular decision.
ZEN Client Remoting
- Alternative A: XML-RPC
XML-RPC is an extensible format. Since the data is sent across using HTTP layer it is easy to implement the communication between the client and the server. This makes the code easy to maintain. Apache XML-RPC for Java provides a secure way to establish communication between the client and the server. XML is standard and XML-RPC is a specification written to address sharing XML data irrespective of the operating system or the environment.
- Alternative B: SOAP
SOAP is an enhancement over XML-RPC. It offers a wide range of features over XML-RPC including user defined data types, ability to specify the recipient, message specific processing control etc. However to implement SOAP we need to add extra components on both the server and the client side. For the purpose of this tool, the requirement is simple file upload and download and the complexity of SOAP is not necessary to accomplish the task when it can be efficiently and securely done by XML-RPC.
Web Application Framework
There are probably too many web application framework out there. We only consider the following two alternatives.
- Pure Servlet/JSP: Also known as "not using any web application framework at all". It's possible to implement web application with only these two standards, but the development effort will be high.
- Struts 2: Struts 2 is one of the popular web application frameworks that implement design patterns such as front controller and command pattern.
We chose to use Struts 2 simply because it reduces development effort and allows us to focus on the business logics.
Glossary
Acronyms for Institutions
- SEI - Software Engineering Institute
- MSE - Master of Software Engineering
- CMU - Carnegie Mellon University
- SMART - Service Migration And Reuse Technique
- SMIG - Service Migration Interview Guide (Refer to ZEN Tool Glossary below)
Architecture related acronyms
- QAW - Quality Attribute Workshop
- ACDM - Architecture Centric Development Method
Planning related acronyms
- ETVX - Entry Task Validation eXit
- PERT - Program evaluation and review technique
MSE acronyms
- MOSP - Middle Of Semester Presentation
- EOSP - End Of Semester Presentation
ZEN Tool Glossary
- SMIG - Service Migration Interview Guide. The SMIG contains the following information in a hierarchical format
- Categories of topics to be discussed with the stakeholders
- Questions to be asked during a SMART Interview phase under each category
- Predefined answer(s) for each question. There need not be an answer at all, or there can more than one answer for each question
- Each pre-defined answer has 0..n risk factors associated with it.
- Each risk factor has 1..n mitigation strategies
- ZEN Tool - The software product delivered to the SEI. Performs functions in both client and server roles.
- ZEN Client - The set of functions within the ZEN Tool which will be used by the SEI personnel while on engagements. Functionality includes interview capturing software and report generation. The ZEN client forms the client portion of the ZEN tool.
- ZEN Server - The set of functions within the ZEN Tool which will be used as a repository for engagement information. Functionality includes report generation, SMIG maintenance, tag maintenance, and synchronization. The ZEN server forms the server portion of the ZEN tool. The ZEN client communicates with the ZEN server for various activities
- ZEN Users - The set of users authorized by the SEI to work on the SMART process. This includes technical and non-technical users
- Interviewer - This person uses the ZEN Client before and during engagement interviews. He can perform the following:
- Download engagement file
- Record answers to SMIG questions
- Apply tags to SMIG questions
- Record comments on SMIG questions
- Browse through the SMIG
- Record data in the Service and Component Tables
- Analyst - This person uses the ZEN Client and the ZEN Server after an engagement. She can perform the following:
- Upload interview data from the ZEN Client to the ZEN Server
- Consolidate multiple sets of data from the same engagement on the ZEN Server
- Download consolidated interview data from the ZEN Server to the ZEN Client
- Produce reports on the ZEN Client and/or the ZEN Server
- Admin - This person uses the ZEN Client and the ZEN Server. This person need not be a technical user. Any user who is aware of basic computer usage and who is slightly knowledgeable about the SMART process can be considered as an Admin. He can perform the following:
- Create & set up engagement files on the ZEN Server
- Create, modify, and delete custom tags
- Associate a custom list of tags with a particular engagement file
- Modify the SMIG in the following ways:
- Add a question
- Modify a question
- Delete a question (this does not actually delete the question, it simply marks it as inactive)
- Maintainer - TBD.
- Interviewer - This person uses the ZEN Client before and during engagement interviews. He can perform the following:
- Engagement - A set of interviews with a client company during which the feasibility of migrating a legacy system to a SOA architecture is determined. Involves the following phases (some of which are performed multiple times):
- Interview - A question and answer session with client representatives. The client representatives can vary in role from managers to developers. This is to ensure as much information is captured about the legacy system. Involves use of the Interview set of functions of the ZEN Client. Once this phase is complete, the Engagement shifts to the Analysis phase.
- Analysis - A review session covering all data captured to date. The purpose of this phase is to identify risks for the migration. Involves use of the reporting functions of both the ZEN Server and the ZEN Client. If further information is needed to make a final recommendation, the Engagement shifts back to the Interview phase. If a final recommendation can be made, the Engagement shifts to the Final Report phase.
- Final Report - A consolidation session where a final evaluation of the risks for the SOA migration is created and delivered to the client. Involves use of the reporting functions of both the ZEN Server and the ZEN Client.
- Engagement File - This file is initially created prior to an engagement and includes all information pertinent to the engagement. This includes:
- SMIG
- Any existing consolidated interview data
- Custom tags
- Interview Data - This represents all data captured during an Interview phase of an Engagement. Includes answers to SMIG questions, comments, and applied tags. Also includes all Service and Component table data captured. These pieces are defined as follows:
- Answers - Each question in the SMIG currently has associated predefined answers in multiple choice format. When the client answers a question during the Interview phase, the Interviewer will select the closest predefined answer.
- Comments - Because each question in the SMIG has predefined answers, often clients will answer in a way that does not fully fit one of the predefined answers. Therefore, the Interviewer may record comments on each question which notes the actual answer and expands on any related issues considered pertinent.
- Tags - When applying a comment to a question, the Interviewer may feel that the answer to a particular question is very important in terms of the SOA migration, and may wish to mark the answer for easy reference during the Analysis phase. To do so, the Interviewer will apply one or more pre-defined tags to the question. The tags will be reflected in the reports generated in the Analysis phase. In addition, the tags are used to set up the Service/Component table interface.
- SMART Templates - In addition to the SMIG questions, the Interviewer will want to capture information which fall under the category of SMART template. The service table and component table are examples of SMART templates. (TBD: Are these the only two?) The ZEN Client will provide a secondary interface to capture this information (the format of this interface has yet to be determined).
