Module appointmenplanner.api
Package appointmentplanner.api

Interface Timeline

public interface Timeline
Timeline of planned appointments. The implementation of the Timeline MUST use YOUR OWN linked list implementation for its internal structure. Existing implementations or arrays/lists are not allowed. However, in the methods returning lists, collections, etc. produced by streams, the usual java classes of such kind are allowed. No need to reinvent all wheels.
Author:
Richard van den Ham r.vandenham@fontys.nl, Pieter van den Hombergh p.vandenhombergh@fontys.nl

  • Method Details

    • nrOfAppointments

      int nrOfAppointments()
      Returns the number of appointments on a day.
      Returns:
      Number of appointments on this timeline.

    • nrOfGaps

      int nrOfGaps()
      Get the number of gaps between start and en of day and between the appointments. The standard day has 4 gaps, form 8:30 to 9:00, from 10:00 to 10:30, from 11:00 to 11:10 and from 15:00 to 16:00 An empty day has 1 gap, duration the whole time between day start and day end.
      Returns:
      number of gaps between appointments and before and after.

    • start

      Instant start()
      Get the start of this timeline as instant.
      Returns:
      the start time of this timeline

    • end

      Instant end()
      Get the end of this timeline.
      Returns:
      the end time of this timeline

    • addAppointment

      Optional<Appointment> addAppointment(LocalDay forDay, AppointmentData appointment, TimePreference timePreference)
      Add a new appointment to this day. Requirements: An appointment can only be added between start time (including) and end time (excluding) of the day. AppointmentData having a duration greater than the length of the day in minutes will result in an empty Optional to be returned. If the day does not have free space to accommodate the appointment, an empty optional is returned. Appointments aren't allowed to overlap. Not all time preferences make sense without a fixed time. If the time preference is not equal to LATEST then the time preference is set to EARLIEST.
      Parameters:
      forDay - time partition to fit appointment
      appointment - the appointment to add
      timePreference - fallback strategy, if not LATEST, than set it to EARLIEST for all other preferences
      Returns:
      Appointment instance with all fields set according to AppointmentData, or empty Optional if the constraints of this day and the requested appointment can't be met.
      Throws:
      NullPointerException - If the appointmentData is null

    • addAppointment

      Optional<Appointment> addAppointment(LocalDay forDay, AppointmentData appointment, LocalTime startTime)
      Add appointment with a fixed time. If the requested slot is available, that is used and the appointment is returned. Otherwise, an empty Optional is returned.
      Parameters:
      forDay - time partition to fit appointment
      appointment - to add
      startTime - preferred start time of the appointment
      Returns:
      the added appointment or an empty Optional on failure.

    • addAppointment

      default Optional<Appointment> addAppointment(LocalDay forDay, AppointmentRequest appointmentRequest)
      Create an appointment based on previous appointmentRequest.
      Parameters:
      forDay - time partition to fit appointment
      appointmentRequest - for this appointment.
      Returns:
      the added appointment or an empty Optional on failure.

    • addAppointment

      Optional<Appointment> addAppointment(LocalDay forDay, AppointmentData appointment, LocalTime startTime, TimePreference fallback)
      Add appointment with a fixed time. If the requested slot is available, that is used and the appointment is returned. Otherwise, the fallback time preference is tried.
      Parameters:
      forDay - time partition to fit appointment
      appointment - to add
      startTime - preferred start time of the appointment
      fallback - time preference as fall back if the fixed time does not apply.
      Returns:
      the added appointment or an empty Optional on failure.

    • removeAppointment

      AppointmentRequest removeAppointment(Appointment appointment)
      Removes the given appointment, returning the AppointmentRequest of that appointment, if found. This day is searched for a non-free time slot matching the appointment. The returned data could be used to re-plan the appointment.
      Parameters:
      appointment - to remove
      Returns:
      the AppointmentRequest of the removed appointment or null if the appointment is not found.

    • removeAppointments

      List<AppointmentRequest> removeAppointments(Predicate<Appointment> filter)
      Removes appointments with description that matches a filter.
      Parameters:
      filter - to determine which items to remove.
      Returns:
      the list of AppointmentRequests of removed appointments.

    • findAppointments

      List<Appointment> findAppointments(Predicate<Appointment> filter)
      Finds all appointments matching given filter.
      Parameters:
      filter - to determine which items to select.
      Returns:
      list of matching appointments.

    • appointments

      default List<Appointment> appointments()
      Finds all appointments for this TimeLine.
      Returns:
      list of all appointments.

    • appointmentStream

      Stream<Appointment> appointmentStream()
      Stream of all appointments.
      Returns:
      a stream of all appointments.

    • contains

      boolean contains(Appointment appointment)
      Check if day contains the given appointment.
      Parameters:
      appointment - to search for.
      Returns:
      true if the Appointment is part of the Timeline, false otherwise.

    • findGapsFitting

      List<TimeSlot> findGapsFitting(Duration duration)
      This method finds all time gaps that can accommodate an appointment of the given duration in natural order.
      Parameters:
      duration - the requested duration for an appointment
      Returns:
      a list of gaps in which the appointment can be scheduled.

    • canAddAppointmentOfDuration

      boolean canAddAppointmentOfDuration(Duration duration)
      Check if an appointment of the given duration can be scheduled.
      Parameters:
      duration - of the appointment
      Returns:
      true is there is a sufficiently big gap, false otherwise

    • findGapsFittingReversed

      List<TimeSlot> findGapsFittingReversed(Duration duration)
      This method finds all time gaps that can accommodate an appointment of the given duration in last to first order.
      Parameters:
      duration - the requested duration for an appointment
      Returns:
      a list of start times on which an appointment can be scheduled

    • findGapsFittingSmallestFirst

      List<TimeSlot> findGapsFittingSmallestFirst(Duration duration)
      Get the gaps matching the given duration, smallest fitting first.
      Parameters:
      duration - required
      Returns:
      list of all gaps fitting, ordered, smallest gap first.

    • findGapsFittingLargestFirst

      List<TimeSlot> findGapsFittingLargestFirst(Duration duration)
      Get the gaps matching the given duration, largest fitting first.
      Parameters:
      duration - required
      Returns:
      list of all gaps fitting, ordered, largest gap first.

    • findMatchingFreeSlotsOfDuration

      List<TimeSlot> findMatchingFreeSlotsOfDuration(Duration minLength, List<Timeline> other)
      Find matching free time slots in this and other TimeLines. To facilitate appointment proposals.
      Parameters:
      minLength - minimum length required.
      other - day plans
      Returns:
      the list of free slots that all DayPlans share.