ass2-service/api/src/main/java/dst/ass2/service/api/courseplan/ICoursePlanService.java

   1 package dst.ass2.service.api.courseplan;
   2
   3 /**
   4  * Manages {@link CoursePlan} instances. Note that {@link CoursePlan}s are transient entities and do not have to be
   5  * persisted. They can be kept in memory for the duration of the application session.
   6  */
   7 public interface ICoursePlanService {
   8
   9     /**
  10      * Creates a new course plan for the participant of the given membership relation. The service is responsible for
  11      * assigning a unique CoursePlan ID in a thread-safe way.
  12      *
  13      * @param membershipId the membership id
  14      * @return a new course plan object
  15      * @throws EntityNotFoundException if the membership does not exist
  16      */
  17     CoursePlan create(Long membershipId) throws EntityNotFoundException;
  18
  19     /**
  20      * Removes the CoursePlan with the given id.
  21      *
  22      * @param coursePlanId the course plan id
  23      * @throws EntityNotFoundException if the course plan does not exist
  24      */
  25     void delete(Long coursePlanId) throws EntityNotFoundException;
  26
  27     /**
  28      * Finds the CoursePlan with the given id.
  29      *
  30      * @param coursePlanId the course plan id
  31      * @return the course plan instance, or null if it does not exist
  32      */
  33     CoursePlan find(Long coursePlanId);
  34
  35     /**
  36      * Adds the given course to the given course plan if possible (i.e., if the owner of the course plan is eligible to
  37      * enroll in the course, and the course has sufficient capacity). Does nothing if the course is already in the
  38      * course plan.
  39      *
  40      * @param courseId the id of the course to add
  41      * @return true if the course was added, false if the course was already in the course plan
  42      * @throws EntityNotFoundException if a referenced membership or course could not be found
  43      * @throws CourseNotAvailableException if the course doesn't exist or can't be enrolled (e.g., no premium membership
  44      * or not enough capacity)
  45      */
  46     boolean addCourse(CoursePlan plan, Long courseId) throws EntityNotFoundException, CourseNotAvailableException;
  47
  48     /**
  49      * Removes the given course from the given course plan.
  50      *
  51      * @param plan course plan to remove the course from
  52      * @param courseId the id of the course to remove
  53      * @return true if the course was removed, false if the course was not contained in the course plan
  54      */
  55     boolean removeCourse(CoursePlan plan, Long courseId);
  56
  57     /**
  58      * Submits the given course plan by attempting to enroll the owner of the course plan into each course in the plan.
  59      * This method should create and persist the necessary {@code IEnrollment} objects in an atomic way, i.e., only if
  60      * all courses can be enrolled. Otherwise a given transaction should be rolled back. If the commit was successful,
  61      * the course plan should be removed from the in-memory storage.
  62      *
  63      * @throws CourseNotAvailableException if the course plan couldn't be submitted (e.g., because a course enrollment
  64      * couldn't be finalized because the capacity changed)
  65      * @throws EntityNotFoundException if a referenced membership or course could not be found
  66      */
  67     void commit(CoursePlan coursePlan) throws EntityNotFoundException, CourseNotAvailableException;
  68 }