system and software architecture description - … system design ... patterns and frameworks ......

11/18/2012

System and Software Architecture Description (SSAD)

Early Medieval East Asian Timeline

Team 9

Daniel Link System Architect Ainsley Chong Project Manager Priyanka Shetty Builder Aarti Kumar Gupta Tester Abdullah Alkahtani Trainer Byron Robert Chan Quality Focal Point

System and Software Architecture Description (SSAD) Version 10.0

SSAD_IOC2_S10b_T09_V10.0 ii 11/18/12

Version History Date Author Version Changes made Rationale

10/09/09 DL 1.0 Initial version Initial version for Core Foundations Commitment Package

10/16/09 DL 1.1 Added to section 2 and 3 according to Valuation phase

Foundations Commitment Package

10/20/09 DL 2.0 Reworked most parts Architecture Review Board 10/28/09 DL 3.0 Corrected errors pointed out in ARB;

Reworked the document sections that had to be changed due to our switch from Use NDI to Architected Agile architecture

Foundations Commitment Package

11/11/09 DL 4.0 Corrected document according to evaluation of Foundations Commitment Package

Response to evaluation of Foundations Commitment Package

11/23/09 DL 5.0 Reworked most parts, added process realization diagrams, changed underlying operating system from Linux to Windows Server 2008

Development Commitment Package

12/02/2009 DL 6.0 Updated most UML diagrams, added sequence diagrams and class diagram

Development Commitment Architecture Review Board

12/07/2009 DL 7.0 Changed Artifacts and Information diagram, Use Cases Overview and Login Sequence Diagram

ARB comments

12/13/2009 DL 7.5 Changed sequence diagram for List Submissions / Recent Changes

Bugzilla bugs from IIV&V; archiving

2/8/2010 DL 8.0 Made language more clear throughout document

Incorporated actionable fixes from DCR ARB comments and peer reviews

Re-baselined Development Commitment Review Draft

2/11/2010 DL 8.5 Changed some diagrams to landscape perspective

Fixed bugs from Bugzilla

Re-baselined Development Commitment Architecture Review Board

4/5/2010 DL 9.5 Incorporated changes suggested at RDCR ARB

IOC package

4/28/2010 DL 10.0 Deleted "Submission Preview" use case


SSAD_IOC2_S10b_T09_V10.0 iii 11/18/12

Table of ContentsSystem and Software Architecture Description (SSAD) ............................................................ i Version History ............................................................................................................................. ii Table of Contents ......................................................................................................................... iii Table of Tables ............................................................................................................................. iv Table of Figures............................................................................................................................ vi 1. Introduction ............................................................................................................................. 1

1.1 Purpose of the SSAD .................................................................................................... 1

1.2 Status of the SSAD ....................................................................................................... 1

2. System Analysis ....................................................................................................................... 2

2.1 System Analysis Overview ........................................................................................... 2

2.2 System Analysis Rationale ......................................................................................... 33

3. Technology-Independent Model .......................................................................................... 34

4. Technology-Specific System Design .................................................................................... 35

4.1 Design Overview ......................................................................................................... 35

4.2 Design Rationale ......................................................................................................... 47

5. Architectural Styles, Patterns and Frameworks ................................................................ 52


SSAD_IOC2_S10b_T09_V10.0 iv 11/18/12

Table of TablesTable 1: Actors Summary................................................................................................................ 4

Table 2: Artifacts and Information Summary ................................................................................. 6

Table 3: Process Description - Request contributor account ......................................................... 8

Table 4: Typical Course of Action - Request contributor account ................................................. 8

Table 5: Alternate Course of Action - Request contributor account .............................................. 9

Table 6: Alternate Course of Action - Request contributor account .............................................. 9

Table 7: Exceptional Course of Action - Request contributor account .......................................... 9

Table 8: Exceptional Course of Action - Request contributor account ........................................ 10

Table 9: Process Description - Manage contributor accounts ..................................................... 11

Table 10: Typical Course of Action - Manage contributor accounts ........................................... 11



Table 13: Alternate Course of Action - Manage contributor accounts ........................................ 12

Table 14: Process Description - Manage moderator accounts .................................................... 13

Table 15: Typical Course of Action - Manage moderator accounts ............................................ 13

Table 16: Typical Course of Action - Manage moderator accounts ............................................ 13

Table 17: Alternate Course of Action - Manage moderator accounts.......................................... 14

Table 18: Process Description - Login ......................................................................................... 15

Table 19: Typical Course of Action - Login ................................................................................. 15

Table 20: Alternate Course of Action - Login .............................................................................. 15

Table 21: Alternate Course of Action - Login .............................................................................. 16

Table 22: Exceptional Course of Action - Login .......................................................................... 16

Table 23: Process Description - Logout ....................................................................................... 16

Table 24: Typical Course of Action - Logout ............................................................................... 17

Table 25: Process Description - Edit Account Information ......................................................... 18

Table 26: Typical Course of Action - Edit Account Information .................................................. 18

Table 27: Alternate Course of Action - Edit Account Information ............................................... 19

Table 28: Exceptional Course of Action - Edit Account Information ........................................... 19


SSAD_IOC2_S10b_T09_V10.0 v 11/18/12

Table 29: Process Description - List Submissions / Recent Changes .......................................... 20

Table 30: Typical Course of Action - List Submissions / Recent Changes ................................... 20

Table 31: Process Description - ................................................................................................... 21

Table 32: Typical Course of Action - ............................................................................................ 22

Table 33: Alternate Course of Action - ......................................................................................... 22


Table 35: Process Description - Comment on article .................................................................. 24

Table 36: Typical Course of Action - Comment on article ........................................................... 24

Table 37: Exceptional Course of Action - Comment on article .................................................... 24

Table 40: Process Description - Edit Article ................................................................................ 25

Table 41: Typical Course of Action - Edit Article ........................................................................ 25

Table 43: Exceptional Course of Action - Edit Article ................................................................. 26


Table 45: Typical Course of Action - Add Source ........................................................................ 27

Table 47: Exceptional Course of Action - Add Source ................................................................. 28


Table 49: Typical Course of Action - Modify Source ................................................................... 29

Table 51: Exceptional Course of Action - ..................................................................................... 30


Table 53: Typical Course of Action - ............................................................................................ 31



Table 56: Hardware Component Description .............................................................................. 39

Table 57: Software Component Description................................................................................. 39

Table 58: Supporting Software Component Description .............................................................. 40

Table 59: Design Class Description ............................................................................................. 42

Table 60: Architectural Styles, Patterns, and Frameworks .......................................................... 52


SSAD_IOC2_S10b_T09_V10.0 vi 11/18/12

Table of FiguresFigure 1: System Context Diagram ................................................................................................ 3

Figure 2: Artifacts and Information Diagram ................................................................................ 5

Figure 3: Process Diagram ............................................................................................................ 7

Figure 4: Hardware Component Class Diagram ......................................................................... 36

Figure 5: Software Component Class Diagram ........................................................................... 37

Figure 6: Deployment Diagram.................................................................................................... 38

Figure 7: Design Class Diagram .................................................................................................. 41

Figure 8: Login Class Diagram .................................................................................................... 43

Figure 9: Process Realization Diagram - Login .......................................................................... 44

Figure 10: Process Realization Diagram - Read Article.............................................................. 45 Figure 11: Process Realization Diagram - List Submissions / Recent Changes .......................... 46 Figure 12: iStudio diagram of the new system ............................................................................. 50


SSAD_IOC2_S10b_T09_V10.0 1 11/18/12

1. Introduction

1.1 Purpose of the SSAD The purpose of the System and Software Architecture Description is to demonstrate to developers and operational stakeholders how the system to be built will operate and what its operations are. It therefore shows where the system will be situated with relation to others, what functionalities it will have, what data will flow in out of it as well as what is kept; furthermore, what its components will be and how they will interact. A sincere attempt is made to make the language of this document understandable to all stakeholders.

1.2 Status of the SSAD The SSAD is being submitted for the Initial Operational Capacity Package. Input from the Re-baselined Development Commitment Review Architecture Review Board has been processed. The project is in the Development phase and minor changes of the implementation are reflected in the architecture.


SSAD_IOC2_S10b_T09_V10.0 2 11/18/12

2. System Analysis

2.1 System Analysis Overview The main purposes of our new additions to and extensions of the Early Medieval East Asian Timeline system are to make adding and managing content easier as well as creating a platform upon which a community of scholars as well as regular users can regulate itself while contributing valuable content. For this, the new system will keep track of newly submitted articles about historic events as well as edits to and comments about current ones. The fate of submissions will be tracked by the system and all participants will be kept informed at all times. User accounts and privileges will also be tracked by the new system. Instead of the previously employed manual ways of moving information to its destination within the timeline, the new system will make positioning articles possible through an easily understood web-based GUI.


SSAD_IOC2_S10b_T09_V10.0 3 11/18/12

2.1.1 System context

Figure 1: System Context Diagram


SSAD_IOC2_S10b_T09_V10.0 4 11/18/12

Table 1: Actors Summary

Actor Description Responsibilities Administrator Person who adds or removes moderators;

Actor with the highest privilege level in the system

x Adds or removes moderators

Moderator Person who accepts or rejects contributions and controls the structure and contents of the website

x Reviews new contributions x Arranges the contents of the

website x Manages contributor

accounts Contributor Person who contributes one or more

articles to the website x Fills out template forms in

order to edit articles or leave comments

Reader Person who is a general reader of the website; unprivileged

x Reads the website

New Timeline System

The new system that our team will build x Manages user accounts x Manages content

submissions x Places content in the timeline

Data backup system

A computer that accepts data from the system for backup; not part of the system that our team will build

x Accepts data for backups x Reports backup results


SSAD_IOC2_S10b_T09_V10.0 5 11/18/12

2.1.2 Artifacts & Information

Figure 2: Artifacts and Information Diagram


SSAD_IOC2_S10b_T09_V10.0 6 11/18/12

Table 2: Artifacts and Information Summary

Artifact Purpose ATF-1: Timeline Item A structured description of facts ATF-2: Historical Detail Supplemental information about historical articles ATF-3: Source Information about a source of historic information ATF-4: Journal Source A source that comes from a scientific journal ATF-5: Comment A message regarding an article. It that aims at prompting a

moderator to change the contents of the referenced article or take different action

ATF-6: User A person who is known to the system and fills out at least one role.

ATF-7: Personal Name The name of a user of the system or of the author of a source


SSAD_IOC2_S10b_T09_V10.0 7 11/18/12

2.1.3 Behavior

Figure 3: Process Diagram


SSAD_IOC2_S10b_T09_V10.0 8 11/18/12

2.1.3.1 Account Management

2 .1 .3 .1 .1 Request contr ibutor account

Table 3: Process Description - Request contributor account

Identifier UC-1: Request contributor account Purpose Reader can request a contributor account Requirements CR-3: Administrator/Moderators/Contributors need to have accounts

to prevent abuse Development Risks

None

Pre-conditions Reader is on Request Contributor Account page Post-conditions Account database is updated with reader's contributor account and

reader is returned to Login page unless request was rejected by system

Table 4: Typical Course of Action - Request contributor account

Seq# Actor’s Action System’s Response 1 On the Request Contributor

Account page, the reader fills out information in the New Contributor Account form (E-mail and Password required; Name, Organization, Occupation optional)

2 Reader clicks "Submit" 3 System saves account information as an

inactive account in the account database and sends confirmation e-mail with activation link to the e-mail address supplied by the reader. Reader is returned to login page

4 Reader clicks on the account activation URL in the confirmation e-mail

5 System activates new account in the account database and displays activation notice page saying that reader's new contributor account has been activated


SSAD_IOC2_S10b_T09_V10.0 9 11/18/12

Table 5: Alternate Course of Action - Request contributor account


Account page, reader clicks on "Back" button

2 Form is not submitted; login page is displayed

Table 6: Alternate Course of Action - Request contributor account


Account page, reader clicks on "Regimes Timeline" or "Events Timeline" link

2 Form is not submitted; Regimes timeline page or events timeline page are displayed according to reader's choice

Table 7: Exceptional Course of Action - Request contributor account


Account page, the reader leaves e-mail and/or password blank or fills out e-mail implausibly (e.g. no “@” in the e-mail address)

2 Reader clicks "Submit" 3 System shows alert box reminding

reader to at least fill out e-mail and password

4 Reader clicks “OK” on alert box or closes alert box

5 System stays on New Contributor Account form page with information that reader had already entered intact


SSAD_IOC2_S10b_T09_V10.0 10 11/18/12

Table 8: Exceptional Course of Action - Request contributor account


Account page, reader fills out at least e-mail and password

2 Reader clicks "Submit" 3 System determines that reader has

submitted an e-mail address that already has an account associated with it

4 System displays red text on the Request Contributor Account page near the submit button with message that an account with the submitted e-mail address already exists.


SSAD_IOC2_S10b_T09_V10.0 11 11/18/12

2.1.3 .1 .2 Manage contr ibutor accounts

Table 9: Process Description - Manage contributor accounts

Identifier UC-2: Manage contributor accounts Purpose Moderator can decide who is a contributor and edit account info

as needed Requirements CR-3: Administrator/Moderators/Contributors need to have accounts

to prevent abuse Development Risks

None

Pre-conditions Moderator is on Manage Contributor Accounts page Post-conditions Contributor information/status has been modified or the account

deleted in the database unless the moderator left it unchanged

Table 10: Typical Course of Action - Manage contributor accounts

Seq# Actor’s Action System’s Response 1 On Manage Contributor

Accounts page, moderator clicks on "Modify" next to an account

2 System displays account info in Edit Account Information form and gives control to "Edit Account Information" use case



Accounts page, moderator clicks on "Delete" next to an account

2 System displays yes/no dialog box asking whether moderator really wants to delete this account

3 On yes/no dialog box, moderator clicks “yes” button

4 Account is deleted from account database; System displays Manage Contributor Accounts page


SSAD_IOC2_S10b_T09_V10.0 12 11/18/12



Accounts page, moderator clicks on "Delete" next to an account

2 System displays yes/no dialog box asking whether moderator really wants to delete this account

3 On yes/no dialog box, moderator clicks “no” button

4 Account is not deleted from account database; System displays Manage Contributor Accounts page

Table 13: Alternate Course of Action - Manage contributor accounts


Accounts page, moderator clicks on "Log off"

2 Moderator is logged out of the system and system displays home page


SSAD_IOC2_S10b_T09_V10.0 13 11/18/12

2.1.3 .1 .3 Manage moderator accounts

Table 14: Process Description - Manage moderator accounts

Identifier UC-3: Manage moderator accounts Purpose Administrator can decide who is a moderator and edit account

info as needed Requirements CR-1: The client (administrator) should have the ability to add

moderator/contributor accounts CR-2: The client (administrator) should have the ability to delete moderator/contributor accounts

Development Risks

None

Pre-conditions Administrator has opened Manage Moderator Accounts page Post-conditions Moderator information/status has is modified in the database

unless the administrator left it unchanged

Table 15: Typical Course of Action - Manage moderator accounts

Seq# Actor’s Action System’s Response 1 On Manage Moderator Accounts

page, administrator clicks on "Add account"

2 System displays empty Edit Account Information form and gives control to "Edit Account Information" use case

Table 16: Typical Course of Action - Manage moderator accounts


page, administrator clicks on "Delete" next to an account

2 System displays yes/no dialog box asking whether moderator really wants to delete this account.

3 On the dialog box, administrator clicks on “Yes”

4 Account is deleted from account database; Manage Moderator Accounts page is displayed


SSAD_IOC2_S10b_T09_V10.0 14 11/18/12

Table 17: Alternate Course of Action - Manage moderator accounts


page, Administrator clicks on "Delete" next to an account

2 System displays yes/no dialog box asking whether administrator really wants to delete this account.

3 On the dialog box, administrator clicks on “No”

4 Account is not deleted from account database; Manage Moderator Accounts page is displayed


SSAD_IOC2_S10b_T09_V10.0 15 11/18/12

2.1.3 .1 .4 Login

Table 18: Process Description - Login

Identifier UC-4: Login Purpose Authenticate a privileged user Requirements CR-3: Administrator/Moderators/Contributors need to have

accounts to prevent abuse. Development Risks

We need to make sure that the correct privileges for each user are set

Pre-conditions Contributor is not logged on to the system and on Login page Post-conditions Contributor is signed on to the system with his/her privileges

(contributor, moderator or administrator) or login is rejected

Table 19: Typical Course of Action - Login

Seq# Actor’s Action System’s Response 1 On Login page, Contributor

enters username/password correctly and clicks “Submit”

2 On Login page, contributor clicks "Submit"

3 Contributor is logged into the system and role is changed accordingly

Table 20: Alternate Course of Action - Login

Seq# Actor’s Action System’s Response 1 On Login page, contributor

clicks on "Back"

2 User is not logged in and system displays page that was displayed before the login page was displayed


SSAD_IOC2_S10b_T09_V10.0 16 11/18/12

Table 21: Alternate Course of Action - Login


clicks on "Reset"

2 All values in form are erased in the form.

Table 22: Exceptional Course of Action - Login


enters username/password

2 Contributor clicks "Submit" 3 System validates username/password

combination and concludes it is incorrect

4 System displays red text on Login page saying that login was incorrect

2.1.3 .1 .5 Logout

Table 23: Process Description - Logout

Identifier UC-5: Logout Purpose Remove privileges and continue session as unprivileged user Requirements CR-3: Administrator/Moderators/Contributors need to have

accounts to prevent abuse Development Risks

None

Pre-conditions User is logged onto the system and system is displaying a page that needs privileges to be accessed

Post-conditions User is logged off the system and continues session without privileges


SSAD_IOC2_S10b_T09_V10.0 17 11/18/12

Table 24: Typical Course of Action - Logout

Seq# Actor’s Action System’s Response 1 On a page that needs privileges

to be accessed, user clicks "Log off" link

2 System logs out the privileged account 3 System regime timeline page


SSAD_IOC2_S10b_T09_V10.0 18 11/18/12

2 .1 .3 .1 .6 Edi t Account Informat ion

Table 25: Process Description - Edit Account Information

Identifier UC-6: Edit Account Information Purpose Change account information Requirements CR-3: Administrators/Moderators/Contributors need to have

accounts to prevent abuse Development Risks

None

Pre-conditions Moderator or administrator is on Edit Account Information page Post-conditions Account information is modified in the user information database

unless it was left unchanged

Table 26: Typical Course of Action - Edit Account Information

Seq# Actor’s Action System’s Response 1 On Edit Account Information

page, contributor, moderator or administrator edits account information in form field

2 On Edit Account Information page, contributor, moderator or administrator clicks "Submit"

3 Updated account information is committed to user database and control is returned to "Manage Contributor Account" use case if user is a moderator or "Manage Moderator Account" use case if user is an administrator


SSAD_IOC2_S10b_T09_V10.0 19 11/18/12

Table 27: Alternate Course of Action - Edit Account Information


page, contributor, moderator or administrator clicks "Return"

2 Control is handed back to returned to "Manage Contributor Account" use case if user is a moderator or "Manage Moderator Account" use case if user is an administrator

Table 28: Exceptional Course of Action - Edit Account Information


page, contributor, moderator or administrator leaves a mandatory field blank or fills it out obviously wrong (e.g. e-mail address with no “@”) and clicks “Submit”

2 On Edit Account Information page, contributor, moderator or administrator clicks "Submit"

3 System displays alert box saying which mandatory fields were left blank or filled out obviously wrong

4 On alert box, contributor, moderator or administrator clicks on “OK” or closes alert box

5 System displays Edit Account Information page


SSAD_IOC2_S10b_T09_V10.0 20 11/18/12

2.1.3.2 Submissions management

2 .1 .3 .2 .1 L is t Submiss ions / Recent Changes

Table 29: Process Description - List Submissions / Recent Changes

Identifier UC-7: List submissions / recent changes Purpose Check new submissions list Requirements CR-6: Moderators should be able to authorize submissions online Development Risks

Make sure the moderator is shown all submissions and changes that need attention

Pre-conditions One or more submissions are stored in the new submissions queue and moderator is on List Submissions / Recent Changes page

Post-conditions Moderator has seen overview and possibly processed one or more submissions

Table 30: Typical Course of Action - List Submissions / Recent Changes

Seq# Actor’s Action System’s Response 1 On Submissions Overview page,

moderator clicks on the title of a submission

2 Selected submission is shown on Individual Submission Review page and control is given to " Individual Submission Review " use case


SSAD_IOC2_S10b_T09_V10.0 21 11/18/12

2.1.3 .2 .2 Individual submission review

Table 31: Process Description -

Individual submission review

Identifier UC-8: Individual submission review Purpose Take action on a new submission Requirements CR-6: Moderators should be able to authorize submissions online

CR-7: The system shall send an acknowledgment email when a submission is received and another acknowledgment when the submission is accepted/rejected

Development Risks

None

Pre-conditions A new submission is available for review by a moderator and is displayed on the List Submissions / Recent Changes page

Post-conditions Moderator has reviewed the submission and taken action on it (accepted, rejected or edited it), the timeline is updated and the contributor who contributed the submission informed accordingly unless moderator has postponed action on the submission; An accepted submission is saved in the article database so that its individual parts can be retrieved within and outside of the system


SSAD_IOC2_S10b_T09_V10.0 22 11/18/12

Table 32: Typical Course of Action -


Seq# Actor’s Action System’s Response 1 On List Submissions / Recent

Changes page, moderator clicks on a listed submission

2 System displays Individual Submission Review page for the chosen submission

3 On Individual Submission Review page, moderator fills out the individual submission review form

4 Moderator clicks "Accept" button

5 Submission is inserted into the timeline in the location requested by contributor

6 System notifies contributor by e-mail that submission has been accepted

Table 33: Alternate Course of Action -





1 On Individual Submission Review page, moderator clicks "Edit"

2 Article editor is displayed


SSAD_IOC2_S10b_T09_V10.0 23 11/18/12






3 On Individual Submission Review page, moderator fills out the individual submission review form

4 Moderator clicks "Reject" button 5 Submission is deleted from the

submissions queue and article database 6 Contributor is notified by e-mail


SSAD_IOC2_S10b_T09_V10.0 24 11/18/12

2.1.3 .2 .3 Comment on ar t ic le

Table 35: Process Description - Comment on article

Identifier UC-9: Comment on article Purpose Create or improve contents of an article Requirements CR-4: Contributors can submit bibliographic data for inclusion in

the timeline Development Risks

None

Pre-conditions Contributor is logged on to the system and on “Comment on Article” page

Post-conditions Comment was submitted to moderator unless contributor canceled submission

Table 36: Typical Course of Action - Comment on article

Seq# Actor’s Action System’s Response 1 On “Comment on Article” page,

contributor edits contents of comment

2 On “Comment on Article” page, contributor clicks “Submit”

3 Comment is added to database, awaiting approval by Moderator

Table 37: Exceptional Course of Action - Comment on article

Seq# Actor’s Action System’s Response 1 On “Comment on Article” page.

contributor does not fill out “Regarding” and/or “Comment” field and then clicks “Submit”

2 System shows alert box reminding reader to at fill out the required fields that were left unfilled ("Regarding" and or "Comment")

3 On alert box, contributor clicks on “OK” or closes alert box

4 System displays Comment on Article page


SSAD_IOC2_S10b_T09_V10.0 25 11/18/12

2.1.3 .2 .4 Edi t Ar t ic le

Table 38: Process Description - Edit Article

Identifier UC-10: Edit article Purpose Create or improve contents of an article Requirements CR-4: Contributors can submit bibliographic data for inclusion in

the timeline CR-5: Contributors should be able to preview their uploaded contribution

Development Risks

None

Pre-conditions Contributor or moderator has clicked on “Modify Description” link on an article page

Post-conditions Contents of the article are changed unless moderator left them unchanged

Table 39: Typical Course of Action - Edit Article

Seq# Actor’s Action System’s Response 1 On the Edit Article page in the

text area of the Edit Article form, contributor edits contents of submission

2 On the Edit Article page, contributor or moderator clicks on “Submit”

3 System validates input as complete 4 Submission is saved in the database; If

Contributor is a moderator or administrator, submission is placed in the timeline. Otherwise, submission is marked in the database as being placed in the new submissions queue and shown in the timeline only to the contributor.


SSAD_IOC2_S10b_T09_V10.0 26 11/18/12

Table 40: Exceptional Course of Action - Edit Article

Seq# Actor’s Action System’s Response 1 On the Edit Article page in the

text area of the Edit Article form, contributor edits contents of submission

2 On the Edit Article page, contributor or moderator clicks on “Submit

3 System validates input as incomplete 4 System shows error dialog box telling

contributor which fields still need to be filled out

5 Contributor clicks “OK” on error dialog box or closes it

6 System displays Edit Article page


SSAD_IOC2_S10b_T09_V10.0 27 11/18/12

2.1.3 .2 .5 Add Source


Add Source

Identifier UC-11: Add Source Purpose Add a new citation source to the system so a moderator can add it

to the timeline Requirements CR-4: Contributors can submit bibliographic data for inclusion in


None

Pre-conditions Contributor is on a regime or event description box and has clicked on "Add Source"

Post-conditions A new source has been added to the moderator queue unless the submission was invalid or cancelled

Table 42: Typical Course of Action - Add Source

Seq# Actor’s Action System’s Response 1 Contributor edits form fields for

new source on the "Add Source" form

2 Contributor clicks "Submit" 3 System validates input as being correct

(at least Title and Author fields are filled out)

4 New source is marked in the database as being in the submissions queue


SSAD_IOC2_S10b_T09_V10.0 28 11/18/12

Table 43: Exceptional Course of Action - Add Source

Seq# Actor’s Action System’s Response 1 Contributor edits form fields for

new source on the "Add Source" form

2 Contributor clicks on "Submit" 3 System validates input as being

incorrect (at least Title or Author field is missing)

4 System shows error dialog box saying which fields where left blank or filled out incorrectly

5 Reader clicks "OK" on error dialog box or closes error dialog box

6 System displays New citation form


SSAD_IOC2_S10b_T09_V10.0 29 11/18/12

2.1.3 .2 .6 Modi fy Source


Modify Source

Identifier UC-12: Modify Source Purpose Modify a citation source in the system so a moderator can change

it in the timeline Requirements CR-4: Contributors can submit bibliographic data for inclusion in


None

Pre-conditions Contributor has clicked on "Modify Source" on a regime or event description box

Post-conditions A modified source has been added to the moderator queue unless the submission was invalid or cancelled

Table 45: Typical Course of Action - Modify Source

Seq# Actor’s Action System’s Response 1 On a regime or event description

box, contributor clicks on "Modify Source"

2 System displays modify source form with form fields filled in with values of the source selected by the user

3 Contributor edits form fields for modified source correctly (fills out at least Title and Author fields)

4 Contributor clicks "Submit" 5 Modified source is submitted to

moderator queue in the database


SSAD_IOC2_S10b_T09_V10.0 30 11/18/12

Table 46: Exceptional Course of Action -

Modify Source

Seq# Actor’s Action System’s Response 1 System displays modify source form

with form fields filled in with values of the source selected by the user

2 Contributor edits form fields for modified source incorrectly (leaves Title and Author fields blank or fills them out implausibly (e.g. only one character))

3 Contributor clicks on "Submit" 4 System shows error dialog box saying

which fields where left blank or filled out incorrectly

5 Reader clicks "OK" on error dialog box or closes error dialog box

6 System displays New Citation form


SSAD_IOC2_S10b_T09_V10.0 31 11/18/12

2.1.3 .2 .7 Read Art ic le


Read Article

Identifier UC-13: Read Article Purpose View an article and possibly request editing the viewed article,

adding a new article or to write a comment regarding the article Requirements CR-4: Contributors can submit bibliographic data for inclusion in


None

Pre-conditions Reader has Timeline website open in browser Post-conditions Reader has the same article open in browser and possibly

submitted an edited version of this article or a new article or a comment

Table 48: Typical Course of Action -

Read Article

Seq# Actor’s Action System’s Response 1 On regime or event description

box, reader clicks on "Add Source" link

2 Control is handed over to "Login" use case. If reader has successfully logged onto the system, control is handed over to "Add Source" use case, where reader acts as contributor


SSAD_IOC2_S10b_T09_V10.0 32 11/18/12


Read Article


box, reader clicks on "Modify Source" link

2 Control is handed over to "Login" use case. If user has successfully logged onto the system, control is handed over to "Modify Source" use case, where reader acts as contributor


Read Article


box, reader clicks on "Modify Description" link

2 Control is handed over to "Login" use case. If user has successfully logged onto the system, control is handed over to "Modify Description" use case, where reader acts as contributor


SSAD_IOC2_S10b_T09_V10.0 33 11/18/12

2.1.4 Modes of Operation No modes of operation are planned for the system. While different actors will have different privileges, there will not be a situation where the same controls will give different responses.

2.2 System Analysis Rationale We have analyzed the current system as well as the new system desired by the client and come up with three kinds of operational stakeholders: Site staff: This is comprised of the administrator and the moderators. They manage how content is added to and modified on the site. With the new system, this will be accomplished by only acting within the system and using only the operations provided by it as opposed to directly editing and manipulating files. The administrator as well as the moderators will connect to the site over the internet or the USC intranet using web browsers exclusively. No access through low-level tools (such as shells or sftp clients) will be required in order to use the new system. Users: The people who read the content on the site or contribute content to it, but do not make any ultimate decisions on its content or direction. To the system, they are categorized through their roles as readers and the contributors. Readers and contributors will connect to the site over the internet using web browsers exclusively. Maintainer: The person who is part of the library IT staff and who keeps the site and its data up and running from an IT perspective after the new system has been deployed. The maintainer has no stake in the content of the site (i.e. he can perform his role with the same level of quality whether or not he ever actually reads any article on the site that is managed by the system). The maintainer can connect to the site over the internet or over the USC intranet using web browsers but will also have direct access to the underlying software using low-level tools (e.g. shells, sftp). The maintainer will also have physical access to the site. While there will be no external site interfacing with the new system as part of its core functionality, the system will be sending backups of its persistent data to a data backup system on a regular basis.USC ITS has committed to doing daily incremental backups as well as weekly full backups of the data on the site. These will be managed outside the system.


SSAD_IOC2_S10b_T09_V10.0 34 11/18/12

3. Technology-Independent Model

This document has no technology-independent model because the technological foundation for the representation of historical data in the current and future system, MIT SIMILE timeline, has already been chosen by the client and therefore the new system needs to be shaped around it.


SSAD_IOC2_S10b_T09_V10.0 35 11/18/12

4. Technology-Specific System Design

4.1 Design Overview The new system will build on the existing two tier client / web server architecture based system and transform it into a three tier architecture. It will add a servlet container and a database to the previous architecture while moving from a pure web server to a servlet container that is also used as a web server. MIT SIMILE Timeline will continue to be the focal point of the system. The entire GUI will be realized using HTML pages and their elements, particularly forms. JavaScript will be used wherever input can be validated without needing complex business logic, e.g. when submissions need to be checked for empty fields, missing format elements and other immediately obvious errors. The back end business logic for the account management and article submissions will be run using Java Servlets that access a MySQL database. These servlets will be compiled from JSPs or written directly in Java.


SSAD_IOC2_S10b_T09_V10.0 36 11/18/12

4.1.1 System Structure

Figure 4: Hardware Component Class Diagram


SSAD_IOC2_S10b_T09_V10.0 37 11/18/12

Figure 5: Software Component Class Diagram


SSAD_IOC2_S10b_T09_V10.0 38 11/18/12

Figure 6: Deployment Diagram


SSAD_IOC2_S10b_T09_V10.0 39 11/18/12

Table 51: Hardware Component Description

Hardware Component Description Networked Computer A computer that is connected to other networked computers

through the internet. In our system, every computer will be networked in this manner.

Application Server A networked computer which provides applications to workstations. In our system, this will be the server our software will be deployed on.

Workstation A networked computer which is used to access services on the internet. In our system, this will be computers used by people at home or in an office to interact with the timeline application server.

Table 52: Software Component Description

Software Component Description User Interface The HTML pages and forms that users of the system interact with

directly Account Management Module

The part of the system that keeps track of user account information and status, authenticates users and informs other components (such as the Submissions Handling Module) about the privileges of a given user

Submission Handling Module

Keeps track of and processes submissions of content to the system

Database Handling Module

Interacts directly with the MySQL database via SQL and provides data storage, retrieval and query functionality to the other modules as needed. All other modules are database-agnostic.

Migration Manager Module

One-time use converter that migrates the existing content from the old system into the MySQL database of our new system

MIT SIMILE timeline A collection of JavaScript objects and methods that serve to represent historical data graphically in a timeline


SSAD_IOC2_S10b_T09_V10.0 40 11/18/12

Table 53: Supporting Software Component Description

Support Software Component Description MySQL A relational database management system Apache Tomcat A servlet container


SSAD_IOC2_S10b_T09_V10.0 41 11/18/12

4.1.2 Design Classes

4.1.2.1 Interface Classes

Figure 7: Design Class Diagram


SSAD_IOC2_S10b_T09_V10.0 42 11/18/12

Table 54: Design Class Description

Class Type Description Timeline Main Page Boundary Main page of the timeline site Article Page Boundary Shows an individual article Edit Article Page Boundary Page with a form to edit or create an article Comment on Article Page Boundary Page with a form to comment on an article Add Source Page Boundary Page with a form to add a source Modify Source Page Boundary Page with a form to modify a source Request Contributor Account Page

Boundary Page with a form to request a contributor account

Manage Contributor Accounts Page

Boundary Page with a list of contributor accounts and buttons to modify or delete these accounts

Manage Moderator Accounts Page

Boundary Page with a list of moderator accounts and buttons to modify or delete these accounts

Login Page Boundary Page with a login form Logoff Page Boundary Page with a logoff confirmation form Edit Account Information Page Boundary Page with a form to edit account information List Submissions / Recent Changes Page

Boundary Shows a list of submissions and recent changes

Individual Submission Review Page

Boundary Shows an individual submission for review


SSAD_IOC2_S10b_T09_V10.0 43 11/18/12

Figure 8: Login Class Diagram


SSAD_IOC2_S10b_T09_V10.0 44 11/18/12

4.1.3 Process Realization The Process Realization diagrams show sequences for the most risky use cases. These are the use cases that, if implemented wrong, would cause the whole system or major parts of it to fail or at least to not work as expected (as opposed to those use cases whose faulty implementation would be contained to themselves).

4.1.3.1 Login This is one of the riskiest use cases because all use cases that have privileged actors rely on a correctly implemented login.

Figure 9: Process Realization Diagram - Login


SSAD_IOC2_S10b_T09_V10.0 45 11/18/12

4.1.3.2 Read Art icle This shows the interaction of our system with MIT SIMILE timeline, which is what our capability of displaying articles to users rests on.

Figure 10: Process Realization Diagram - Read Article

4.1.3.3 List Submissions / Recent Changes This is one of the most risky use cases because the moderator will take the articles he/she needs to work on from this list. If it were to be implemented wrong, some necessary work may not get done by the moderator.


SSAD_IOC2_S10b_T09_V10.0 46 11/18/12

Figure 11: Process Realization Diagram - List Submissions / Recent Changes


SSAD_IOC2_S10b_T09_V10.0 47 11/18/12

4.2 Design Rationale Our client has requested us to extend the functionality of his existing timeline system and to make working with his new system more efficient and community-based while being able to access all functionality using a GUI. Our solution for this is to provide the existing and newly added functionality using Java Servlets on an Apache Tomcat server with a MySQL database backend while leaving MIT SIMILE timeline in place. The existing functionality (displaying the timeline) will be provided through Apache Tomcat based Java Servlets and MIT SIMILE while using MySQL to hold the data. For this, the existing data will be migrated into a relational MySQL database. The new functionality (account management, submissions management and GUI-based positioning of articles in the timeline) will be realized by software components that will run as Java Servlets on Tomcat. Below is our rationale as to what the NDI components are that we chose and did not chose to realize the new system and how they interact.

4.2.1 NDI components

4.2.1.1 Chosen NDI components Software Component

Description Purpose

MIT SIMILE Timeline

Software system that represents data graphically in a timeline

Represent data about historic events, people and regimes

MySQL Relational Database Management System

Store user account information and metadata pertaining to the content of the timeline

Apache Tomcat Servlet container Provide facility to run Java Servlets which will be programmed by the team (Submissions Manager, Account Manager, Database Manager)

Internet Explorer, Firefox, Safari

Web browser Web front end for users of the existing and new timeline systems


SSAD_IOC2_S10b_T09_V10.0 48 11/18/12

4.2.1.2 NDI components that were not chosen

4.2.1 .2 .1 PHP Two NDI components that could have provided some functionality for the system (Submissions Manager, Account Manager), but were not chosen, are the PHP language and its corresponding Apache web server extension. In the first semester of this project, this choice was made for two reasons: 1. It was felt that while PHP can provide the required functionality, using Apache Tomcat and Java Servlets would be a better fit if the system needs to scale upwards. 2. The team has more experience using Apache Tomcat and Java Servlets. This reason could have potentially become irrelevant if the project would have been transferred to another team or the team members who have more experience with Tomcat and Servlets than with PHP would have left the team before the start of development in the second semester. However, as it actually turned out, all the team members that were relevant to this decision are still with the team as of the second semester.

4.2.1 .2 .2 Apache Web Server The current system will be migrated to the Apache Tomcat server, which will serve both static and dynamic HTML pages. While in a high performance context it may make sense to run both the Apache web server and Apache Tomcat in parallel, it was felt here that the modest performance requirements of the timeline system do not require that kind of setup. This will still hold true for any reasonably expected evolution of the system during its lifetime.

4.2.1.3 Interfaces Since our new system will be an extension of an existing system, the new system will interface with the same systems as the existing system. These systems the internet connected workstations of web users and the networked workstations of the site staff and the maintainers. In addition to that, there will be a need to interface with a data backup system and a database running on the same server as Apache Tomcat. The figure below shows the integration of the software components comprising the new system. These are split into three major groups: Client-side (Browsers and their underlying operating systems), Web servers and their business logic (Apache Tomcat with a Java SDK and underlying operating systems) and the database back-end.


SSAD_IOC2_S10b_T09_V10.0 49 11/18/12

While iStudio 0.21 has been used to produce the figure shown here, we have not used it to determine mismatches and incompatibilities. The reason for this is that its reports showed a large amount of mismatches between components that are well-known to work with each other. Fixing these non-existent mismatches would have required a large amount of editing the XML descriptions of components, which would have added no value to our project. We also feel that figure shows only connections between components that are well-known to work with each other. These are as follows: Laterally (integration of different components within one physical system):

x Web browsers are known to work on Windows, Mac and other client platforms.

x Combinations of Apache Tomcat with Servlets and Java EE are known to work together on Windows Server 2008.

x MySQL is known to work on Windows Server 2008.

Vertically (integration of different components between several physical systems):

x Web browsers such as Safari, Internet Explorer and Firefox are known to work with web servers or Java servlet containers using the HTTP protocol such as Apache Tomcat.

x Tomcat is known to work with MySQL using the JDBC connector that comes with

Tomcat.


SSAD_IOC2_S10b_T09_V10.0 50 11/18/12

Figure 12: iStudio diagram of the new system


SSAD_IOC2_S10b_T09_V10.0 51 11/18/12

4.2.2 Connectors Component 1 Component 2 Connector Web browser Apache Tomcat Built-in MIT SIMILE Timeline Apache Tomcat JavaScript source of MIT

SIMILE Timeline is referenced in HTML pages

Apache Tomcat MySQL JDBC Because all required connectors between components are either built into the components (Apache Tomcat, web browsers), URLs are being referenced (Apache Tomcat/SIMILE) or the connectors are part of the distribution of the NDI component (Apache Tomcat/MySQL), no connectors between the components will need to be programmed by our team.


SSAD_IOC2_S10b_T09_V10.0 52 11/18/12

5. Architectural Styles, Patterns and

Frameworks

Table 55: Architectural Styles, Patterns, and Frameworks

Name Description Benefits, Costs, and Limitations Three-tier Architecture

Three-tier architecture is an architectural style and a design pattern that separates the presentation of data, business logic and the data itself into tiers that, in the case of our system, reside on two different systems and are managed with three different applications:

x All data is presented within web browsers (Internet Explorer, Mozilla Firefox, Apple Safari) on networked machines that will in most cases be offsite.

x The business logic platform will be Apache Tomcat running on Windows Server 2008.

x The data will be managed using a MySQL database running on Windows Server 2008 on the same virtual machine as Apache Tomcat (this is based on the setup of the physical system, MySQL could just as well run on a different machine without causing any detriment to the functionality of our system)

Benefits: x Individual tiers can be modified

independently from the rest of the system without breaking it (less coupled than a monolithic architecture)

x Enforces separation of data, business logic and presentation on the developers, thereby making them create code that is more easily maintained because its functionality is more easily understood due to its impact being more localized within the system.

Cost:

x There is no specific cost required in order to use three-tier architecture.

Limitations:

x Potential limited speed losses when data which is transferred between the browser and the database and vice versa has to pass through the separate business layer and has to be replicated in the database and the servlet container

system and software architecture description - … system design ... patterns and frameworks ......

Documents