COM 1205 Assignment #6.
Assigned:  Tuesday, 29 February 2000
Due:       Tuesday, 7 March 2000

Working in small teams that are assigned by the instructor,
you will design and code an implementation in Java of the
Caesar module that is specified below, and link it to code
provided by the instructor that will result in a complete
first version of the cryptanalysis program that is capable
of breaking Caesar ciphers (as well as some others, perhaps).

Collaboration between members of different teams is forbidden.
Each team is responsible for keeping its design and code hidden
from other teams.  Part of each team's grade will be determined
by how well the team hides its code, and part of the grade will
depend upon the quality of the implementation.  A team that
resolves the security issues and submits an implementation of
the specified module that the instructor considers acceptable
for use in a large software project will earn an A.

The instructor will designate one member of each team as the
lead programmer for that team.  The lead programmer is
responsible for submitting the team's work, and has the final
say concerning all design, coding, and testing decisions.  The
lead programmer is also responsible for dividing the team's work
among its members, and for scheduling team meetings at times
that are convenient for the team.  The other members of the team
are responsible for advising the lead programmer, for reviewing
the team's design, code, and tests, and for any other teamwork
that may be assigned by the lead programmer.

All members of a team will receive the same grade.

The lead programmer is responsible for turning in the team's
work before 4 pm on the due date by sending electronic mail to

    will@ccs.neu.edu

with subject

    assignment #6

and a body that consists of the following, in the order shown:

    1.  The names of the team members.
    2.  Any remarks that the lead programmer wishes to make to
        the instructor concerning the team's work.
    3.  A line consisting of exactly 50 hyphens.
    4.  The code for Caesar.java.

Late assignments may be discounted, and very late assignments
may be discarded.

--------------------------------------------------

Specification of the Caesar module.

Caesar is a concrete data type.  The Caesar CDT shall be
implemented in Java using JDK 1.2.  The code for this
implementation shall be in the experts.caesar package, and
shall consist of a single file named Caesar.java.  This file
shall define a public class named Caesar that extends the
abstract class experts.Expert and defines the following Java
constructor and dynamic methods, which are specified below.
The constructor and dynamic methods listed in the signature
below shall be public.

Signature:

    new Caesar:  String x Histogram x SearchTree  ->  Caesar
    likelihoodOfSuccess:                          ->  int
    solve:                                        ->  Solution

Restrictions:  The first argument to new Caesar shall be a
suitable input for the newHistogram operation of assignment #4,
and shall contain nothing but spaces and upper case letters
of English; if spaces occur they can be assumed to represent
divisions between words.  The second argument to new Caesar
shall have been constructed by calling newHistogram on the
first argument.  The third argument to SearchTree shall not
be null.

Informal specification:

The arguments to the Java constructor are a String representing
the cryptogram to be solved, a Histogram constructed from that
cryptogram, and a SearchTree that contains most of the words
that are likely to appear within the original plaintext.

If x is an object of type Caesar, then x.likelihoodOfSuccess()
returns a non-negative integer p that is less than or equal to
100.  This integer represents the estimated probability, in per
cent, that x.solve() will succeed.

If x is an object of type Caesar, then x.solve() returns a
Solution that indicates whether the cryptogram was solved
successfully.  If it was, then the Solution also indicates
the original plaintext, that the type of cipher was "Caesar",
that the key was "c" where c is one of the 26 English letters
(in lower or upper case), and whether any further solutions
were found.

If x is an object of type Caesar, then x.likelihoodOfSuccess()
should compute its result in a short period of time, no matter
how long the cryptogram.  x.solve() may take longer, but should
call Thread.yield() periodically to allow concurrent threads to
make progress.  A benchmark that will be used to determine how
well an implementation of the Caesar module meets this part of
the specification will be described in class.

The client may create more than one Caesar object and use each
in a separate thread, but shall not use more than one Caesar
object within a single thread.

--------------------------------------------------

Specification of the Solution ADT.

A Solution represents a possibly empty sequence of solutions.

Solution is an abstract data type.  Its operations are static
methods defined within the Solution class, which is public and
is in the experts package.

Signature:

    notFound:                                       ->  Solution
    found:     String x String x String             ->  Solution
    found:     String x String x String x Solution  ->  Solution

    wasSuccessful:  Solution  ->  boolean
    getPlaintext:   Solution  ->  String
    getCipher:      Solution  ->  String
    getKey:         Solution  ->  String
    getOthers:      Solution  ->  Solution

Algebraic specification:

    found (text, cipher, key)
        =  found (text, cipher, key, notFound())

    wasSuccessful (notFound())                         =  false
    wasSuccessful (found (text, cipher, key, others))  =  true

    getPlaintext (found (text, cipher, key, others))  =  text
    getCipher (found (text, cipher, key, others))     =  cipher
    getKey (found (text, cipher, key, others))        =  key
    getOthers (found (text, cipher, key, others))     =  others