COP 2800 (Java Programming) Project #4

For this project you will create a class called TextKit containing several utility methods that can be used in different applications.  This class is not intended to be a complete application by itself!  Your class will be put into a package called utils.  The package will then be documented using the javadoc tool to create HTML documentation for your package.  Finally you will create a small stand-alone Java program that tests the methods of your utils.TextKit class.

Your next project will use this package, and you won't be allowed to make any changes to TextKit once submitted.

Create a public Java class named TextKit in a package called utils that contains the following public static methods (at least):

• lineOfStars
  This method will create and return a String containing a line of asterisks (or stars).  This method must take a single parameter only, an int which says how many stars to draw.  For example the code:
  
  System.out.println( utils.TextKit.lineOfStars(4) );
  Should print a line that looks like:
  
  ****
  The intent is that lineOfStars should be a generally useful method that given a single number returns a String of that many stars.  (Such a method could easily be reused in another project someday.)
  
  
• pad
  This method will format integers by adding spaces (called padding) to the left end, to make the resulting String a certain minimum length.  (If the number contains more digits than the specified width, then no padding is added.)  This method must take two int arguments, the first is the number to format, and the second is the desired minimum String length.  The resulting String is returned.  For example the code:
  
  int num = 17; System.out.println( "*" + utils.TextKit.pad(num, 4) + "*" );
  Should print a line that looks like:
  
  * 17*
  (Notice there are two leading blanks added by pad, to make the field length 4.)

To facilitate such reuse these methods must be static methods of a class called TextKit, which must be in a package called utils.  (Someday you might add other text utility methods to this class or add other classes to this package.)

Be sure to add appropriate JavaDoc comments throughout your code!

For full credit your methods must check for invalid arguments (for example, inappropriate negative numbers).  If you detect invalid arguments passed to a method, the method must throw an appropriate java.lang.IllegalArgumentException.

Next, create a testing application.  Your test program (containing just a main method) should not be in the utils package but rather in the default, nameless package.  You can name the class anything you like; something like TextKitApp is fine.  This test program should invoke each method of the utils.TextKit class at least once, to verify those methods work.  (Such a main method is sometimes referred to as a test driver.)  A good test driver will have many test cases, to more throughly check the methods.  Having failing cases (in a try...catch block of course) is also a good idea.

Finally, you must use javadoc to create HTML documentation for your package.  This documentation should be placed in a directory called docs.  Note only the code in the package needs to be documented with JavaDoc, your test driver only needs regular style comments.

For this project, no normal email submissions will be accepted.  However you can submit a zip attachment via email, which should contain the correct files and directories.  You should send this email to waynepollocklive@yahoo.com.  (Email sent to my regular email address that contains a zip file attachment will be discarded by the HCC mail server!)

You can instead submit a flash disk or CD-ROM, with your name on it, containing your test program at the top (root) directory, a directory called utils containing the TextKit class and Java source code file, and another directory (not under utils!) called docs containing the HTML output of the javadoc command, which should be generated using all the appropriate options as shown in class.  (Please don't have other files on this; I don't wish to hunt around for the right ones.)

Send projects to .  Please use a subject such as Java TextKit Project submission so I can tell which emails are submitted projects.

Send project questions to .  Please use a subject such as Java TextKit Project Questions so I can tell which emails are questions about the project.

Please review Submitting Assignments and Project Grading Criteria from your class syllabus for further details.

Use PkgDemo as a model to create and use packages.  See Greeter - JavaDoc demo as a model to use the javadoc tool.  (Remember that the Java SDK documentation contains information about all tools, including javadoc.

You program should be easily read and well commented, including your name.

What is an illegal argument?  If you try to pass something other than an int to a method expecting an int argument, you get a compiler error message.  That's not what is meant by an illegal argument.  That would just be a syntax error that the compiler catches for you.

What the compiler can't catch is when you pass an int value that makes no sense.  In the case of lineOfStars, what should that method do if you pass a negative integer?  Or a huge integer, say over one million?  The Java compiler can't detect such illegal argument values.  (Although in some languages you can more precisely define argument types, including legal ranges.  In those languages the compiler can detect the problem!)

So, you check arguments at the top of methods in reuseable code modules such as TextKit, and if they are illegal then the method should throw exceptions.

A programmer is an expert problem solver.  To solve a task such as lineOfStars and pad you can make use of a design method that works in lots of cases.  The idea is to try to solve a simpler problem.  Then you can repeat that step in a loop to solve the original task.  This general idea of solving a problem by breaking a difficult task into very simple tasks (baby steps) and then repeating or combining those steps, is known as divide and conquer.

You can apply this idea to the task of lineOfStars.  To start with, create an empty String.  To add one star to this you can use a similar solution to adding a number to a variable (num = num + something).  You need to take the existing string of stars, append one "*" to the right end, and the new String object replaces the original.  Once you can add one star to a String, so you need to repeat that step the correct number of times to produce a String with the correct number of stars.  To make this idea efficient consider how you might use a StringBuilder instead of a String.

You can apply this idea to the design of pad as well.

Java 5 added many new features, including the ability to format numbers easily.  You don't have to use this feature, but if you find it and figure out how to use it (which isn't easy) you can pad a number in a single line of code!

Ask me for help if you get stuck!  (Try not to wait until the deadline!)