BlueJ is a Java development environment; in other words, it is a software application that provides tools for reading, writing, compiling, and running Java programs. In this lab, you will create a folder for use in this course and learn how to use BlueJ to modify simple programs, run programs in two different ways, and create a program from scratch.

Exercise 1: Create a folder for your CS 110 work.

It makes sense to keep your CS 110 programs together in a single place, separate from other documents or materials you may have for other classes.

If you are working on K College computers (any computer that is part of Knet):

1. Double-click on the "My Computer" icon on the desktop.
2. Double-click on the M: Drive associated with your Knet ID (e.g., k03xx01).  Note: if there isn't an M: Drive associated with your Knet ID under "My Computer,", talk to your instructor immediately!
3. Create a new folder named CS110 (or something similar) on your M: Drive. Throughout this course, you will be creating additional sub-folders in your CS110 folder (or whatever you chose to call it).

Exercise 2: Download and modify a trivial Java program.

An object-oriented program is, as we learned in class, made up of a collection of classes.  The Java code for each class is stored in a separate file, where the name of the file is the name of the class with a .java extension.  Thus, the Java code for a class called Aquarium must be in the file Aquarium.java.  In BlueJ, the classes for a program are all stored together in a folder. 

We also learned that a running program consists of objects invoking operations on other objects.  How, though, can we start an application when it doesn't have any objects yet to do any operations?  In Java, we can start an application by invoking a special "start-up" operation called main.  (Java operations are called methods, so this operation is called the main method.)  A main method is not tied to any particular object, so the BlueJ development environment (or Eclipse, or whatever software is running the program) can invoke the main method, even though the program doesn't have any objects yet.  The main method then constructs one or more objects and invokes methods on them.  They, in turn, may construct other objects and invoke other methods, which is the essence of an object-oriented program.

We will start by downloading a very simple program with a single class. To keep things simple, the only method this class has is a main method.

• Download the TrivialJavaProgram project into to your folder for this class.  To download it, right-click (or control-click on a Mac) on the TrivialJavaProgram project link, select "Save Link As...", and, in the navigation window that appears, save it to your new CS110 folder.
• Unzip the downloaded project.  Double-click on the "My Computer" icon on your desktop and go to your CS110 folder on your M: drive. To unzip the project you just downloaded, double-click on the TrivialJavaProgram.zip file and click on "Extract all files" (under Folder Tasks) on the left side of the Windows Explorer window.  In the Extraction Wizard, just click on "Next" or "Finish" until it is done.
• Start up BlueJ.  Click on the "Start" menu at the lower left-hand corner of your screen.  Move the mouse up to the "All Programs" menu name, then move the mouse to the right until a pop-up submenu appears.  In the list of alphabetized application folders in this submenu, move the mouse over the word "BlueJ", then move the mouse right again and select the "BlueJ" application from the second pop-up submenu.
• Open the TrivialJavaProgram project.  In the BlueJ "Project" menu, select "Open Project."  In the navigation window that appears, navigate to your CS110 folder, choose TrivialJavaProgram, and click on the Open button.  (The TrivialJavaProgram project may be in a TrivialJavaProgram folder, in which case you will have to double-click on the folder first and then on the project of the same name within the folder.)
• Read the README file.  For now, you can ignore the buttons in the control panel or toolbar on the left side of the BlueJ window.  Concentrate instead on the icons in the central part of the window.  Double-click on the document icon in the upper-left corner of the diagram to open up a README file with information about the project.  Read this document, especially the "HOW TO START THIS PROJECT" section, which describes how to know whether classes in a project need to be compiled (translated to a format that the computer can execute), how to compile classes that need to be compiled, and how to run the TrivialJavaProgram application.
• Compile and run the TrivialJavaProgram project using the instructions in the README document.
• Read and modify the TrivialProgramClass class.  Double-click on the TrivialProgramClass icon to view the class's Java code in an editor window.  (Or, right-click or control-click on the icon and select Open Editor.)  Modify the "@author" line in the class comments to include your name, without parentheses, rather than "(your name)".  Leave the "(with assistance from)" phrase there for now.  Change the date on the "@version" line to today's date.
• Compile and run the TrivialJavaProgram project.
• Further modify the TrivialProgramClass class.  Double-click on the TrivialProgramClass icon to view the class's Java code in an editor window.  Modify the main method to print a simple message, as in the following example:

          public static void main(String[] args)
          {
              System.out.println("Hello, world.");
          }
      

  Compile and run the modified program.  Your message should appear in a new window.
• Update and view the class documentation.  Update the AUTHORS and USER INSTRUCTIONS sections in the project README file, since your program no longer does nothing.  Edit the TrivialProgramClass Java source code to update the initial description of what the program does and to document your changes in the Modifications section of the class documentation.  If you received assistance from anyone, document that in the "@author" line; otherwise, remove the "(with assistance from)" clause.  Compile and run your program to make sure that you only changed the program's documentation, not its behavior.  Double-check your documentation changes by selecting Documentation in the pull-down menu in the upper-right corner of the editor window.  Scroll down to see the complete javadoc documentation for your class.

Print your modified files.  When you are done making your modifications, print the project README file and the Java source code and class documentation for the TrivialProgramClass class (3 print-outs).  You will find the Print option under the Class menu.  Remember that you can go back and forth between the Java source code and the class documentation for a class using the pull-down menu in the upper-right corner of the editor window.

Exercise 3: Download and save class templates for future use.

When you create new projects and new classes in BlueJ, the development environment will provide you with some sample code and documentation in the project README file and in the classes.  The documentation conventions for this course, however, are slightly different from the documentation that is provided automatically.  The CS110Templates project contains a project README file and two sample classes with documentation corresponding to the conventions for this course.  One class contains a main method, while the other is a normal class with an instance variable, a constructor, and a method.  In future projects, you may find it useful to copy and paste the comments from these classes into new classes, and then edit them to reflect the actual behavior of the new classes.

• Download the CS110Templates project to your CS110 folder and unzip it in the same way that you downloaded and unzipped the TrivialJavaProgram project above.
• Read the files in the CS110Templates project.  In BlueJ, open the project and read the project README file and the Java source code for the two classes.
• Write out answers to the following Analysis Questions. 
  • How is the main method for the TemplateOfClassWithMainMethod class different from the main method for the TrivialProgramClass class?
  • How does the javadoc documentation for each class (in other words, the documentation comments that appear above the line with public class ClassName) correspond to the contents of its class documentation page (the page you see when you switch from Implementation to Interface in the pull-down menu in the upper-right corner of the editor window)?  How does the use of the HTML <br> (line-break) tag affect the look of the class documentation page? What effect do  the Javadoc @author and @version tags have?
  • How does the javadoc documentation for the constructor and method in the NormalClassTemplate class correspond to the contents of its class documentation page?  Pay particular attention to the Constructor Summary, Method Summary, Constructor Detail, and Method Detail sections of the class documentation page.  Also, what effect do  the Javadoc @param and @return tags have?

Print your answers to the Analysis Questions above.

• You may wish to save a backup copy of your Java programs to your computer (if it is on the campus network) or to a USB drive.

Exercise 4: Look, Ma, no main!

Although stand-alone Java programs need a main method as a starting point, in BlueJ it is possible to construct objects from the icons in the project diagram and then invoke methods on those objects directly.  For this exercise, you will be working with a project that will simulate fish swimming around in an aquarium.

• Download the AquariumLabSeriesUsingBlueJ project to your CS110 folder and unzip it in the same way that you downloaded and unzipped the TrivialJavaProgram and CS110Templates projects above.
• Open the Aquarium Lab Series project in BlueJ.  The first thing you'll notice is that this program has several more classes than the other two you have looked at today.  You will be learning about and enhancing the Aquarium simulation program over the next couple of weeks, and during that time you will become familiar with these classes and how they relate to each other.  For now, though, we will consider just four:
  • The AquaSimApplication class contains the main method to start the program.
  • An instance of the Aquarium class represents the aquarium in which fish will swim.
  • Instances of the AquaFish class represent the fish swimming in the aquarium.
  • An instance of the AquaSimGUI class provides a graphical user interface (display and control button) for the simulation.
• Run the Aquarium simulation using main.  As a quick way to become familiar with what the Aquarium simulation program does, compile and run the program using the main method in the AquaSimApplication class.  You should see a window appear with a Start button and some instructions at the bottom.  This is the program's graphical user interface.  When you press the Start button, you should see a white fish drawn on a blue background (the aquarium).  That is all the program does for now.  Close the graphical user interface window.
• Run the Aquarium simulation without using main.  To run the Aquarium simulation program using BlueJ and without a main method will take a number of steps.
  • Construct an Aquarium object.  To do this, right-click (or control-click on a Mac) on the icon for the Aquarium class and select "new Aquarium(int width, int height)".  A dialog box will appear, asking you for the width and height of the aquarium.  You may enter 600 and 480, as the program does when executed from the main method, or any other dimensions.  You will also have an opportunity to set the name of the instance (for example, "aqua") or use the default ("aquarium1").  Once you have constructed the aquarium object, a red icon for it will appear in the object bench, the window area below the project diagram and control panel.  Note that you will not see a display of an aquarium with a blue background, because you have not yet created a graphical user interface and display.
  • Construct AquaFish objects.  Right-click (or control-click) on the icon for the AquaFish class, and construct a fish by selecting the "new AquaFish(Aquarium aqua)" constructor. For the parameter, use the name of the Aquarium object in the object bench area (for example, "aqua" or "aquarium1").  You can also set the name of this AquaFish instance (e.g., "fish1", "trout", "joe") or use the default ("aquaFish1").  Note that there still is no visual display of the aquarium because there is, as yet, no graphical user interface.  Construct at least one more AquaFish object in the object bench.  Tell at least one of your fish to move by right-clicking on the appropriate red object icon in the object bench and selecting "moveForward".  Again note that there is no visual display of the fish movement.
  • Construct the graphical user interface.  Right-click (or control-click) on the icon for the AquaSimGUI class, and construct a graphical user interface by selecting the shortest and simplest of the AquaSimGUI constructors, the one with only a single parameter.  Provide the name of your Aquarium object in the object bench, just as you did for the fish.  A graphical user interface window with an empty aquarium dislay should appear.  Even if you were to press the Start button, the aquarium display would remain empty. 
  • Display the aquarium.  Right-click (or control-click) on the red icon for the AquaSimGUI object in the object bench, and select "showAquarium()".  You should see the blue background for the aquarium, but no fish.  This is because we constructed fish that know about the aquarium (so that they can figure out where the walls and top and bottom of the aquarium are), but we did not add the fish to the aquarium. 
  • Display the aquarium with fish in it.  Add the fish to the aquarium by right-clicking on the red Aquarium object in the object bench and selecting the "add (AquaFish fish)" method for each AquaFish object.  Each time, provide the name of one of your AquaFish objects as the parameter to the add method.  Now go back and right-click on the red AquaSimGUI icon and select "showAquarium()"; you should see the fish you added to the aquarium.
  • Move and display fish.  Move one of your fish forward with its "moveForward" method and then redisplay the aquarium with the "showAquarium" method in the graphical user interface.  You should see one fish move forward.  Then move both fish forward one or more times and redisplay the aquarium.
  • Close the graphical user interface window.  Notice that the objects in the object bench disappear.  They will also disappear if you edit any of the Java source files and recompile the program.  After compilation your object bench will always start over from scratch.
  • Experiment with a skinny aquarium.  Construct a new aquarium whose dimensions are 100 pixels wide and 200 pixels high. Construct one or more fish and add them to the aquarium, as you did before. Construct a graphical user interface and display your aquarium and fish. Again, move your fish forward several times.
• Write out answers to the following Analysis Questions. 
  • Why do you think the AquaFish and AquaSimGUI constructors ask for the aquarium as a constructor?
  • Why does the Aquarium "add" method take a parameter but the AquaFish "moveForward" method and the AquaSimGUI "showAquarium" methods do not?
  • What happens when you move a fish forward a number of times in a tall, thin aquarium? (This will be the focus of a future lab exercise.)

Print your answers to the Analysis Questions above.   Hand in your modified files and Analysis Question answers from this lab.

Exercise 5: Creating a new project (OR, Getting started on Programming Project #1).

In this exercise you will be creating a new project from scratch that will be similar to the TrivialJavaProgram project you worked with at the beginning of the lab.  This will be your first programming project, due in lab during Week 2.

• Read the program options available for Programming Project #1 (due at the beginning of Lab 2).  Choose one.
• Create a new project.  In the BlueJ Project menu, select "New Project...."  Give the project a name that describes the program option you chose. 
• Create a new class.  Click on the "New Class" button in the control panel to the left of the project diagram.  Edit your new class; copy the contents of the TrivialProgramClass or the TemplateOfClassWithMainMethod class into your new class. 
• Implement the new class.  Write the Java source code for the main method in your new class.  Update the project README file (the icon in the upper-left corner of the project diagram) and the javadoc comments in the class to reflect the changes you make.

If you wish to work on your own computer:  Copy your program to your own computer (if it is on the campus network) or to a USB drive.  If you do not have BlueJ on your own computer, you can download it from www.bluej.org.  It is free, open source software, and quite easy to install.

Due at the beginning of Lab 2:  Print the project README file and the Java source code and javadoc class docmentation for the class (3 files altogether) , and hand them in at the beginning of Lab 2.