Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

Poetic Concordance, Enterprise EditionA rose by any other name would still be in this dictionary.SM

5/14/2023 1 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

Requirements Analysis Document (RAD)

1 Introduction1.1 Purpose of the systemYou have responsible for developing a concordance system for the 154 Shakespearean Sonnets. The text for these poems may be found in numerous places. Here is one:

Sonnets 1 – 50Sonnets 51 – 100Sonnets 101 – 154

Note that the full text of the poems will be made available to you, one per file, within a single ZIP file.

A concordance is “an alphabetical index of all the words in a text or corpus of texts, showing every contextual occurrence of a word”. That is, a researcher would like to know when a poet used certain words, and in what context these words were used. Instead of printing this information in a fixed book format, you will develop (a) a command-line driven application; and (b) an interactive graphical application that will enable researchers to search for words within these Shakespearean sonnets and retrieve the context where the words are used.

1.2 Scope of the systemYour application must be able to construct a concordance for any collection of text files that exist in a directory on your computer. The format of the individual poem files is discussed in section 3.1.1. The full set of poems within a directory is known as the poet’s “body of work” (BOW) and the directory itself is called the “directory of work” (DOW).

You will develop two applications. The first, known as the Batcher, will be a command-line driven utility to process concordance queries and report its results. The second, known as the Viewer, enables researchers to browse through the BOW and locate poems by name, as well as browse through the concordance of the BOW by viewing the contexts of words entered in the GUI.

1.3 Objectives and success criteria of the projectThe success of the application depends upon meeting the following core set of objectives

Develop Batcher capable of processing a concordance query over a BOW with 2,000 total lines of poetry within 500 milliseconds. If the BOW has k times as much lines of poetry, then the query must complete within 500*k milliseconds.

All major capabilities supported by Viewer are to be supported as well by Batcher, although some changes will need to be made due to the text-based interface

5/14/2023 2 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

Viewer shall present user with navigational aids for viewing the results of concordance queries.

In Viewer, user will be able to “drill down” to the original poem while viewing the results of the concordance query (and the words from the concordance query shall be highlighted in some way in the original poem).

In Viewer, user will be able to browse the poems by title and see the contents of any poem in the BOW.

User should be able to select which DOW to use when executing the Batcher and Viewer, thus enabling multiple concordances to be available.

1.4 Definitions, acronyms, and abbreviationsBOW The Body of Work for a poet. Represents the full set of poems found in the

directoryDOW The Directory within which the Body of Work may be found. Each poem is

stored individually within its own text file. Concordance An alphabetical index of all the words in a text or corpus of texts, showing

every contextual occurrence of a wordBatcher A batch-oriented tool that enables researchers to submit concordance queries

to see where certain words were used in a BOW, and in what context.Viewer A tool that enables researchers to browse a poet’s BOW and submit

concordance queries to see where certain words were used, and in what context.

Context A set of three lines that describes the location of a particular word within a poem. The middle line contains the query target. The first line and the third line represent the “neighboring” lines in the poem. If the query target line is either the first line in the poem or the last line in the poem, then the context will only contain two lines (either 1st two or last two in the poem).

pf Suffix of the file which contains an individual poem in the DOW. Stands for “poem file”.

whitespace A separating character between words of poems. The only whitespace character shall be a single space ‘ ’ which takes the place of any number of repeated spaces or tabs.

Punctuation The following punctuation marks are ignored in poems and never appear as a keyword in the concordance: “~`!@#$%^&*()_=+{[}]\|:;”<,>./?”. The astute reader will note these are the same non-alphanumeric characters found on a standard American style keyboard. Note that the two traditional punctuation characters omitted above are (-) for hyphenated words and (‘) which deals with contractions such as “don’t” and “won’t”.

Administrator Individual responsible for preparing DOW.Researcher Individual who invokes the Viewer to browse the DOW and issue

concordance queries over the poems in the DOW.Query A concordance query searches for a single target word in the BOW and

returns a set of contexts showing the target word in use in the poems. Note that the query is only valid if the target word is not a common word.

Join Query A set of words that all must appear within two lines of each other. In essence, a join query combines the results of individual queries.

Common word A common word has the property that: (a) it occurs in more than 80% of the poems in the BOW; and (b) in these poems it appears at least twice in each poem.

5/14/2023 3 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

1.5 ReferencesConsider the http://www.opensourceshakespeare.com/concordance system, which is a much more powerful web-based system than anything you are really being asked to accomplish as part of this assignment. Nonetheless, you should get a feel for the type of interaction that is being considered.

1.6 Overview

2 Current SystemNo system is in place.

3 Proposed System3.1 OverviewThe system is divided into two parts. A system administrator is responsible for constructing the BOW within a specific DOW. This is done using available operating system commands to copy, rename, and delete files within a directory. You are not responsible for providing any assistance in this matter.

The input files to be provided in the DOW will conform to the Poem file format which is described next.

3.1.1 Poem file format

All poems that exist within the BOW are found in the DOW as a plain text file. The name of the file is not relevant, but the suffix must end in a “.pf” (capitalization is not important) which stands for “poem file”. An example poem file that conforms to the PF format is shown in Figure 1.

Spring Days3

Listen! A frogJumping into the stillnessOf an ancient pond!

Figure 1: Sample Poem using pf format.

The first line contains the title of the poem. If the original poem title as written by the poet is intended to cover multiple lines, then the character ‘\’ shall appear in the title in its place. Thus the poem.titled:

“This is not the beginningBut the end”

5/14/2023 4 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

shall be represented by the string “This is not the beginning\but the end” which will appear in its entirety on the first line. Note that the second line of the PF file contains a long integer which will declare the number of lines N of the poem. The third line of the PF file shall always be blank. Note that the total number of lines in the file will be N + 3.

There are no restrictions on the number of characters that will fit on a single line, but each of the N lines in which the poem is represented shall end in a ‘\n’ character. There may be arbitrary whitespace characters in the poem, and individual words are always separated by whitespace or basic punctuation characters. Once again, note that the single apostrophe quote (’) and the hyphenation mark (-) are not punctuation characters.

The contents of the poems are strictly represented using ASCII characters, despite the serious limitation this implies for multicultural poems.

Note please see [cite] for an explanation as to why this poem file format is woefully inadequate! But that is not our problem.

3.2 Functional RequirementsThere are several actors in the system:

Administrator Researcher

3.2.1 Administrator

An Administrator can: Update the poem files that belong to a DOW using standard operating system commands;

this includes adding or deleting poem files. Maintain multiple DOWs as necessary.

Since the Administrator’s actions are all outside of the two applications developed for this homework assignment, no use cases are expected

3.2.2 Researcher

A Researcher can: Use the Batcher to submit a concordance query for a non-common word and view the

results directly as output to the console. Use the Viewer to browse the BOW and view any poem by name Use the Viewer to submit a concordance query and view the returned contexts. From an

individual context, the researcher should be able to quickly navigate to view the original poem in which the target word is labeled in a way that stands out from the original poem.

Use the Viewer to submit a join query and view the returned contexts. Regardless of interface, the researcher must be able to:

o Determine the number of poems in the BOWo Show the full list of the common words in the BOWo Determine the number of unique, non-common words in the BOW

3.2.3 Join queries

5/14/2023 5 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

A join query represents a set of words that all must appear within two lines of each other. In essence, a join query combines the results of individual queries. The best way to understand a join query is to consider how to combine the output of two independent target queries:

gilded silencePoem LV Not marble, nor the gilded monuments Of princes, shall outlive this powerful rhyme;

Poem LXVI

And purest faith unhappily forsworn, And gilded honour shamefully misplac'd, And maiden virtue rudely strumpeted,

Poem CI

Excuse not silence so, for't lies in thee To make him much outlive a gilded tomb And to be praised of ages yet to be.

Poem LXXXIII Speaking of worth, what worth in you doth grow. This silence for my sin you did impute, Which shall be most my glory being dumb;

Poem LXXXVI Which nightly gulls him with intelligence, As victors of my silence cannot boast; I was not sick of any fear from thence:

Poem CI Because he needs no praise, wilt thou be dumb? Excuse not silence so, for't lies in thee To make him much outlive a gilded tomb

If the join query “gilded silence” was submitted, then only Poem CI would appear in the output:

gilded silencePoem CI

Excuse not silence so, for't lies in thee To make him much outlive a gilded tomb And to be praised of ages yet to be.

To be precise about the distances, the following four lines of poem I would not be a result of the join query “a b c” because ALL words are not within two lines of each other (specifically, fairest is three lines away from memory.

fairest riper memoryPoem CI

From fairest creatures we desire increase, That thereby beauty's rose might never die, But as the riper should by time decease, His tender heir might bear his memory:

One should be able to reuse the graphical interface as is. Specifically, when the researcher enters in the “target query” using the existing interface, this could be overloaded to allow a researcher to enter in a set of words”. Note that common words must be automatically discarded from the join query prior to its execution.

3.3 Nonfunctional Requirements3.3.1 Usability

The Batcher should be executable entirely from the command line without any direct user input from the console. That is, one should be able to automate the execution of the Batcher.

5/14/2023 6 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

The Viewer must be written using one of the prevailing Java GUI standards, either Java AWT, Java Swing, or Eclipse’s SWT toolkit.

All functionality (except for the interactive ones, such as “drill down”) available to the Viewer must be made possible to the Batcher.

3.3.2 Reliability

While the Batcher and Viewer are executing, any underlying changes by the administrator to the BOW should have no impact on the execution of the system. That is, poems can be added, removed, or renamed and the system should be able to continue functioning, albeit with somewhat limited functionality. For example, while the Viewer is currently running, and a concordance query shows the results of a search, the underlying poem which contains that search word could be deleted from the BOW. If this happens, the “drill down” enabled by the GUI would fail, and the Viewer must properly respond to this situation. Note this is only one example of various such “concurrent access scenarios”.

3.3.3 Performance

The programs are intended for use with small concordances, say with less than 1,000 poems and a total of 10,000 lines. Any use that exceeds this expectation may prevent the system from achieving its target performance measures (although you should try to ensure that the performance degrades “gracefully”)

3.3.4 Supportability

None.

3.3.5 Implementation

The implementation shall be in Java, although the GUI can use any of the standard GUI framework libraries.

3.4 System Models

3.4.1 Scenarios

In total, the following scenarios capture all required elements of the system. These are provided to you by the professor. If they change during the course of the project, the revised versions will be posted and clearly marked.

3.4.1.1 Administrator prepares BOW within DOWThe following steps are required to set the system up to be ready for processing:

Scenario name prepareDOWVersion 1.0 (Feb-26-2008)Participating George : Administrator

5/14/2023 7 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

actor instancesFlow of Events 1. Create directory “Sonnets” to be the DOW of Shakespeare’s Sonnets

2. Within directory, unpack the ZIP file containing all 154 of the poems.

3.4.1.2 Researcher launches Viewer to browse poems “User shall be able to issue a concordance query directly from a poem.”“User shall be able to issue a concordance query directly from another concordance query”“User shall not be able to issue a concordance query using a common word”

Scenario name launchViewerVersion 1.0 (Feb-26-2008)Participating actor instances

Will: Researcher

Flow of Events 1. Launch Viewer2. Select option to open DOW and browse to Shakespeare’s sonnets

directory on computer3. Select option to view the available poems by title in the DOW4. Find “Sonnet LV” (number 55) and open the poem.5. Read the first three lines…

Not marble, nor the gilded monumentsOf princes, shall outlive this powerful rhyme;But you shall shine more bright in these contents

6. Select word “gilded” and perform a concordance query7. Review the output:

LV

Not marble, nor the gilded monuments Of princes, shall outlive this powerful rhyme;

LXVI

And purest faith unhappily forsworn, And gilded honour shamefully misplac'd, And maiden virtue rudely strumpeted,

CI

Excuse not silence so, for't lies in thee To make him much outlive a gilded tomb And to be praised of ages yet to be.

8. Select word “and” and perform concordance query9. User is told that “and” is a common word and not allowed by query10. User quits the program

5/14/2023 8 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

3.4.1.3 Researcher finds out statistics“Viewer can execute even while underlying DOW changes”

Scenario name findStatisticsVersion 1.0 (Feb-26-2008)Participating actor instances

Will : Researcher, George: Administrator

Flow of Events 1. Launch Viewer2. Select option to open DOW and browse to Shakespeare’s sonnets

directory on computer3. Review statistics to see there are 154 poems, 7,695 unique words

(NOTE I AM MAKING THIS NUMBER UP HERE), and 19 common words (I AM MAKING THIS NUMBER UP)

4. George finds an unpublished sonnet number 155 (CLV) and updates the DOW to include the “CLV.PF” file

5. Will once again reviews statistics and sees there are still 154 poems in the system.

6. Will exits Viewer7. Will relaunches Viewer8. Select option to open DOW and browse to Shakespeare’s sonnets

directly on computer9. Review statistics to see there are 155 poems, 7,707 unique words

(MAKING THIS UP), and 19 common words (MAKING THIS UP).

3.4.1.4 Researcher seeks word that appears in numerous poemsViewer shall present user with navigational aids for viewing the results of concordance queries.”

Scenario name queryLargeDataSetVersion 1.0 (Feb-26-2008)Participating actor instances

Will : Researcher

Flow of Events 1. Launch Viewer2. Select option to open DOW and browse to Shakespeare’s sonnets

directory on computer3. Submit concordance query for “beauty”4. Review output and see that 68 poems use this word.

II

When forty winters shall besiege thy brow,And dig deep trenches in thy beauty's field,Thy youth's proud livery so gazed on now,…

5. Scroll to review several more on the available screen, but then select to go to the next page to review more. There is a limit to the number of

5/14/2023 9 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

poem context results per page.6. View two more pages, then skip to view the last one. Then skip back to

view the first page.

3.4.1.5 Researcher uses Batch program“All functionality (except for the interactive ones, such as “drill down”) available to the Viewer must be made possible to the Batcher.”

Scenario name executeBatchRunVersion 1.0 (Feb-26-2008)Participating actor instances

Will : Researcher

Flow of Events 1. Launch Batcher with command line arguments to locate Shakespeare’s sonnets directory and request concordance query for the word “beauty”.

2. The 68 contexts for the word are output3. Launch Batcher with command line arguments to locate

Shakespeare’s sonnets directory and request to review statistics for the DOW.

4. The statistics are output, showing 154 poems, 7,695 unique words (NOTE I AM MAKING THIS NUMBER UP HERE), and 19 common words (I AM MAKING THIS NUMBER UP)

5. Launch Batcher with command line arguments to locate Shakespeare’s sonnets directory and view poem “LV.PF”

6. The output of the poem appears, starting with the following lines:

Sonnet LV

Not marble, nor the gilded monumentsOf princes, shall outlive this powerful rhyme;But you shall shine more bright in these contents…

3.4.2 Use case model

You will devise appropriate use cases as part of the assignment, so this section is intentionally blank.

3.4.3 Object model

You will devise the appropriate analysis object model. Focus only on Class Diagrams.

3.4.4 User interface – navigational paths and screen mock-ups

You will devise the appropriate GUI mock-ups.

5/14/2023 10 of 11

Requirements Analysis Document (RAD) Poetic ConcordanceVersion 1.0 [Feb-26-2008]

4 Test PlanYou are responsible for providing documented evidence that you have fully tested the classes which you design and implement. There are two tools that you will use for this. The first is the general purpose (and wildly popular) JUnit test framework, which is integrated into Eclipse. The second is a special Eclipse plugin (which only works with JUnit 3.8.1 I believe) called Coverlipse. Coverlipse will do code coverage analysis of your test cases to detect when you have code that has not been executed by any of your test cases.

When you submit your final deliverables you will produce a report showing the full code coverage statistics for your classes (which should be as close to 100% as you can reasonably achieve).

At a minimum, you will need a JUnit test case for each of the classes you develop. Having JUnit test cases for GUIs is not really helpful and you should focus instead on the ability to write JUnit test cases for boundary (i.e., model) classes and the controllers.

5 DocumentationYour code must include with sufficient documentation within the code. Follow the JavaDoc coding standard that is supported by Eclipse and expected by nearly everyone reading Java code. See code examples for the template you are to use.

6 ImplementationYour fully implemented solution must be provided with a README file that explains how to run the Viewer and the Batcher, as well as any expectations you may have on the environment on which you execute.

I will execute your code based upon your instructions and evaluate it accordingly. Please provide your evaluation of whether your final coded system achieves the success criteria listed in Section 1.3.

7 Change HistoryAs this document changes, it will be made available with Microsoft Track Changes turned “on” so you will be able to see all the updates that have occurred.

Version Description20080227.0904 Initial Version released to the class20080311.1241 Additional Requirements to be satisfied

5/14/2023 11 of 11