Architecture

Document Sample
Architecture Powered By Docstoc
					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.

      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.
[edit]   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.
[edit]   Constraints
The following constraints are applied to the design of the architecture.
[edit] Business Constraints

       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.
[edit] Technical Constraints

      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.
         The ZEN Tool will need to work on a Windows XP machine.
         Connection to SEI requires using virtual private network (VPN).

Requirements Overview
[edit]   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 Catalog
  Use Case
                                                       Description
   Name

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
                 Prior to any interview phases of a given engagement, the interviewer obtains a copy of
Engagement
                 the engagement setup data prepared in the Setup Engagement Data use case.
Data

                 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
Choose           which a desired question is located. To quickly locate a question, the interviewer can
Question         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.

                 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
Record Answer
                 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?)

                 After each interview phase of a given engagement, the interviewers submit their
                 individual interview data for consolidation. Each interviewer associated with a specific
Consolidate      engagement is expected to upload the data they took, however this is not mandated.
Interview Data   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.

                 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
Generate
                 then the system generates the report. Second, in between engagements, the analyst
Report
                 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.

                 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
Generate
                 acceptable. The system is given the templates that are used during interview, and then
Template
                 the system adds new columns to them. The columns are the short names of questions
                 marked with specific tags.

Setup            Administrator prepares an engagement by entering information obtained prior to an
Engagement         engagement. The information includes the engagement client organization, type of
Data               system under evaluation, profiles of interviewees, the version of the SMIG which will be
                   used, and the set of tags that will be used.

                   Administrator updates SMIG information. It includes the basic create, read, modify and
Update SMIG        delete operations. The administrator can also promote the updated SMIG into a new
Information        version. The system has to keep the old versions of SMIG in order to maintain data
                   consistency for old engagement data.

Update Tag         Administrator updates the default tag list, which is used during Setup Engagement
List               Data. It includes the basic create, read, modify, and delete operations.

Register User      Administrator registers user account, which can be used in the Sign In use case.
Account            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.


                                                                                                      Rank
 Attributes       Concerns       Scenario#                        Description
                                                                                                      (I, D)

                                             At the end of an interview day, the system generates
                                             a consolidated report based on the input data of
Reliability     Data integrity   #1                                                                   (H, L)
                                             three team members that shows the risk factors that
                                             reflect correctly what was captured.

                                             When a report is generated, then the report includes
Usability       Smartness        #2                                                                   (L, H)
                                             risks based on historical data.

                                             When Dennis, a non-technical person, generates a
                                                                                                      (M,
Modifiability   Flexibility      #3          report, he can specify the information printed within
                                                                                                      M)
                                             10 minutes.
                                      Entering New SMIG information (offline)


                                              Question
                                              Answers
                                              Risk factor
                                              Recommendation
                Input                                                                           (H,
Usability                       #4            Related questions
                correctness                                                                     M)
                                              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.

                                      When entering a new thought-about SMIG question,
                User's mental                                                                   (M,
Usability                       #5    Dennis will find and enter the question in the right
                model                                                                           H)
                                      place in not more than 5 minutes.

                                      Client provides information not related to current
                                      question, the person using the tool will navigate to
Usability       Navigation      #6    the related topic within 15 seconds and then be able      (H, L)
                                      to return to the previous question with one push of
                                      button.

                                      A developer is able to add the generation of the          (H,
Modifiability   Flexibility     #7
                                      migration issue template within 1 person-week effort.     M)

                                      A developer will be able to add a new risk analysis
                                                                                                (M,
Modifiability   Flexibility     #8    capability reflected in report with only changing 1
                                                                                                H)
                                      component.

                                      A developer will be able to add new fields specific to
                                                                                                (M,
Modifiability   Flexibility     #9    a question or an engagement via modifications to the
                                                                                                H)
                                      GUI within 2 person-days per field.

                                      A developer will be able to create new specified          (H,
Modifiability   Flexibility     #10
                                      report type within 5 person-days                          M)

                Integrity of
                                      Unauthorized access to the application, and all these     (H,
Security        SMART           #11
                                      attempt are recognized and denied.                        M)
                process

                Integrity of
                                      Unauthorized access to the data in to database and        (H,
Security        SMART           #12
                                      all such attempts are recognized and denied.              M)
                process

                Integrity of
                                      Eavesdropping on any communications is not
Security        SMART           #13                                                             (H, L)
                                      possible based on current technical standard.
                process

Performance UI Response         #14   During the interview, the status will be updated within   (H, L)
                  Time                          1 second of a change occurring.

                                                During an interview, the interview module will be        (M,
Availability      Robustness       #15
                                                available at 99.9%.                                      H)

                                                In the event of a system crashes, the application will
                                                                                                         (H,
Availability      Downtime         #16          return to former state within 30 seconds from
                                                                                                         H)
                                                application start.

                                                While entering information to a question, this
Usability         Intuitiveness    #17          question can be tagged with multiple tags in less        (H, L)
                                                then 1 second per tag




[edit]   Six-Part Quality Attribute Scenarios
                                         Quality Attribute Scenario #4
   Stimulus:          Administrator enters new SMIG information

   Source of
                      Administrator
   Stimulus:

 Environment:         At runtime

    Artifact:         ZEN Server

                      New SMIG information can be entered consistently and that the tool provides hints
  Responses:          when inconsistent inputs are received. The process should be termed complete only
                      when all inconsistencies have been resolved.

   Response
                      Inconsistent inputs are rejected with hints showing where the inconsistency is.
   Measure:




                                         Quality Attribute Scenario #6
     Stimulus:           Client (interviewee) provides information not related to current question

     Source of
                         The person using the tool (interviewer)
     Stimulus:

   Environment:          At runtime

      Artifact:          ZEN Client

    Responses:           Navigate to the related topic and then be able to return to the previous question

     Response            Navigate to the related topic in 15 seconds; return to the previous question with
     Measure:            one push of button




                                         Quality Attribute Scenario #7
 Stimulus:     A developer wishes to add the generation of the migration issue template

 Source of
               Developer
 Stimulus:

Environment:   At design time

  Artifact:    Migration issue template

               Locates the migration issue template; makes modification; tests modification;
Responses:
               deploys modification

 Response
               Within 1 person-week effort.
 Measure:




                                Quality Attribute Scenario #10
 Stimulus:     A developer wishes to create new specified report type (template)

 Source of
               Developer
 Stimulus:

Environment:   At design time

  Artifact:    Report type (template)

               Locates the report type (template); makes modification; tests modification; deploys
Responses:
               modification

 Response
               Within 5 person-days
 Measure:




                                Quality Attribute Scenario #11
 Stimulus:     Tries to access the application

 Source of
               Internal or external individual who are not authorized
 Stimulus:

Environment:   At runtime

  Artifact:    ZEN Client and ZEN Server

Responses:     All these attempts are recognized (recorded) and denied

 Response      TBD (Time/effort/resources required to circumvent security measures with
 Measure:      probability of success)




                                Quality Attribute Scenario #12
 Stimulus:     Tries to access the data in the database
    Source of
                       Internal or external individual who are not authorized
    Stimulus:

  Environment:         At runtime

     Artifact:         ZEN Client

   Responses:          Stores data in unreadable format

    Response           TBD (Time/effort/resources required to circumvent security measures with
    Measure:           probability of success)




                 Quality Attribute Scenario #14
     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




                              Quality Attribute Scenario #16
     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.




                   Quality Attribute Scenario #17
     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
[edit]   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.

                               Views and Quality Attributes Matrix
                                                                       Quality Attributes
Viewtypes                    Views
                                                     #4 #6 #7 #10 #11 #12 #14 #16 #17

            ZEN Server JSP Decomposition View        ×

 Module               ZEN Tool Data Model            ×

             ZEN Client UI Decomposition View            ×                               ×           ×

                   ZEN Server High Level View        ×

                    ZEN Server With Struts 2         ×

                ZEN Client Interview Perspective         ×                           ×   ×           ×
   C&C
                ZEN Client Analysis Perspective                ×        ×            ×

                ZEN Client Initial Configuration                             ×       ×

                   ZEN Client Authentication                                 ×       ×




[edit]   Elements and Use Cases
The Element and Use Case Matrix explains the relation between the use cases
and the two major elements.

                                     Element and Use Case Matrix
                                                   Use Cases

Elemen    Choos      Recor   Synchron           Genera                        Update     Upda
                                         Genera               Setup                              Sig     Sig
   ts       e          d        ize               te                           SMIG        te
                                           te                Engagem                               n      n
          Questi     Answ    Engagem            Templa                       Informati    Tag
                                         Report              ent Data                             In     Out
           on         er      ent Data            te                             on       List

  ZEN
            ×          ×        ×           ×        ×                                           ×        ×
 Client

 ZEN
                                ×           ×                      ×             ×           ×   ×        ×
Server
[edit]   Client-Server Architecture
The following component and connector view shows the highest level of partitioning
the ZEN Tool in a client-server style.
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.
                                          Element Catalog
Element                                           Description

ZEN        ZEN Client is a standalone application that can be used during an interview. ZEN Client can
Client     operate in an environment without network access.

ZEN
           ZEN Server is a standalone application that keeps track of all SMART engagements.
Server

[edit]   Allocation Architectural Viewtype
[edit]   ZEN Tool Physical Deployment View
This view shows the physical elements of the ZEN Tool system and how they
communicate.
                                          Element Catalog
  Element                                            Description

             This is the physical server located at the SEI. It receives connections from multiple offsite
ZEN Server   Zen Client machines via a VPN connection. The communication can be either a direct
             data transfer or a web browser-based transfer.

             This is the physical laptop in use at the SEI and at client locations. It can communicate
ZEN Client
             with the ZEN Server. When at a client location, it does so in a direct data transfer or a
Computer
             web browser-based transfer via a VPN connection.
              This is the client portion of the ZEN Tool; it provides users the ability to conduct SMART
ZEN Client
              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.


[edit]   ZEN Server Deployment View
This view shows the primary components of the ZEN Server. It includes the web
server, which contains the Zen Server software component, and the MySQL
database being used as the primary repository.
                                        Element Catalog
  Element                                          Description

ZEN Server   This is the physical server located at the SEI. It contains a web server which contains
Machine      the ZEN Server software component. It also contains a MySQL database.

             This is the web server software component. It contains the ZEN Server and provides
Web Server
             remote access to it.

             This is the ZEN Server software component. It performs all of the critical repository
ZEN Server
             functionality.

MySQL        This is the primary data repository for the ZEN Server. It contains all of the engagement
Database     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
   system, we have chosen to use a web 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

             This is the physical laptop used by SMART personnel to perform engagements. It can be
ZEN Client   used both at the SEI (without VPN access) and at client locations, using a VPN connection
Machine      to communicate with the ZEN Server. It contains both the ZEN Client software component
             and a database.

             This is the ZEN Client software component. It performs all of the critical interview
ZEN Client
             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:
      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 is used because it is common and well-documented.
[edit]   ZEN Tool Deployment View
This view shows the deployment configuration of ZEN Tool.
This view highlights several architectural decisions:

      ZEN Client heavily depends on Eclipse RCP. See Rich Client Platform for the
   trade-off analysis.
         ZEN Client requires obfuscation to prevent reverse engineering.
      ZEN Server depends on Struts 2, which is compliant to Java Servlet and
   JavaServer Pages (JSP) standards. Therefore, any compliant servlet container
   can be used to replace JBoss Web (Tomcat).
      Standards such as HTTP/HTTPS and JDBC are applied in both ZEN Client
   and ZEN Server. Therefore, it is easy to replace HTTP/HTTPs implementation
   and database.
      AJP is specifically for Apache HTTP Server communicating with JBoss Web
   (Tomcat). Therefore, using other HTTP server, such as Microsoft IIS , will
   require a different configuration.
Key: UML
                                       Element Catalog
   Element                                         Description

Personal      One or more laptops installed with ZEN Client communicate with the Central Server
Laptop        through HTTPS protocol.

              Eclipse Rich Client Platform (RCP) provides the runtime environment for ZEN
Eclipse RCP
              Client.

              In this view, ZEN Client is more precisely defined as a plugin deployed inside Eclipse
ZEN Client    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 is a reporting engine that can be used as a set of plugins in Eclipse
Eclipse BIRT     RCP and a servlet in JBoss Web (Tomcat). Eclipse BIRT handles directly the JDBC
                 connections.

External         ZEN Client can be configured to use an External Database with a compliant JDBC
Database         driver.

                 Central Server is located inside SEI. It has been specified that the server will run on
Central Server
                 Windows XP, but in fact, the deployment applies to any OS with a standard JDK/JRE.

Apache HTTP      The most popular web server. It communicates with JBoss Web using the Apache
Server           JServ Protocol (AJP).

MySQL            The most popular open source database.

JBoss
Application      JBoss Application Server is a J2EE 1.4 compliant application server.
Server

                 JCA stands for J2EE Connector Architecture. JBoss JCA is the implementation of
JBoss JCA
                 JCA specification. The Data Source is deployed into JBoss using the JBoss JCA.

                 Data Source represents a JDBC data source that is available through a JNDI (Java
Data Source
                 Naming and Directory Interface) repository.

JBoss Naming     JBoss Naming Server (JBossNS) is implemented as a JNDI repository. ZEN Server
Server           looks up a JDBC data source from JBossNS.

JBoss Web        JBoss Web is in fact an embedded Tomcat, a servlet container that ZEN Server is
(Tomcat)         deployed into.

                 Struts 2 is a web application framework on which that ZEN Server is based. Its runtime
Struts 2
                 behavior can be found in the ZEN Server With Struts 2 section.

                 In this view, ZEN Server is more precisely defined as a component (or a set of actions,
ZEN Server       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]   Zen Common Directory Structure
The following is a list of packages that serve as a common resource for both the
client and 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]   ZEN Client Directory Structure
The following is a list of packages that comprise the client:
   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
                                   Notes (Note: All
                               components include UI,
            Component                                           Allen Marc Sajjad Session Somakala
                                logic and data access
                                 wherever applicable)

ZEN                          This component includes role
          Authentication                                                     ×
Server                       based management aspects

                             Creating SMIG and exposing
          SMIG               an interface to communication
                                                                                             ×
          Maintenance        component for creating an
                             XML structure of SMIG data

                             This includes report creation
          Reporting                                              ×                           ×
                             and report generation

                             Creating new engagement
                             setup and exposing an
          Engagement         interface to communication
                                                                             ×
          Setup              component for creating an
                             XML structure of engagement
                             setup data

                             This ensures secure ports
                             listening for information.
          Communication                                                             ×
                             There should be a single point
                             of entry

                             This module consolidates the
          Consolidation      interview data from multiple                                    ×
                             users

                             This task involves ensuring
                             that common tasks for
                             database access like
                             establishing connection etc. is
          Data Access
                             provided as a utility. This task                ×
          Layer
                             also involves verifying that the
                             data model is normalized and
                             does not have redundant
                             information.

                             This task involves ensuring
                             that the UI developed by all
          UI Layer           team members integrates well                           ×
                             and it looks like one well
                             developed UI

          Installation and   This component is for
                                                                                    ×
          Configuration      installing the component and
                            configuring it for use.
                            Configuration should be
                            available wherever applicable
                            for later use during the lifetime
                            of the tool

                            Interface for creating roles,
         Administration     usernames and passwords on                  ×
                            the server

ZEN                         This component includes role
         Authentication                                             ×
Client                      based management aspects

                            SMIG Navigation, storing
         Interview          answers, comments, tags,            ×
                            displaying risks

         Interview -        Updating status on the UI
                                                                            ×
         Status             based on the interview

                            This includes report
         Reporting                                              ×
                            generation

                            This includes generating
                            templates, component table
         Template           and service table on the                            ×
                            client. This is the Excel table
                            (can be CSV)

                            Interface for connecting to
                            server, downloading
         Administration     engagement setup, uploading         ×
                            interview data, downloading
                            interview consolidated data

                            This ensures secure ports
                            communicating with the
         Communication                                                          ×
                            server. There should be a
                            single point of contact

                            This task involves ensuring
                            that common tasks for
                            database access like
                            establishing connection etc. is
         Data Access
                            provided as a utility. This task            ×
         Layer
                            also involves verifying that the
                            data model is normalized and
                            does not have redundant
                            information.

                            This task involves ensuring
                            that the UI developed by all
         UI Layer           team members integrates well            ×
                            and it looks like one well
                            developed UI

         Installation and   This component is for                   ×
          Configuration    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.

                               The module represents the ZEN Client, which is a standalone GUI
edu.cmu.sei.smart.zen.client
                               application.

edu.cmu.sei.smart.zen.server The module represents the ZEN Server, which is a centralize server.

[edit]   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.
                                            Element Catalog
                                  Notes (Note: All
                              components include UI,
           Component                                           Allen Marc Sajjad Session Somakala
                               logic and data access
                                wherever applicable)

ZEN                         This component includes role
         Authentication                                                     ×
Server                      based management aspects

                            Creating SMIG and exposing
         SMIG               an interface to communication
                                                                                            ×
         Maintenance        component for creating an
                            XML structure of SMIG data

                            This includes report creation
         Reporting                                              ×                           ×
                            and report generation

                            Creating new engagement
                            setup and exposing an
         Engagement         interface to communication
                                                                            ×
         Setup              component for creating an
                            XML structure of engagement
                            setup data

                            This ensures secure ports
                            listening for information.
         Communication                                                             ×
                            There should be a single point
                            of entry

                            This module consolidates the
         Consolidation      interview data from multiple                                    ×
                            users

                            This task involves ensuring
                            that common tasks for
                            database access like
                            establishing connection etc. is
         Data Access
                            provided as a utility. This task                ×
         Layer
                            also involves verifying that the
                            data model is normalized and
                            does not have redundant
                            information.

                            This task involves ensuring
                            that the UI developed by all
         UI Layer           team members integrates well                           ×
                            and it looks like one well
                            developed UI

                            This component is for
         Installation and
                            installing the component and                           ×
         Configuration
                            configuring it for use.
                            Configuration should be
                            available wherever applicable
                            for later use during the lifetime
                            of the tool

                            Interface for creating roles,
         Administration     usernames and passwords on                  ×
                            the server

ZEN                         This component includes role
         Authentication                                             ×
Client                      based management aspects

                            SMIG Navigation, storing
         Interview          answers, comments, tags,            ×
                            displaying risks

         Interview -        Updating status on the UI
                                                                            ×
         Status             based on the interview

                            This includes report
         Reporting                                              ×
                            generation

                            This includes generating
                            templates, component table
         Template           and service table on the                            ×
                            client. This is the Excel table
                            (can be CSV)

                            Interface for connecting to
                            server, downloading
         Administration     engagement setup, uploading         ×
                            interview data, downloading
                            interview consolidated data

                            This ensures secure ports
                            communicating with the
         Communication                                                          ×
                            server. There should be a
                            single point of contact

                            This task involves ensuring
                            that common tasks for
                            database access like
                            establishing connection etc. is
         Data Access
                            provided as a utility. This task            ×
         Layer
                            also involves verifying that the
                            data model is normalized and
                            does not have redundant
                            information.

                            This task involves ensuring
                            that the UI developed by all
         UI Layer           team members integrates well            ×
                            and it looks like one well
                            developed UI

         Installation and   This component is for
                                                                    ×
         Configuration      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,
       but not all of them.
                                       Element Catalog
   Element                                        Description

              ZEN Server represents the web application layer that is based on JBoss Application
ZEN Server
              Server.

JBoss
              JBoss Application Server is a J2EE 1.4 compliant application server, but only the
Application
              following modules will be used by the ZEN Server.
Server

              JMX stands for Java Management Extension. JBoss JMX is the implementation of JMX
JBoss 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.

              JCA stands for J2EE Connector Architecture. JBoss JCA is the implementation of JCA
JBoss 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 is in fact the Tomcat wrapped as a MBean. It's a servlet container that ZEN
JBoss Web
                Server is deployed into.

                Struts 2 is a web application framework that ZEN Server is based on. Its runtime
Struts 2
                behavior can be found in the ZEN Server With Struts 2 section.

                The Java Virtual Machine layer provides the Java Runtime Environment for the ZEN
JVM
                Client to run.

                The Operation System layer provides the memory management, file I/O and other
OS
                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,
         but not all of them.
                                           Element Catalog
   Element                                             Description

                  ZEN Client represents the rich client application layer that is based on Eclipse Rich
ZEN Client
                  Client Platform.

                  ZEN Client relies heavily on Eclipse Rich Client Platform. It extends the Generic
Eclipse Rich
                  Workbench to provide the views, editors and perspectives as described in the ZEN
Client Platform
                  Client UI Decomposition View section.

                  The Generic Workbench manages the editors, views and perspectives. It provides
Generic
                  the selection service for transmitting events between views and editors. One example
Workbench
                  of its runtime behavior can be found in the ZEN Client Interview Perspective section.

                  SWT stands for the Standard Widget Toolkit. ZEN Client uses SWT to construct the
SWT
                  user interface.
                 JFace is a UI toolkit for handling common UI programming tasks. It is designed to work
JFace            with SWT without hiding it. ZEN Client uses its data binding framework to decouple
                 model from UI presentation.

Optional Plug-
                 Optional plug-ins such as help and update can be added to ZEN Client with ease.
ins

Platform         The Eclipse's core platform runtime module provides the fundamental functionalities for
Runtime          the rich client application to run.

Equinox OSGi     The Eclipse Equinox implements the OSGi R4 Framework.

                 The Java Virtual Machine layer provides the Java Runtime Environment for the ZEN
JVM
                 Client to run.

                 The Operation System layer provides the memory management, file I/O and other
OS
                 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 is responsible for verifying that the user or application accessing the
Authentication
                 server is a valid user of the system.

                 This process is responsible for modifications to the SMIG by supporting the following

SMIG                     Adding a question to the SMIG (and answers, risks, mitigation strategies)
Maintenance
                         Modifying an existing SMIG question (and answers, risks, mitigation
                     strategies)
                        Marking SMIG questions as no longer active

                This process is responsible for creating the initial data setup for a particular
                engagement. This includes


                        Enter preliminary information about the engagement
Engagement
Setup                   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

                This process is responsible for allowing the user to view reports on a browser. (TBD:
Reporting
                And what else?)

                This process is responsible for consolidating the interview data across the interviewers
Consolidation   per each engagement. This process will allow the user to upload the interview data
                and download the consolidated interview data.

                This process is responsible for communication between any outside component with
Communication   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
from the data access layer.




Key: UML
                                          Element Catalog
    Element                                          Responsibilities

                Report generation is used for generating reports and rendering it on the browser. This
Report
                will use the MVC pattern. The functionality which needed to be provided for reports
Generation
                are
                       Filtering the data based on queries
                       Sorting (TBD)
                       Exporting to PDF and HTML (TBD)
                       Printing data

Report
                This process can be used to customize reports (TBD)
Customization

[edit]   ZEN Server JSP Decomposition View
This view enumerates all the JSP pages.
See ZEN Server With Struts 2 for its runtime behavior.
                         Element Catalog
            Element                           Responsibilities

                      This is the default page that is displayed to users who enter the
Index.jsp             web site's URL; it provides an authentication form with username
                      and password fields for users to enter.

                      This is the main menu of functionalities that a user can choose
Main_Menu.jsp
                      from depending on the role he is authenticated in.
                         This is a dynamically generated page that gives feedback to the
Error_Page.jsp           user about improper or inconsistent information entry (i.e. bad
                         username or password), or server processing error.

                         This page provides the user with a list of engagements to choose
                         from, and a list of reports to generate for the chosen
Generate_Report.jsp
                         engagement. Note that only one type of report is generated at a
                         time.

                         This is the resulting report generated by the server and displayed
Report.jsp
                         to the user, who can then print it from his browser.

                         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
Manage_SMIG.jsp
                             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.

                         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
Add_SMIG_Question.jsp
                             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.

                         This page provides the following fields to edit an existing
                         question:
Edit_SMIG_Question.jsp

                                 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.

                        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).
Manage_Engagement.jsp
                                edit existing ones (which directs them to
                            Edit_Engagement.jsp).
                                delete existing ones (which directs them to
                            Delete_Engagement_Confirmation.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

Add_Engagement.jsp          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.
                                       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.
Edit_Engagement.jsp
                                           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.

                                   This page asks the user to confirm his choice to delete the
                                   selected engagement. Because an engagement, unlike a tag,
Delete_Engagement_Confirmation.jsp 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.

                                       This page displays all of the users of the ZEN Server and allows
                                       an administrator to:


                                               add users
Manage_Users.jsp
                                               remove users
                                               change the information of a user (name, type, ...)
                                               reset the password of a user

                                       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.
Manage_Tags.jsp
                                               select one to many tags and remove them.

                                       The confirmation of the addition, edits, or removals will be
                                       displayed on this page.

                                       This page displays all of the engagements and the users who
                                       have uploaded their interview reports for a particular
Consolidate_Interview_Data.jsp
                                       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.

                                       This page allows the user to download the ZEN Client tool onto
Download_ZEN_Client.jsp
                                       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 is responsible for verifying that the user or application accessing the
Authentication
                 server is a valid user of the system.

                 This process is responsible for allowing the user to interview and capture data.


                          Browse through the SMIG
Interview
                          Record answers to SMIG questions
                          Apply tags to SMIG questions
                          Record comments on SMIG questions

                 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
Template
                 tagged to be added to the template files, this process will be run by the user again.
Generation
                 The original data will be retained and the new columns will be appended wherever
                 applicable.

                 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
Reporting

                          Filtering the data based on queries
                        Sorting (TBD)
                        Exporting to PDF and HTML (TBD)
                        Printing data

                This process is responsible for connecting to the server and uploading and
                downloading data. This includes


                        Downloading engagement setup data
Communication
                        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
activity they perform.




Key: UML
                                         Element Catalog
    Element                                        Responsibilities

                 This process is responsible for allowing the user to interview and capture data.


                         Browse through the SMIG
Interview
                         Record answers to SMIG questions
                         Apply tags to SMIG questions
                         Record comments on SMIG questions
                   SMIG Navigation allows the client to navigate between questions. The questions can
                   be navigated in the following ways


                           Sequentially
SMIG Navigation            A new question can be triggered based on the answer chosen
                           Navigate to the last answered question
                           Search for a question and jump directly the one chosen by the user from the
                       search results

                   Information Gathering allows the client to record interview data. This will follow the
                   MVC pattern.


Information                Record answers to SMIG questions
Gathering
                           Apply tags to SMIG questions
                           Record comments on SMIG questions
                           Record data in the Service and Component Tables

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

                   The process captures comment information stored by the user. This will follow the
Comment
                   MVC pattern

                   The status of the answers which have been completed so far will be displayed to the
Status
                   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
                        This process is responsible for allowing the ZEN client to communicate with the
                        ZEN server and transfer data. This data includes


Communication                   Engagement setup data
                                Interview data
                                Consolidated interview data

Engagement Setup        This process is responsible for downloading the engagment setup data from the
Download                server

                        This process is responsible for uploading interview data from the Zen client to
Interview Data Upload
                        the ZEN server and downloading the consolidated interview data from the ZEN
Download
                        server

                        This process is responsible for communication between the ZEN client and the
Remoting
                        ZEN server

[edit]   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 Catalog
         Element                                              Description

                             The Workbench class is responsible for creating, managing and navigating
Workbench                    its workspace resources, which include perspectives, views and editors.
                             This class is part of the Eclipse RCP.

                             This InterviewPerspective class represents the initial user interface layout
InterviewPerspective
                             designed for the Interview Module in the Controller Layer.

                             This class represents the initial user interface layout designed for the
AnalysisPerspective
                             Report Module in the Controller Layer.

                             This class represents the initial user interface layout designed for the
SynchronizationPerspective
                             Synchronization Module in the Controller Layer.

                             This class is responsible for displaying SMIG questions in a hierarchical
SmigView                     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.

                        This class allows the Interviewer to record interview information, such as
AnswerEditor
                        answer choices, comments and tags.

                        This class is responsible for displaying the tags. The state of checked tags
TagsView                changes according to what question is selected in the SmigView and in the
                        editor area.

                        This class is responsible for displaying the associated risks to a selected
RiskView
                        answer choices in the AnswerEditor.

                        This class is responsible for showing the interview status. It displays the
StatusView
                        progress of each SMIG category.

                        This class is responsible for displaying available report templates for the
TemplateView
                        Analyst to choose from.

                        This class is responsible for producing report according to the chosen
                        template and the collected interview information. It uses the Ecliipse BIRT,
ReportEditor
                        an reporting engine chosen according the rationale documented in the
                        Architecture Trade-off Analysis section.

                        This class shows the locally available engagements. See Issues section for
EngagementView
                        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

                   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),
Engagement table
                   creation_Time BIGINT, modification_Time BIGINT, synch_Time BIGINT,
                   repository VARCHAR(400), engagement_State INT, PRIMARY KEY
                   (engagement_ID))

                   The table can be aptly described by the following SQL snippet:

                   Smig (smig_ID VARCHAR(64), smig_version VARCHAR(20), smig_description
Smig table
                   VARCHAR(400), creation_Time BIGINT, last_Modification BIGINT, PRIMARY
                   KEY (smig_ID))

                   The table can be aptly described by the following SQL snippet:

Category table     Category (category_ID VARCHAR(64), category_name VARCHAR(500),
                   category_description VARCHAR(500), PRIMARY KEY (category_ID))

                   The table can be aptly described by the following SQL snippet:

                   Question (question_ID VARCHAR(64), question_Text VARCHAR(500),
Question table
                   question_short_name VARCHAR(500), default_next_question_ID VARCHAR(64),
                   isDisabled INT, PRIMARY KEY (question_ID))

                   The table can be aptly described by the following SQL snippet:

Answer table       Answer (answer_ID VARCHAR(64), answer_Text VARCHAR(400),
                   related_Question_ID VARCHAR(64), PRIMARY KEY(answer_ID))

                   The table can be aptly described by the following SQL snippet:
Risk table
                   Risk (risk_ID VARCHAR(64), risk_Text VARCHAR(400), PRIMARY KEY (risk_ID))

                   The table can be aptly described by the following SQL snippet:
Tag table
                   Tag (tag_ID VARCHAR(64), tag_Title VARCHAR (400), PRIMARY KEY (tag_ID))

                   The table can be aptly described by the following SQL snippet:
Comment table
                   Comment (comment_ID VARCHAR(64), comment_Text VARCHAR (10000),
                     PRIMARY KEY (comment_ID))

                     The table can be aptly described by the following SQL snippet:
MitigationStrategy
table                Tag (tag_ID VARCHAR(64), tag_Title VARCHAR (400), PRIMARY KEY (tag_ID))

                     The table can be aptly described by the following SQL snippet:

                     User(user_ID VARCHAR(64), user_description VARCHAR(400), encrypt_String
User table
                     VARBINARY(200), random_Number VARBINARY(200), PRIMARY KEY
                     (user_ID))

Other tables         All other tables are simple M x N mapping tables.




[edit]   ZEN Engagement State Maintenance
Engagement State Transition

        The engagements in the server shall maintain one of the four different states
    at any given time. The following state transition diagram dictates the rules,
    conditions, and the sequence surrounding the change in states and the execution
    of transitions.

       All transitions to "closed" and "new" state should be decided by the engineer
    responsible for the engagement setup component. This is because such
    transitions are controlled and managed by that component.

         State transition diagram:
Engagement State Description Table
State
               Constant Name                            Description
Code

                                     Represents a state where the subject engagement has
1       NEW
                                     not been downloaded, stored, or closed.

2       DOWNLOADED                   Represents a state where the subject engagement has
                                            been downloaded by one or more client(s).

                                            Represents a state where client data for the subject
                                            engagement has been submitted by one or more
6         STORED
                                            client(s). Stored assumes that the engagement has
                                            been downloaded.

                                     Represents a state where a "new" engagement has
8         CLOSED_WITHOUT_DOWNLOADING been closed i.e. it was NOT downloaded or stored
                                     prior to closure.

                                            Represents a state where an engagement has been
10        CLOSED_AFTER_DOWNLOADING          closed after it was DOWNLOADED by one or more
                                            clients.

                                            Represents a state where an engagement has been
14        CLOSED_AFTER_STORING
                                            closed after it was STORED by one or more clients.




[edit]   Component & Connector Architectural Viewtype
[edit]   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 Catalog
Element              Description
                    SelectionService is part of the Eclipse RCP. It acts as an event bus that propagates
SelectionService
                    events between view and editor objects.

                    Views provide users with a graphical representation of data and editors allow users
Views/Editors
                    to interact with that data.

                    Adapter Factories are objects that link views and editors to the data access objects
Adapter Factories
                    on which they depend to display and edit data for the user.

                    JFace Actions are the actions to be implemented to link ZEN client functionalities
JFace Actions
                    with services offered on the ZEN server.

                    Data Access Objects extract data out of the database, based on the specific
                    command which is received. For example, download engagement setup would
Data Access
                    result in engagement data being extracted. On the other hand download
Objects
                    consolidated data would return the user's data along with the consolidated data of
                    all other users.

BIRT Reporting      The Eclipse BIRT reporting engine generates the report display by contacting the
Engine              database and using the report template file (*.rptdesign) for generating the report.

                    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
Report Templates
                    database, database connection details (password is encrypted) and other
(*.rptdesign)
                    presentation related details. It has an XML structure. (TBD: See how database
                    communication details can be overriden with application's data).

                    This is the data store that holds the data of the ZEN Tool. This will be accessed via
Data
                    a JDBC connector.

                    XML-RPC is a specification written to address sharing XML data irrespective of the
XML-RPC over
                    operating system or the environment. Using HTTPS ensures secured
HTTPS
                    communication between ZEN Client and ZEN Server.

Browser             This is a standard web browser.

Https               Secure connection over port 443.

                    The Request Dispatcher parses and executes http requests containing servlet
Tomcat Request
                    commands. It determines which requests should be handled by the BIRT reporting
Dispatcher
                    engine and which ones should be sent to the Struts 2 actions.

Struts 2            The Filter Dispatcher determines whether a request should invoke an action, and
FilterDispatcher    delegates control to the appropriate action if required.

Java Server Pages   The JSP pages displayed to the browser upon authentication and authorization.

                    The Actions are user-defined objects that implement the functionalities that are to
Struts 2 Actions
                    be expressed. They may access database through the Data Access Object.

                    These Business Objects are implemented as POJOs (Plain Old Java Objects),
Business Objects
                    which can be invoked by the XML-RPC over HTTPS .




[edit]   ZEN Server High Level View
This view shows the high level C&C view of ZEN Server.
                                   Element Catalog
   Element         Type                               Responsibilities

                            The client CPUs run the ZEN Client and communicate with the ZEN
Client CPU    Computer
                            Server to accomplish a number of server specific tasks.

                            Browsers communicate with the ZEN Server to accomplish a number
Browser       Browser
                            of tasks.

                            The Firewall filters incoming traffic to the applications and databases
Firewall      Application
                            residing on the server, in order a higher level of network security.

                            Tomcat is a servlet filter container that processes JSP tag
Tomcat Web
              Web Server    commands from client or web page requests, and displays the result
Server
                            of those requests to the client or browser.

Tomcat        Web Server    Contains a number of modules (servlets) provided by Tomcat, and
Components    components    that will be used to communicate with the Struts 2 Server.

                            Struts 2 contains the ZEN Server functional components and
              Application
Struts 2                    processes requests that require an action to be executed (this may
              Server
                            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
ZEN Server uses to handle browser requests.
                                     Element Catalog
       Element             Type                             Responsibilities

                                  The browser submits the following requests to the server:


                                          Interview consolidation requests to merge all of the
                                      interview data for a given engagement.
                    Standard              Requests for engagement reports.
Browser
                    web browser
                                          Modification requests for the SMIG.
                                          Modification requests for tags.
                                          Download requests for data.
                                          Setup requests for new engagements.

                                  The Firewall filters incoming traffic to the applications and
SEI Firewall        Application   databases residing on the server, in order a higher level of
                                  network security.

                                  Tomcat is a servlet filter container that processes JSP tag
Tomcat Web Server   Web Server    commands from web page requests, and displays the result of
                                  those requests to the browser.

                    Web Server    Contains a number of modules (servlets) provided by Tomcat,
Tomcat Components
                    components    and that will be used to communicate with the Struts 2 Server.

                                  The servlet filters parse and execute http requests containing
                                  servlet commands. These filters are optional. If the
                                  ActionContextCleanUp filter is present, the FilterDispatcher will
Servlet filters     Objects
                                  not clean up the ThreadLocal ActionContext once the Result is
                                  returned. If the ActionContextCleanUp filter is not present, the
                                  FilterDispatcher will cleanup all ThreadLocals.

                                  The FilterDispatcher checks the ActionMapper to determine
                                  whether a request should invoke an action, and delegates
FilterDispatcher    Object
                                  control to the ActionProxy if an action is require. This filter IS
                                  required.

                                  The web.xml file describes all necessary framework components
web.xml             File          for web deployment, including servlet filters. This is a required
                                  configuration file.

                                  Struts 2 contains the ZEN Server functional components and
                    Application
Struts 2                          processes requests that require an action to be executed (this
                    Server
                                  may involve the database).

                                  The ActionMapper determines whether a request requires an
ActionMapper        Object
                                  action to be invoked.

                                  The ActionProxy refers to the ConfigurationManager to
ActionProxy         Object
                                  determine which ActionInvocation to create to process the
                                 action, and it creates that ActionInvocation object.

                                 The ConfigurationManager uses the information from struts.xml
ConfigurationManager Object
                                 to tie an ActionInvocation with the action that it handles.

                                 The struts.xml file initializes the ConfigurationManager and
struts.xml           File        contains result/view types, action mappings, interceptors, and so
                                 forth. This is an optional configuration file.

                                 The ActionInvocation is responsible for the command pattern
                                 implementation of Struts 2, which includes invoking interceptors
ActionInvocation     Object
                                 and actions, and looking up the proper report type to create
                                 based on an Action's result code (mapped in struts.xml).

                                 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
Interceptors         Objects
                                 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.

                                 The Action is a user-defined class that implements the
Action               Objects     functionality that is to be expressed. It may access database
                                 through the Data Access Object.

                                 The Data Access Object is responsible for accessing database
Data Access Object   Objects     through JDBC connection. Modification to database must be
                                 transactional, i.e., it's either all or nothing.

                                 The Database is the central repository of the ZEN Server Tool
Database             Database    (including engagement data, SMIG version, interview
                                 reports, ...).

                                 The Result is an (optional) object that is created after the Action
Result               Object      executes, and returned to the browser. The Result may
                                 optionally use a rendering Template (JSP, FreeMarker, ...).

                                 The Template is a file that is used to describe how the Result
Template             File
                                 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
       no inter-process communication.
   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.
                   Other information may be still needed.

SecureRandom       A secure random number generator. This is part of the JDK.

                   This object implements the one-way cryptographic hash function. Possible hash
MessageDigest      functions are SHA-256 and SHA-512. MD5 and SHA-1 are ruled out because of
                   identified security flaw.

                   This object encrypts Authentication Text and Encryption Key #1 into the
Cipher
                   Encryption String by using Encryption Key #2.

AccountDAO         AccountDAO is responsible for accessing the actual database table using JDBC.

                   AccountModel stores the Username, Random Number and Encryption String in a
AccountModel
                   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,
   associating it with the Username.
Key: UML

                                           Element Catalog
   Element                                              Description

                 This is the username the user uses to log into the ZEN Client. It is recorded in the
Username
                 database in plain text.

                 This is the password the user uses to log into the ZEN Client. It is never recorded in
Password
                 the database, at all.

Random           This is a random number, called the "Salt", which is associated with a particular
Number           Username. It is stored in the database in plain text.

Authentication   This is a text string which is stored in the database in an encrypted format. It is used to
Text             verify that the user has entered the correct password.

Encryption Key   This is the key used for the encryption and decryption of the actual interview data. It is
#1               stored in the database in an encrypted format.
Encryption Key   This is the key generated from a 1-way encryption algorithm based upon the entered
#2               Password and the Random Number.

                 This is the concatenation of the Authentication Text and Encryption Key. The two
Encryption
                 elements are concatenated in plain text format, then the entire string is encrypted
String
                 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
sequence diagram (seen below this view).
          Element Catalog
Element                Description
                           The system starts in this component. It calls the AuthenticationController to
ApplicationEntryPoint
                           enforce security.

                           To enforce security, the authentication must be done in the
AuthenticationController
                           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 is responsible for accessing the actual database table using
AccountDAO
                           JDBC.

                           AccountModel stores the Username, Random Number and Encryption
AccountModel
                           String in a database table.

                           This is an abstracted portion of ZEN Client that will be loaded after successful
MainApplicatoin
                           authentication.




[edit] 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 Catalog
     Element                                                Description

                      This is the username the user uses to log into the ZEN Client. It is recorded in the
Username              database in plain text. It is initially created during installation, when the user selects
                      login information.

                      This is the password the user uses to log into the ZEN Client. It is never recorded in
Password              the database, at all. However, it is used to create an encryption key which IS stored
                      in the database (this will be explained later).

                      This is a random number, called the "Salt", which is associated with a particular
Random Number
                      username. It is stored in the database in plain text.

                      This is a text string which is stored in the database in an encrypted format. It is
Authentication Text
                      used to verify that the user has entered the correct password.

Challenge             This is the text extracted from Encryption String using Encryption Key #2'. It
Authentication Text   should match the original Authentication Text for a successful authentication.

                      This is the key that is extracted from the Encryption String using the Encryption
Encryption Key #1'
                      Key #2'.

                      This is the key generated from one-way encryption algorithm based upon the
Encryption Key #2'
                      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
Decomposition View section.
                                            Element Catalog
         Element                                            Description

                          SelectionService is part of the Eclipse RCP. It acts as an event bus that
SelectionService
                          propagates events between view and editor objects.

                          SmigView is responsible for displaying SMIG data model using a tree. It
SmigView                  announces selection events to the event bus indicating which question is
                          selected.

                          AnswerEditor is responsible for providing the answering form and accepting
                          response information. It announces activation events indicating an
AnswerEditor              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 is responsible for displaying the progress of an interview. (To be
StatusView
                          refined)

                          SmigFilter is responsible for matching questions to key words. The matching
SmigFilter
                          results are then presented in the SmigView.

                        NavigationHistoryAction keeps track of the navigation history. This object
                        directly addresses the quality attribute scenario #6: Client provides information
NavigationHistoryAction 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.

                          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
AnswerAction              ResponseDAO object to retrieve responses from the database. The
                          information is then passed to the AnswerEditor. It also activates the
                          AnswerEditor.

                          This object hooks up the SmigView object with the SMIG data model. It uses
SmigAdaptorFactory
                          the SmigDAO object to retrieve SMIG data model from the database.

                          This object hooks up the StatusView object with the response data model. It
StatusAdaptorFactory      uses the ResponseDAO object to retrieve data from database and construct
                          the status data model for the StatusView.

                          This object is responsible for saving information gathered by the AnswerEditor
SaveAction                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 is responsible for accessing the actual database table using
ResponseDAO               JDBC. Modification to ResponseModel must be transactional, i.e., it's either all
                          or nothing.

                          ResponseDAO uses Cipher object to encrypt/decrypt data before storing it
Cipher
                          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 is a set of database tables that represent the responses to
ResponseModel
                  the SMIG questions.




[edit] Sequence Diagrams
[edit] Browse and Search
The Browse and Search sequence diagram shows the behavior of Interviewer
interacting with the SmigView.
Key: UML

[edit] 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

[edit] Status Update
The Status Update sequence diagram shows the behavior of saving answers and
the corresponding status update.
Key: UML

[edit]   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 Catalog
        Element                                    Description

                   SelectionService is part of the Eclipse RCP. It acts as an event bus that
SelectionService
                   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 listens to the selection events from TemplateView. If a report,
ReportAction             instead of the report group, is selected, the action is enabled. It instantiates a
                         ReportEditor and passes the associated report object.

                         TemplateAdapterFactory hooks up the TemplateView object with the list of
                         reports available. It reads the report list file (in xml format) and extracts the
TemplateAdapterFactory
                         report category and report user friendly name, and the actual report name
                         and instantiates a TemplateView object.

                         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
ReportEditor
                         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 instantiates Eclipse BIRT report viewer with the link to the
PreviewBirtAction
                         report design file and the browser which is instantiated in ReportEditor.

                         BIRTWebViewer is the Eclipse BIRT reporting engine which generates the
BIRTWebViewer            report display by contacting the database and using the report template file
                         (*.rptdesign) for generating the report.

                         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
Report Template
                         database, database connection details (password is encrypted) and other
(*.rptdesign)
                         presentation related details. It has an XML structure. (TBD: See how
                         database communication details can be overriden with application's data)

                         This is the file which contains details about the list of reports, the names of
Report List (*.xml)      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 holds the entire data of the ZEN Tool on which reports have
ZENToolModel
                         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
are shared.
On the server side, BIRT allows the capability to interact with servlet mechanisms
and application servers like JBoss.

[edit]   ZEN Client Synchronization Perspective
Brief description to be added.




                                         Element Catalog
  Element                                            Description

ZEN Client   ZEN Client initiates connection to the server. It provides credentials for authentication.

             ZEN Server receives connections from the client. It has a HTTPS port open and listens
ZEN Server
             for requests for clients.
Eclipse         Eclipse Workbench manages the editors, views and perspectives. It provides the
Workbench       selection service for transmitting events between views and editors.

              JFace Actions are the actions to be implemented to integrate the ZEN client
JFace Actions functionality, specifically here, the synchronization tasks using the JFace library provided
              within Eclipse.

                Tomcat is a servlet filter container that processes HTTP/HTTPS commands from client
Tomcat          or web page requests, and returns/displays the result of those requests to the client or
                browser. .

Business        Business Objects are implemented as POJOs (Plain Old Java Objects), which can be
Objects         invoked by the XML-RPC over HTTPS.

                XML-RPC is a specification written to address sharing XML data irrespective of the
XML-RPC
                operating system or the environment. Using HTTPS ensures secured communication
over HTTPS
                between ZEN Client and ZEN Server.

                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
Data Access
                being extracted. On the other hand download consolidated data would return the user's
                data along with the consolidated data of all other users.

                This is the data store that holds the data of the ZEN Tool. This will be accessed via a
Data
                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

                                                                                  Good with it's native
Eclipse                       Both have no build-in         Both are proven
         Both are able to                                                         SWT approach.
                              features for security.        and stable
         support creating                                                         Not as good; depending
                              (Supported by underlying      solutions in the
NetBeans usable UI.           JDK/JRE.)                     market.               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.

[edit]   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.
         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.
         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.
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.

[edit]   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.

[edit]   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.

[edit]   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.

[edit]   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.

[edit]   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.

[edit]   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.

[edit]   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.

[edit]   Glossary
[edit]   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)


[edit]   Architecture related acronyms
         QAW - Quality Attribute Workshop
         ACDM - Architecture Centric Development Method


[edit]   Planning related acronyms
         ETVX - Entry Task Validation eXit
         PERT - Program evaluation and review technique


[edit]   MSE acronyms
         MOSP - Middle Of Semester Presentation
         EOSP - End Of Semester Presentation


[edit]   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.
   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).

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:38
posted:8/31/2011
language:English
pages:87