CS 302: Introduction to Programming

Suggested Data Structures

Your enigma machine will need a number of data structures (1D and 2D arrays) in order to keep track of what's going on. Here are the data structures we suggest you use:

• reflectorRotor: This should be a one-dimensional array of integers that represents the reflector rotor. You can create it by using the convertRotor() method in conjunction with the RotorConstants.REFLECTOR constant.


• rotorsInUse: This should be a two-dimensional array of integers that represents the multiple rotor ciphers in use. You can create it by calling setUpRotors() and passing in an array which indicates the rotor #'s to be used.


• rotorNotches: This should be a two-dimensional array of integers, that represents the notch locations of the rotors you're currently using. It should be created by using the getRotorNotches() method.


• rotorOffsets:This should be a one-dimensional array of integers whose purpose is to store the current rotational positions of the rotors. Each slot in the array would corresponds to a rotor in the rotors array. Each slot in the rotorOffsets array will hold the corresponding rotor's current position. This does not need any method for initializion.

Development Milestones:

We suggest that you incrementally develop this program by following the milestones in the order listed below. This order will make it easy for you to check that each milestone is working properly before you move on to the next one. Don't move on to a new milestone until you can convince yourself that the current milestone is working correctly. The further along you get, the harder it will be to detect errors in code you developed early on.

• Milestone 0 (Read the Documentation) - Create a new Eclipse project, download and extract the code from the skeleton. Read through the code that is provided. Familiarize yourself with the project by reading the javadoc pages and the History and Functionality.


• Milestone 1 (Create Main Program Loop) - Begin program by working on the main program control flow. Create your main program loop, and simply have it prompt the user, and echo the input back to them. Do not worry about errors, encryption, parsing, or rotors at this point. Think of this as laying the groundwork for the rest of your program. This work should be done in the main() method.

  Milestone 1 Sample Run



• Milestone 2 (Create the reflectorRotor) -
  1. Implement (code) the convertRotor() method. Use the comments and javadoc to assist you.
  2. Add code to declare and initialize your reflectorRotor. (See Suggested Data Structures section). Use (call) your convertRotor() method and the RotorConstants.REFLECTOR value to initialize your reflectorRotor.
  3. Add code to print out each element of your reflectorRotor. See if its results match your expectations. Also compare results with the Milestone 2 sample run.

  Milestone 2 Sample Run



• Milestone 3 (Assemble the rotorsInUse array) -
  1. Try implementing setUpRotors(). Again use the javadoc and comments to guide you. Hint: setUpRotors() will need to make one or more calls to convertRotor() in order to work properly.
  2. Once those methods are finished, try calling setUpRotors() in main(). setUpRotors() requires an array of integers as input, which represents the user's rotor selection. Since you haven't yet implemented rotor configuration parsing, you should hard-code a temporary value to take the place of this selection ( e.g. tell your program to always use Rotor I). As for its purpose in main(), you can use setUpRotors() to initialize your rotorsInUse array (See the Suggested Data Structures section).
  3. Once you have your call to setUpRotors() in place, try printing the contents of rotorsInUse. Compile and run your program, and see if it prints out the results you expect. We have also provided a Milestone 3 sample run. Once you are satisfied, you can remove that print command.

  Milestone 3 Sample Run



• Milestone 4 (Implement encryption with a single rotor) - Before tackling the full-fledged complexity of the enigma encryption scheme, first focus on a smaller problem: encryption using a single rotor, without advancement.
  1. Implement the encode() method. Start simple and encrypt using just a single rotor and the special reflector rotor. Do not worry about advancing the rotors yet, as encode only has to encode a single character. (Advancing will be handled by other methods)
  2. Go back to your main() method and insert a call to encode(). You'll need to provide it with the rotorsInUse and reflectorRotor arrays that you created in Milestones 2 and 3. Try it out with a hard-coded message and see if it performs a basic encryption.
  3. Verify that the encryption is working as you expect. Work out a sample message by hand and see if your results match.
  4. Encrypt your message twice in a row during a run of your program. You should get the same output both times, since there is no advancement.

  Milestone 4 Sample Run

  Is your output not matching the Milestone 4 sample run? Take a glance at the "Encrypting in Reverse Order" section in the History and Functionality page.



• Milestone 5 (Test Encryption with Multiple Rotors) -
  1. You can now hardcode an array of two rotors to send to setUpRotors(). Run your program and see if encryption still works. You should get a different ciphertext than that produced in Milestone 4.
  2. Verify that the encryption is still working as you might expect. Work out a sample by hand and see if the results agree.
  3. Add in more rotors. This should not break your program.

  Milestone 5 Sample Run
  Milestone 5 Sample Run 2

  
  
• Milestone 6 (Implement Rotor Parsing) - With basic encryption working, let's turn to making your enigma reconfigurable. Do this by adding in rotor parsing.
  1. Implement parseRotorIndices().
  2. Insert a call to parseRotorIndices() in main(). Add in the prompt and user input (Scanner) functionality to the main method. Your program should now be able to read in a sequence of numbers as a String and convert them into an array of integers using parseRotorIndices(). You can now replace that hard-coded array from Milestone 2 with the array created by parseRotorIndices().
  3. Add in error handling for the Enter Rotor Configuration: prompt.
  4. Test your parsing and error handling code thoroughly.
  Milestone 6 Sample Run
  Also, check the error handling sample runs. Your program should now be able the match the output of those.


• Milestone 7 (Assemble the rotorNotches Array) -
  1. Implement the getRotorNotches() method.
  2. Insert a call to getRotorNotches() within main(). Use it to initialize your rotorNotches array. (See the Suggested Data Structures section).
  3. Display the contents of rotorNotches to the user. Examine the results and see if they match your expectations. Once you are satisfied, you can remove that print command.

  Milestone 7 Sample Run



• Milestone 8 (Implement Rotor Advancement) -
  1. Implement the rotate() method and then the advance() methods. Hint: Your advance() method should make one or more calls to rotate(). See the first Milestone 8 Sample Run to verify that your rotate() method is working correctly.
  2. Create a rotorOffsets array. (See the Suggested Data Structures section). You will need this to keep track of how far advanced each rotor is.
  3. Insert a call to advance() within main(). Remember, the rotors should advance after encoding each and every letter. You will need to pass to it your rotorOffsets and rotorNotches arrays.
  4. Test the functionality using just one rotor. Work out an example by hand and see if the results match your expectations.
  5. If you are satisfied that advance() is working with just a single rotor in play, try adding in the other rotors.
  
  Milestone 8 Sample Runs
  • Milestone 8-1 Sample Run (Rotate)
  • Milestone 8-1 Sample Run (Advance)


• Milestone 9 (Test Your Complete Program Thoroughly ) - Test your completed program using multiple rotors, in multiple configurations. Compare your outputs with our sample runs. Test decryption, as described earlier. Also, save a copy of your original RotorConstants.java (as RC1.java or something) and then copy the alternative rotorConstants.java file to your project. Your program should now produce the alternative sample runs. You are free to modify any of the provided rotorConstants files to facilitate your own testing. You will only be turning in your Enigma.java file.

Tips and Hints

Parsing the Rotor Indices

For parsing the rotor indices line (what the user types when the program begins), there are two recommended approaches you may take:

First, use a Scanner object to read in the entire rotor input line as a String.

Then, (inside the parseRotorIndices() method) :

1. Use String methods such as split() to parse the integers.
   
   OR
   
   
2. Create a second Scanner object connect to the String that was read (instead of connecting it to System.in). Then, you can use the Scanner object's hasNextInt() and nextInt() methods to parse the integers out.

The Identity Rotor

To assist you in debugging, the RotorConstants.ROTORS array will always have a special value stored at its 0th index: the "Identity Rotor". This rotor is simply the alphabet. Using it (before advancement, and not taking into account the Reflector) will cause all characters to map to themselves: 'A' would encode as 'A', 'B' would encode as 'B' etc.

Working with Upper-case and Lower-case Characters

You will have to be able to convert lines of text into UPPERCASE letters. To do this, you can use the String class toUpperCase() method.

To check if a single letter is uppercase, you can use Character.isUpperCase().

Convering Characters into Alphabetical Indices

Many of the methods will require to work with characters by converting them first to their alphabetical index. In fact, this is one of the primary purposes of the convertRotor() method. The alphabetical index of a letter refers to that letter's position in the alphabet. Suppose we were to create an array of characters in the order of the alphabet:

ABCDEFGHIJKLMNOPQRSTUVWXYZ

Index 0 would refer to letter A, index 1 would refer to letter B, etc. Converting a letter into this form is as simple as subtracting 'A' from it.

Javadoc as a Contract

For this project, it is imperitave that your method implementations follow the interface specified by the Javadoc. You can think of the Javadoc as the contract which your code must adhere to. As such, your code must make use of the input parameters and return values, as specified. All inter-method communication must be through those parameters and return values. As such, using mechanisms like static fields (or "class variables") to avoid passing program information between method would be a violation of the Javadoc that describes how the Enigma class functions.

What about Decryption?

You won't be explicitly implementing decryption, but your program can indeed decrypt ciphertext! In order to test this functionality, first run your program as usual, encrypting a few different plaintexts. Keep track of what the program outputs as the corresponding ciphertexts. Now, restart your program and use the same rotor configuration (i.e. the same rotor numbers in the same order). Now, you can "encrypt" your ciphertexts that you recorded, and you should get back your original plaintexts. The fact that this is possible is one of the beauties of the Enigma.

However, it is important that you actually quit and restart your program to test decryption. This is because decryption requires that the rotors must have the same offsets as when the encryption took place. We have not provided any functionality to manually reset the offsets. Therefore, the simplest way to test this is to restart the program. This sets the offsets back to 0, which is where they started during encryption.

Testing

You should test your program by running it frequently as you develop. It is a worthy goal to always have a compiling program so that you can run it and see what it does. If you follow the milestones outlined above, you should be able to verify whether you have completed each milestone by running your program and interacting with it.

One technique that you can apply to your own testing practices is the idea of Unit Testing. Unit testing essentially is the process of testing small units of code (methods in our case) independent of each another. That is, instead of testing your entire program as a whole, take a small piece of it (like a single method), and test that separately. This might mean short-circuiting your main method temporarily and hard-coding inputs to pass into a given method. Give special thought to boundary cases that may test the limits of your methods' behavior. Off by one errors are easy to make.

To be a good tester, you have to be willing to become your own adversary. Try to break your own code with different input combinations, and do not relent until you are convinced that your program is 100% correct.

Extra Credit (1%)

The extra credit for this assignment involves implementing another level of the Enigma's security: the plugboard. The plugboard allows pairs of letters to be swapped before and after the rotors do their substitution ciphers. The name "plugboard" comes from the fact that on the physical Enigma machine, the user would plug a wire into the two letters they wanted to be swapped. Our version allows the user to enter on a single line which letters they want to be swapped.

Input and Error Checking

Using the plugboard involves getting one more piece of input from the user. You need to know which pairs of letters should be swapped on the plugboard. Prompt the user for these pairs after they have entered the rotor configuration:

Enter pairs of letters to connect on the plugboard. Separate pairs by spaces:

For example, if the user wanted to swap the letters A and F, as well as C and T, they would enter AF CT at the prompt.

If the input is anything other than what is specified, print the following error message, and exit the program:

Invalid plug pair. You must enter a pair of upper-case letters with no characters in between.

Additional Methods

There are three additional methods you will need to implement the plugboard: parsePlugs(), encodeWithPlugs(), and swapPluggedPairs(). The processes of rotor advancement and rotating are unaffected by the use of the plugboard.

Parsing the plugboard input is similar to parsing the rotor configuration. The plug configuration becomes a two-dimensional array, or, an array of 2-element arrays. Each 2-element array contains the integer representation of the two letters that are being swapped.

When encoding with plugs, the pairs are swapped before and after the rotors-reflector-rotors sequence. That is, swapPluggedPairs() is called before running the rotors in forward order, and after the rotors are run in reverse order. That is, you should check to see if your original plaintext character is part of a plugged pair and do the swap, if necessary. The encryption then runs as usual. At the end of the encryption, when you are left with an encrypted character, you should now check to see if that character is a member of a plugged pair, and do the necessary swap. Note: a swap may never be done, may be done only before or after the normal encryption, or may occur both before and after the encryption. It depends on what you specify as your plugged pairs.

Important! Read the EnigmaEC Javadoc to get an idea on how to go about implementing these methods. Just as with the non-ec methods, you are required to provide implementations for these methods. Also as before, you are not allowed to change the method headers in any way.

EnigmaEC Skeleton

Because you are required to implement the EC methods exactly as specified, you are required to use the ec skeleton below. Essentially it is just a non-ec skeleton that also contains the methods you are required to implement. We recommend that you copy and paste the method bodies from your non-ec version to this skeleton file, and then start coding the EC assignment from there.

skeleton-ec.zip

EC Sample Runs

EC Sample Runs can be found in the Sample Runs section.

Submission:

Before handing in your program, check that you've done the following:

• Did you verify that your program works correctly by following the information in the Testing section above? About 80% of your grade is based on your program working correctly.
• Did you turn in all necessary source files listed below?
• Did you use good programming style by following the CS302 Style Guide? About 10% of your grade is based on good programming style.
• Did you properly comment your program by following the CS302 Commenting Guide? About 5% of your grade is based on proper commenting. Note, we've provided most of your method header comments.
• Are your program's source files named exactly as provided by the skeleton? Deductions will be made if you renamed any classes or changed any public methods headers from the skeleton.

Use the CS302 Forms Page to electronically submit and backup your work:

• Indidividuals or either team member may submit files.  Only one member of a team needs to submit files for the team. All team members may list files.
• Submit the files listed below as often as you wish at any time before the due date and time.
• Previously submitted files are overwritten when you re-submit your work.
• We suggest you use your handin directory to keep a backup of your most recent working copy as you develop your solution. If you run into a problem, you can use the "List Files" form to download the files in your handin directory as a backup. They are downloaded as a zip file that you'll need to unzip to extract your files.
• You can verify that you've submitted things correctly. Please do not ask your instructor to check for you. Use the "List Files" form to list and download what you've submitted to verify that the files with the desired contents are your handin directory.

Submit this file:

• Enigma.java

You are not submitting any of the other files that were provided to you in the skeleton. You should not have edited any other files, and if you did, you should make sure your code still works with those files as they were provided to you.

If you did Extra Credit, submit these files in addition to the other files you submit:

• EnigmaEC.java

Make sure you did not put any EC-specific code into any other files. This file, along with the non-EC file submitted earlier, should be enough for us to run your entire EC submission.

Getting Feedback from the Testing Server

For this project, you will have the opportunity to upload your program early to receive feedback from our testing server. The testing server will run a number of test cases against your program and send you an email containing the test results.

Using the Testing Server

To "submit" to the testing server, all you have to do is to upload your code anytime before the due date (following the submission steps outlined above). The testing server will then test your program and send its results to you via email. These results are not grades, and nothing you upload is final. These results are simply testing feedback that can assist you in assessing your program.

Note for submitting EC: To get feedback on EC, simply submit it along with your non-EC code. EC Submissions are not counted separately, so please be sure to submit both files whenever you are handing in EC.

You have the opportunity to receive testing feedback at most once per calendar day. When you submit for the first time on any given calendar day, the testing server will test your program and send back and email report as soon as possible. All subsequent submissions for that day will be "silent."

At the beginning of each calendar day (sometime between 12:01AM and 3:00AM), your most recent "silent" submission from the previous day (if applicable) will be tested and an emailed will be sent. When such an instance occurs, you will not be eligible to receive testing results until the next calendar day.

Disclaimers

1. The purpose of the testing server is to assist you in following the project requirements. The specifications are lengthy and detailed, and it can be easy to make a small mistake. It is our hope that the testing server can help you make the program we expect. That said, however, the testing server is not a replacement for testing. You should still test your program early and often. You are still responsible for thoroughly testing the correctness of your program.
2. Note that the testing service does not assign grades ~ grades will also take into account other factors such as style, documentation, and adherence to project requirements.
3. Please be advised that we will run other tests in addition to these when grading your program, so a failure-free report does not guarantee a grade of 100%.

Understanding the Testing Reports

1. During the testing process, the testing server will run your code against a variety of test cases. Each test case will test some different behavior, as indicated by the test's name. There are a variety of different messages that may get printed:
   • Compiler errors: Your code did not compile. This prevented the testing server from being able to run any tests.
   • Runtime Exceptions: During the test, your code threw some kind of exception, which caused your program to crash. This caused a stack trace to get printed, which will indicate both the type of error that caused the crash, as well as the line of code at which it happened..
   • Expected / Got Messages: These messages will contain an error message describing the problem, as well as "expected output" The expected output indicates the correct message that should have been printed in response to a certain command to your program. The message following "But got: " will be the incorrect output that your program printed.
   • Expected Output to Contain: These messages will specify a sub-message that we expected to find within your program's output when given a certain command. "But got" indicates the message in which that sub-message should have been found.
   • Testing of Submethods: Some of our tests will substitute correct instructor versions of methods while testing your program. This is to help isolate incorrect behavior method-to-method, and to ensure that your code is obeying the javadoc contracts. You may assume that a given test is substituting in correct versions of sub-methods, unless noted otherwise.
2. The tests are sorted in order of increasing complexity. We recommend that you attempt to fix the behavior tested by the lower-numbered test cases before addressing the higher-numbered test cases. Many of the higher-numbered test cases depend on functionality that is tested by the lower-numbered cases.
3. If you recieve a large number of errors, do not despair. It is possible that many tests ended up failing due to a single bug. This is known as a "cascading failure".