assignment3.tex

\documentclass{article}
\usepackage[margin=2cm]{geometry}
\usepackage[dvips]{graphicx}
\author{Programming in Java}
\title{Assignment 4 (v1.2)}
\date{2014--15}
% \title{Assignment 2 (v1.1)}
% \date{2013--14}
% \title{Assignment 3 (v1.1)}
% \date{2012--13}
\begin{document}

\maketitle

\section{Introduction}
\label{sec:introduction}

Launching a start-up company is difficult. Apart from creating a great
product, you must talk to a lot of people to get them interested in
the project: clients, venture capital, government agencies\ldots it is
really difficult to keep track of everybody! 

When is your next meeting? Who will you meet? What did they say the
last time you talked to them?

The purpose of this assignment it writing a program to keep track of
contacts and meetings. The application will keep track of contacts,
past and future meetings, etc. When the application is closed, all
data must be stored in a text file called "\emph{contacts.txt}". This
file must be read at startup to recover all data introduced in a
former session (the format of the file if up to you: you can use XML,
comma-separated values (CSV), or any other format).

\section{Implementation details}
\label{sec:impl-deta}

The program should implement the interfaces
provided below. Classes that implement an interface should follow the
convention of having the same
name as the interface with the ``Impl'' suffix unless there is more 
than one. For
example, if there is only one class that implements
\verb+ContactManager+, it must be called \verb+ContactManagerImpl+. Be
careful with this, as it may interfere with automatic tools that will
analyse your code. 

In order to complete this piece of coursework, you must follow the
Test Driven Development (TDD) methodology. That is, you must first
write the interfaces (most of them are already provided below), then
write the tests, then write the implementation. Your commit history
should clearly show that you wrote the tests before the implementation
and not after, and that you added new functionality in small cycles of
interface--test--implementation and not big chunks of untested code in
one go. 

\subsection{ContactManager}
\label{sec:contactmanager}

% Maybe we can make them create a set that comes chronologically
% ordered? ...for next year \ \

\begin{verbatim}
import java.util.Calendar;
import java.util.List;
import java.util.Set;

/**
 * A class to manage your contacts and meetings. 
 */
public interface ContactManager {
  /**
   * Add a new meeting to be held in the future.
   * 
   * @param contacts a list of contacts that will participate in the meeting
   * @param date the date on which the meeting will take place
   * @return the ID for the meeting
   * @throws IllegalArgumentException if the meeting is set for a time in the past, 
   *     of if any contact is unknown / non-existent 
   */
  int addFutureMeeting(Set<Contact> contacts, Calendar date);

  /**
   * Returns the PAST meeting with the requested ID, or null if it there is none. 
   *
   * @param id the ID for the meeting
   * @return the meeting with the requested ID, or null if it there is none. 
   * @throws IllegalArgumentException if there is a meeting with that ID happening in the future
   */
  PastMeeting getPastMeeting(int id);

  /**
   * Returns the FUTURE meeting with the requested ID, or null if there is none. 
   * 
   * @param id the ID for the meeting
   * @return the meeting with the requested ID, or null if it there is none. 
   * @throws IllegalArgumentException if there is a meeting with that ID happening in the past
   */
  FutureMeeting getFutureMeeting(int id);

  /**
   * Returns the meeting with the requested ID, or null if it there is none. 
   * 
   * @param id the ID for the meeting
   * @return the meeting with the requested ID, or null if it there is none. 
   */
  Meeting getMeeting(int id);

  /**
   * Returns the list of future meetings scheduled with this contact.
   * 
   * If there are none, the returned list will be empty. Otherwise,
   * the list will be chronologically sorted and will not contain any
   * duplicates. 
   * 
   * @param contact one of the user's contacts
   * @return the list of future meeting(s) scheduled with this contact (maybe empty).
   * @throws IllegalArgumentException if the contact does not exist
   */
  List<Meeting> getFutureMeetingList(Contact contact);

  /**
   * Returns the list of meetings that are scheduled for, or that took
   * place on, the specified date
   * 
   * If there are none, the returned list will be empty. Otherwise,
   * the list will be chronologically sorted and will not contain any
   * duplicates. 
   * 
   * @param date the date
   * @return the list of meetings
   */
  List<Meeting> getFutureMeetingList(Calendar date);

  /**
   * Returns the list of past meetings in which this contact has participated.
   * 
   * If there are none, the returned list will be empty. Otherwise,
   * the list will be chronologically sorted and will not contain any
   * duplicates. 
   * 
   * @param contact one of the user's contacts
   * @return the list of future meeting(s) scheduled with this contact (maybe empty).
   * @throws IllegalArgumentException if the contact does not exist
   */
  List<PastMeeting> getPastMeetingList(Contact contact);

  /**
   * Create a new record for a meeting that took place in the past.
   *
   * @param contacts a list of participants
   * @param date the date on which the meeting took place
   * @param text messages to be added about the meeting. 
   * @throws IllegalArgumentException if the list of contacts is
   *      empty, or any of the contacts does not exist
   * @throws NullPointerException if any of the arguments is null
   */
  void addNewPastMeeting(Set<Contact> contacts, Calendar date, String text);

  /**
   * Add notes to a meeting. 
   * 
   * This method is used when a future meeting takes place, and is
   * then converted to a past meeting (with notes). 
   * 
   * It can be also used to add notes to a past meeting at a later date.
   * 
   * @param id the ID of the meeting
   * @param text messages to be added about the meeting.  
   * @throws IllegalArgumentException if the meeting does not exist
   * @throws IllegalStateException if the meeting is set for a date in the future
   * @throws NullPointerException if the notes are null
   */
  void addMeetingNotes(int id, String text);

  /**
   * Create a new contact with the specified name and notes.
   * 
   * @param name the name of the contact.
   * @param notes notes to be added about the contact.   
   * @throws NullPointerException if the name or the notes are null
   */
  void addNewContact(String name, String notes);

  /**
   * Returns a list containing the contacts that correspond to the IDs.
   *
   * @param ids an arbitrary number of contact IDs
   * @return a list containing the contacts that correspond to the IDs.
   * @throws IllegalArgumentException if any of the IDs does not correspond to a real contact
   */
  Set<Contact> getContacts(int... ids);

  /**
   * Returns a list with the contacts whose name contains that string. 
   * 
   * @param name the string to search for
   * @return a list with the contacts whose name contains that string. 
   * @throws NullPointerException if the parameter is null
   */
  Set<Contact> getContacts(String name);

  /**
   * Save all data to disk. 
   * 
   * This method must be executed when the program is 
   * closed and when/if the user requests it. 
   */
  void flush();
}
\end{verbatim}

\subsection{Contact}
\label{sec:contact}

\begin{verbatim}
/**
 * A contact is a person we are making business with or may do in the future. 
 * 
 * Contacts have an ID (unique), a name (probably unique, but maybe
 * not), and notes that the user may want to save about them. 
 */
public interface Contact {
  /**
   * Returns the ID of the contact.
   *
   * @return the ID of the contact.
   */
  int getId();

  /**
   * Returns the name of the contact.
   * 
   * @return the name of the contact.
   */
  String getName();

  /**
   * Returns our notes about the contact, if any. 
   * 
   * If we have not written anything about the contact, the empty
   * string is returned. 
   * 
   * @return a string with notes about the contact, maybe empty.
   */
  String getNotes();

  /**
   * Add notes about the contact.
   * 
   * @param note the notes to be added
   */
  void addNotes(String note);
}
\end{verbatim}

\subsection{Meeting}
\label{sec:meeting}

\begin{verbatim}
import java.util.Calendar;
import java.util.Set;

/**
* A class to represent meetings
*
* Meetings have unique IDs, scheduled date and a list of participating contacts
*/
public interface Meeting {
  /**
   * Returns the id of the meeting.
   * 
   * @return the id of the meeting.
   */
  int getId();

  /**
   * Return the date of the meeting.
   * 
   * @return the date of the meeting.
   */
  Calendar getDate();

  /**
   * Return the details of people that attended the meeting.
   * 
   * The list contains a minimum of one contact (if there were 
   * just two people: the user and the contact) and may contain an 
   * arbitraty number of them.
   * 
   * @return the details of people that attended the meeting.
   */
  Set<Contact> getContacts();
}
\end{verbatim}

\subsection{PastMeeting}
\label{sec:pastmeeting}

\begin{verbatim}
/**
 * A meeting that was held in the past. 
 *
 * It includes your notes about what happened and what was agreed.
 */
public interface PastMeeting extends Meeting {
  /**
   * Returns the notes from the meeting. 
   * 
   * If there are no notes, the empty string is returned. 
   * 
   * @return the notes from the meeting. 
   */
  String getNotes();
}
\end{verbatim}

\subsection{FutureMeeting}
\label{sec:futuremeeting}

\begin{verbatim}
/**
 * A meeting to be held in the future
 */
public interface FutureMeeting extends Meeting{
    // No methods here, this is just a naming interface
    // (i.e. only necessary for type checking and/or downcasting)
}
\end{verbatim}



\section{Submission and grading}
\label{sec:submission-grading}

The assignment must be pushed to a project called
\verb+ContactManager+ on your GitHub account. It will be automatically
cloned on 
%
the date specified on the Moodle site at 23h59.59 London time. 
%Friday, 24$^{th}$ January at 23h59.59 GMT (full-time students)
%
%or on 
%
%Friday 7$^{th}$ March at 23h59.59 GMT (part-time students). 
%
You are encouraged to
leave everything ready well in advance ---both the programming and
pushing it to your GitHub account--- to avoid last-minute problems 
(e.g.~GitHub may be down on that weekend for maintenance). If the
code is not available at the GitHub account by the deadline, the 
assignment will not be marked. 

The assignment will be graded according to its compliance with the
provided specification; the simplicity, clarity, and generality of
the code (including succint but illustrative comments and JavaDoc);
and the compliance with good practices of version control 
(e.g.~commiting often and in small pieces, use of descriptive commit
messages, committing only source code and not binary or class files). 

% TODO: publish a rubric

Regardless of the times you choose to \emph{push} your changes to
GitHub, you should \emph{commit} early and often. In case of suspected
plagiarism, your version control history will be used as additional
evidence to judge the case. It is in your best interest to commit very
often (and to use adequate commit messages) to make it clear that the
process of creation is entirely your own.

% ADDED THE DESCRIPTION OF ASSIGNMENT OF PROGRAMMING IN JAVA II JUST
% IN CASE IT IS USEFUL / NEEDED LATER. 

% Graded assignments

% There will be three graded assignments in Programming in Java. Each
% of them will count 5\% of the final mark for the module (the exam in
% June counts 85%).

% Assignments will be graded by the faculty team, who will provide
% both a mark and feedback for students to help them improve their
% programming skills and knowledge. Feedback will be provided as soon
% as humanly possible, possibly around two weeks after the deadline,
% and no later than four weeks after the deadline.

% The programming assignments (II and III) will be pushed by students
% to their GitHub accounts, with the right repository name as provided
% in the assignment specification. The faculty staff will clone the
% repositories with the students' assignments from GitHub on the day
% of the deadline at 23h59.59 London time, including the full version
% control history.

% Students are encouraged to have a rich version control history, not
% only to help them during the programming process but also to prove
% that their code is theirs and is not plagiarised. Students are also
% encouraged to leave everything ready well in advance —both the
% programming and pushing it to your GitHub account- to avoid
% last-minute problems (e.g. GitHub may be down on that day for
% maintenance). If the code is not available at the GitHub account by
% the deadline, the assignment will not be marked. Deadlines are long
% to help students organise their own schedules, but based on past
% years experiences we must make a point of saying: "please, do not
% leave everything for the last two weeks".

% Students should give their GitHub account details to the faculty
% (e.g. by email) as soon as possible to ensure that their assignments
% will be collected without problems.

% Assignment I

% The first assignment for Programming in Java will be a small exam on
% paper. It is intended to be useful practice for you with an eye on
% the exam in June. The exam will cover the material up to Day 11
% (Polymorphism): variables, loops, data types, methods, pointers and
% dynamic data structures, inheritance, polymorphism, basic recursion.

% The exam will take place in the same lab as always (full-timers 404,
% part-timers 407), and will last 55 minutes. It will take place at
% the start of the lecture (full-timers 13h30-14h25, part-timers
% 18h00-18h55), then we will continue working in the lab as usual.

% Full time students will sit the exam at the lab on Wednesday, 11th
% December 2013. Part time students will do it on Monday 3rd February
% 2014. It will be announced again both in the forum and in the lab
% the week before.

% Assignment II

% The second assignment for Programming in Java will require the
% implementation of a small program according to some specifications,
% defined by a Java interface. The full implementation will require
% knowledge of all aspects covered in the course up to Day 15
% (Exception handling) but many parts can be implemented before that
% material is covered in the lectures.

% The specifications will be published on the last week of November
% 2013.

% The deadline for full-time students is Friday 24th January 2014. The
% deadline for part-time students is Friday 7th March 2014.

% Assignment III

% The third assignment for Programming in Java will require the
% implementation of a small program according to some specifications
% that will require some level of concurrent programming. The
% specifications will be published on the last week of December 2013.

% The deadline for both full-time and part-time students is Friday
% 11th April 2014.

\end{document}