Introduction - the SeaPort Project
series

For this set of project, we wish to simulate some of the aspects
of a number of Sea Ports.

Here are the classes and their instance variables we wish to
define:

SeaPortProgram extends JFrame

variables used by the GUI interface

world: World

Thing implement Comparable <Thing>

index: int

name: String

parent: int (eventually Thing)

World extends Thing

ports: ArrayList <SeaPort>

time: PortTime

SeaPort extends Thing

docks: ArrayList <Dock>

que: ArrayList <Ship> // the list of ships waiting to
dock

ships: ArrayList <Ship> // a list of all the ships at
this port

persons: ArrayList <Person> // people with skills at
this port

Dock extends Thing

ship: Ship

Ship extends Thing

arrivalTime, dockTime: PortTime

draft, length, weight, width: double

jobs: ArrayList <Job>

PassengerShip extends Ship

numberOfOccupiedRooms: int

numberOfPassengers: int

numberOfRooms: int

CargoShip extends Ship

cargoValue: double

cargoVolume: double

cargoWeight: double

Person extends Thing

skill: String

Job extends Thing - optional till Projects 3 and 4

duration: double

requirements: ArrayList <String>
// should be some of the skills of the persons

PortTime

time: int

Eventually, in Projects 3 and 4, you will be asked to show the
progress of the jobs using JProgressBar's.

Here's a very quick overview of the projects:

Read a data file, create the internal data structure, create a
GUI to display the structure, and let the user search the
structure.

Sort the structure, use hash maps to create the structure more
efficiently.

Create a thread for each job, cannot run until ship has a
dock, create a GUI to show the progress of each job.

Simulate competing for resources (persons with particular
skills) for each job.

General Objectives

Here are some notes about the projects, the particular features
of object-oriented design and object-oriented programming
(OOD/OOP) the we want to cover in this class and some of the
features of Java to help support that style of programming. We
also want to explore the Java GUI system a little, with
particular emphasis on viewing the data structures and effective
ways to display the running of multiple threads competing for
resources.

The particular scenarios selected for each semester ask you to
implement as many of these objectives as possible in some
compelling way. We are always open to additions and suggestions.

General objects for each project:

Project 1 - classes, text data file, GUI, searching

Define and implement appropriate classes, including:

instance and class variables,

constructors,

toString methods, and

other appropriate methods.

Read data from a text file:

specified at run time,

JFileChooser
jfc = new JFileChooser (".");
// start at dot, the current directory

organizing those instances in existing JDK structures
which can be sorted, such as ArrayList's.

Create a simple GUI:

presenting the data in the structures with with some
buttons and

text fields supporting SEARCHING on the various fields of
each class.

Project 2 - Map class, Comparator, sorting

Use the JDK Map class to write more efficient code when
constructing the internal data structures from the data file.

Implement SORTING using the Comparator interface together
with the JDK support for sorting data structures, thus sorting
on different fields of the classes from Project 1.

Extend the GUI from Project 1 to let the user sort the data
at run-time.

Project 3 - More JDK classes - GUI's and threads

Explore other GUI classes, such as JTree, JTable, and
JProgressBar.

Create and run threads

Competing for one resource.

Project 4 - Concurrency

Resource pools

Threads competing for multiple resources

Blocking threads

Extending the GUI interface to visualize the resource pools
and progress of the various threads.

Documentation

HINT: You should start working on a documentation file before you
do anything else with these projects, and fill in items as you go
along. Leaving the documentation until the project is finished is
not a good idea for any number of reasons.

Read the data file, creating the specified internal data
structure (see the Introduction for
the classes and variables of the structure).

Display the internal data structure in a nice format in the
GUI

use JScrollPane and JTextArea

Display the results of a Search specified by the user

JTextField to specify the search target

Searching targets: name, index, skill would be a minimum
you are encouraged to provide other options

Note that a search may return more than one item

DO NOT create new data structures (beyond the specified
internal data structure) to search
you may create a structure of found items as a return value

Data file format:

Each item in the simulation will appear on a single line of
the data file.

The data file may have comment lines, which will start with a
//.

There may be blank lines in the data file, which your program
should accept and ignore.

The data lines will start with one of the following flag
values, indicating which item is being specified, its name, its
index, and the index of its parent - which is used to specify
the connections used to create the internal data structure (ie,
assign an item to its parent or parent ArrayList).

For most items there will be additional fields appropriate to
the class of that item.

The fields on a line are space delimited (perhaps more than
one space)

This works well with Scanner methods, such as next(),nextInt() and
nextDouble().

You may assume that the data file is correctly formatted and that
the parent links exist and are encountered in the data file as
item indices before they are referenced as parent links.

There is a Java program (CreateSeaPortDataFile.java) provided
with this package that will generate data files with various
characteristics with the correct format. You should be using the
program to generate your own data files to test various aspects of
your project programs.

Each class should have an appropriate Scanner constructor,
allowing the class to take advantage of super constructors, and
any particular constructor focusing only on the addition elements
of interest to that particular class. As an example, here's one
way to implement the PassengerShip constructor:

Extend Project 1 to use
advanced data structures and support sorting on various keys.

Elaboration:

Required data structure - the data structure specified in
Project 1:

World has SeaPort's

SeaPort has Dock's, Ship's, and Person's

Dock has a Ship

Ship has Job's

PassengerShip

CargoShip

Person has a skill

Job requires skills - optional until Project 3

PortTime

Use the HashMap class to support efficient linking of the
classes used in Project 1.

The instances of the hash map class should be local to the
readFile (Scanner) method.

These instances should be passed as explicit parameters to
other methods used when reading the data file.

For example, the body of the methods like the following
should be replaced to effectively use a <Integer,
Ship> hash map, the surrounding code needs to support
this structure:
Ship getShipByIndex (int x, java.util.HashMap <Integer,
Ship> hms) {
return hms.get(x);
} // end getDockByIndex

Since the body of this method has become trivial, perhaps
the call to this method can be simply replaced by the get
method of the HashMap.

Your code should be sure to handle a null return from this
call gracefully.

The instances should be released (go out of scope, hence
available for garbage collection) when the readFile method
returns.

Comments: The idea here, besides getting some experience
with an interesting JDK Collections class, is to change the
operation of searching for an item with a particular index
from an O(N) operation, ie searching through the entire data
structure to see if the code can find the parent index
parameter, to an O(1) operation, a hash map lookup. Of course,
this isn't so very interesting in such a small program, but
consider what might happen with hundreds of ports, thousands
of ships, and perhaps millions of persons and jobs.

Comments: Also, after the readFile operation, the indices
are no longer interesting, and could be completely eliminated
from the program. In this program, removing the index
references could be accomplished by removing those variables
from the parent class, Thing.

The project will be graded
according the criteria for the final project - see below.

Elaboration:

Required data the
data structure specified in Project 1:

World has SeaPort's

SeaPort has Dock's, Ship's, and Person's

Dock has a Ship

Ship has Job's

PassengerShip

CargoShip

Person has a skill

Job requires skills- NEW CLASS for
this project!

PortTime

Extend Project 2 to use the
Swing class JTree effectively to display the contents of the
data file.

(Optional) Implement a JTable to also
show the contents of the data file. There are lots of
options here for extending your program.

Threads:

Implement a thread for
each job
representing a task that ship requires.

Use the synchronize
directive to avoid race conditions and insure that a dock
is performing the jobs for only one ship at a time.

the jobs of a ship in
the queue should not be progressing

when all the jobs for
a ship are done, the ship should leave the dock,
allowing a ship from the que to dock

once the ship is
docked, the ships jobs should all progress

in Project 4, the jobs
will also require persons with appropriate skills.

The thread for each job
should be started as the job is read in from the
data file immediately after the entire data
file has been read.

Use delays to simulate
the progress of each job.

Use a JProgressBar for
each job to display the progress of that job.

Use JButton's on the Job
panel to allow the job to be suspended or cancelled.

As before, the GUI elements
should be distinct (as appropriate) from the other classes in
the program.

See the code at the end of
this posting for some suggestions.

Suggestions for Project 3 Job class. Here is a sample of code for
a Job class in another context, the Sorcerer's Cave project. The
code for this class will need some modifications, but this should
give you an idea of the issues involved.
In fact, you should find much of this code redundant.

Also, some of the code at the following sites might give you some
ideas about how to proceed with this project:

Extend project 3 to include making jobs wait until people with
the resources required by the job are available at the port.

Elaboration:

Reading Job specifications from a data file and adding the
required resources to each Job instance.

Resource pools - SeaPort.ArrayList <Person> list of
persons with particular skills at each port, treated as resource
pools, along with supporting assignment to ships and jobs.

Job threads - using the resource pools and supporting the
concept of blocking until required resources are available
before proceeding.

The Job threads should be efficient:

If the ship is at a dock and all the people with required
skills are available, the job should start.

Otherwise, the Job should not hold any resources if it
cannot progress.

Use synchronization to avoid race conditions.

Each Job thread should hold any required synchronization
locks for a very short period.

When a job is over, all the resources used by the job (the
people) should be released back to the port.

When all the jobs of a ship are done, the ship should depart
the dock and if there are any ships in the port que, one of
then should should be assigned to the free dock, and that
ships jobs can now try to progress.

NOTE: If a job can never progress because the port doesn't
have enough skills among all the persons at the port, the
program should report this and cancel the job.

GUI showing:

Resources in pools - how many people with skill are
currently available

Use one of the following formats: MS Word doc, docx,
OpenOffice odf, pdf, rtf.

Your project is due by midnight, EST, on the day of the date
posted in the class schedule. We do not recommend staying up all
night working on your project - it is so very easy to really mess
up a project at the last minute by working when one was overly
tired.

Your instructor's policy on late projects applies to this
project.

Submitted projects that show evidence of plagiarism will be
handled in accordance with UMUC Policy 150.25 — Academic
Dishonesty and Plagiarism.

Format

Documentation format and length. The documentation describing and
reflecting on your design and approach should be written using
Microsoft Word, and should be of reasonable length. The font size
should be 12 point. The page margins should be one inch. The
paragraphs should be double spaced. All figures, tables,
equations, and references should be properly labeled and formatted
using APA, IEEE or ACM style.

Coding hints:

Code format:

header comment block, including the following information in
each source code file:

file name

date

author

purpose

appropriate comments within the code

appropriate variable and function names

correct indentation

Errors:

code submitted with errors will be returned ungraded

Warnings:

Your program should have no warnings

Use the following compiler flag to show all warnings:javac -Xlint
*.java

optional parameters - random indicates that the exact number
is based on a random number

? will print a usage message

[0] - first parameter, a String specifying the output file
name

[1] - number of ports

[2] - number of docks per port (random)

[3] - number of passenger ships per port (random)

[4] - number of cargo ships per port (random)

[5] - number of jobs per ship (random)

[6] - number of persons per port (random)

files used to generate names

You can change the contents of these files, or substitute
simply the giving a different list of names in file(s) with
one of the following file names.

personNames.txt - 1000 names from census lists of popular
names

portNames.txt - 1741 names of ports around the world

shipNames.txt - 109,582 words from a dictionary - SIL
International Linguistics Department, 7500 W. Camp Wisdom
Road, Dallas, TX 75236, U.S.A.I have not taken the
time to remove words that might be offensive - there are
just too many of them.

skillNames.txt - just a random selection. Note that making
this longer makes it harder for jobs to find the skills they
require at the ports.