Part of the assignment involves learning and using new tools and APIs on your own. We know that for most of the students this part takes quite a bit of time and effort. We publish the relevant requirements so you can get ready for the assignment.

Below is a list of the tools and APIs you will be required to know how to use.

Note: the "small exercises" below are not part of the assignment. They are not mandatory, you don't have to submit them, and we will not check them. You will, however, be required to perform something very similar in the assignment, and these are simple, controlled practice tasks which can help you learn how to do so.

  1. Learn to work with the "Properties" class (http://download.oracle.com/javase/6/docs/api/java/util/Properties.html) for reading and writing configuration files such as sample.conf. You can also have a look at the supplied UseProperties.java class and the accompanying test.properties file.
  2. Learn to work with the "Logger" api (http://download.oracle.com/javase/6/docs/api/java/util/logging/Logger.html). You might find the following tutorial helpful: http://www.onjava.com/pub/a/onjava/2002/06/19/log.html You can also have a look at the UseLogging[2].java class.

    small exercise
    At this stage, we recommend you write a short Java program which:
    • gets a filename as a commandline argument(this file should be a properties file),
    • opens that file and reads it using the Properties class,
    • uses a Logger tool to write the properties it reads to both a logfile and to the screen, while using various log-levels.

  3. Learn how to create .jar files, Learn how to create runnable .jar files.
    A good place to learn about .jar files is: http://download.oracle.com/javase/tutorial/deployment/jar/ (you need only the first section: "Using JAR Files: The Basics", and the first 3-4 entries of the second Section: "Working with Manifest Files: The Basics")

    small exercise
    Create a .jar file named "myprog.jar" containing the program you wrote in the previous task.
    If you run the previous program by running:
    > java TheClassName properties_file_name
    You should be able to run the .jar file by
    > java -jar myprog.jar properties_file_name

  4. Learn what is Ant and how to use it (see Ant).

    small exercise
    Create an ant buildfile to perform what you did in the previous exercise (that is, writing "ant" should compile the .java files, and create the executable .jar with the correct manifest information).

  5. Coding Guidelines

    Let's say that you know how to write programs. Do you know how to program? Not necessarily.
    The fact that you know how to write in Hebrew, does not mean you know how to write a readable paper, or a formal letter. You must also master "style" and "conventions" – not only syntax and vocabulary.

    We will now discuss coding styles and tools that will help us (and force us) observe them.

    • Checkstyle

      Checkstyle is a development tool that helps programmers write Java code that adheres to a coding standard. The coding standard is expressed as a set of rules, which are verified by the tool.

      Checkstyle can be used from the command line and also from within Eclipse. The Checkstyle Eclipse plugin: http://eclipse-cs.sourceforge.net is already installed in the lab. If you work from home, make sure to install it in your Eclipse environment.

      Step-by-step (START)

      1. Window > Preferences
      2. Checkstyle (Notice there are two 'Checkstyle' tabs, updating only one is enough)
      3. New
        1. Type: Remote Configuration
        2. Name: spl-checkstyle
        3. Location: http://www.cs.bgu.ac.il/~spl121/wiki.files/spl_checkstyle.xml
        4. Cache configuration file - checked
        5. -OK-
      4. -OK-

        The Checkstyle configuration (the set of rules we want to use in this course) is now available to all projects in your Eclipse workspace.

      5. Go to project properties.
      6. Checkstyle (Notice there are two 'Checkstyle' tabs, updating only one is enough)
      7. "Checkstyle active for this project" - checked
      8. "Use simple configuration" - checked
      9. Select spl-checkstyle - (Global) for the configuration.
      10. -OK-
      Step-by-step (END)

      You can see checkstyle warnings in the "Problems" view. They appear in the same way as the compiler would flag problems in your code.

      Checkstyle rules

      Let's review the checkstyle rules we included: (goto checkstyle property and click "Configure" to see the checkstyle rules we included)

      • Javadoc comments > Method Javadoc. Applicable for public methods.
      • Naming Conventions > Constant Names
      • Size Violation > Maximum Parameters
      • Coding Problems > Magic Number
      • Coding Problems > Hidden Field
      • Coding Problems > Require This
      Note, the SPL team might change the configuration from time to time. Make sure exercises you submit pass the latest rules configuration.

    • PMD

      PMD is another style checking tool, similar to Checkstyle. PMD (pmd.sourceforge.net) scans Java source code and looks for potential problems like:

      • Possible bugs - empty try/catch/finally/switch statements
      • Dead code - unused local variables, parameters and private methods
      • Suboptimal code - wasteful String/StringBuffer usage
      • Over-complicated expressions - unnecessary if statements, for loops that could be while loops
      • Duplicate code - copied/pasted code means copied/pasted bugs

        The PMD Eclipse plugin from here is already installed in the lab. If you work from home, make sure to install it in your Eclipse environment.

        Step-by-step (START)

          First you set the global PMD rule-set for Eclipse. Then, you can enable/disable specific rules for your project.

        1. Import SPL PMD rules
          1. Window > Preferences…
          2. PMD
          3. Click "+"
          4. Rules Configuration

          5. On the right side: "Clear All" + OK
          6. On the right side: "Import rule set…"
            1. Click Browse
            2. Write: http://www.cs.bgu.ac.il/~spl121/wiki.files/spl_pmd.xml
              (in Linux you can write just: ~spl121/wiki.files/spl_pmd.xml)
              (you can also download the file, if you prefer: spl_pmd.xml)
            3. Click Open
            4. Click OK
          7. -OK-

          The configuration is now available to all projects in THIS workspace.

        2. Check project PMD properties
          1. Goto project properties
          2. Goto PMD
          3. You can see the list of all PMD rules and their description.
          4. Mark "Enable PMD"
          5. -OK-
        3. Run PMD on your code
          1. Right click on your project
          2. PMD > Check code with PMD
          3. This will move you to "PMD" Perspective, and display violations.
        Step-by-step (END)

        PMD rules

        You can see the full list of PMD rules and their description in Preferences.

        • Rules that produce Error/Warning message (things that you must fix):
          • UselessOperationOnImmutible > example: string.concat(other); will produce a new String
          • ImmutableField > identifies fields that could be immutable
          • BrokenNullCheck > example: if (a.contains("name") && a != null) …
        • Rules that produce Information message (you should try to fix them, but if you think it's ok, keep them):
          • AvoidReassigningParameters
        • Rules that will be added in the future:
          • DefaultPackage
        Note that the SPL team may update these rules from time to time.

      • Last note Even with all the help, the programmer is the most important tool. There is (currently) a limit to how much a tool can help your code be more readable and safer. Examples:
        • Readable Javadoc.
        • Meaningful variable names.
        • Checking arguments of public methods.

        See SPL Checkstyle/PMD Coding standards.

        And there are so much more programming practices and patterns that help you and I understand each other's code. Coding standards are ABSOLUTELY CRITICAL to the life of a programmer. They encapsulate the wisdom of many generations of exceptional programmers. The tools we have just described help you. USE THEM. LEARN THEM. LOVE THEM.


Good luck, Have fun.