001    package net.sf.cpsolver.coursett.model;
002    
003    import java.util.Collection;
004    
005    /**
006     * Interface for student sectioning functions needed within the course timetabling solver.<br>
007     * <br>
008     * Many course offerings consist of multiple classes, with students enrolled in
009     * the course divided among them. These classes are often linked by a set of
010     * constraints, namely:
011     * <ul>
012     * <li>Each class has a limit stating the maximum number of students who can be
013     * enrolled in it.
014     * <li>A student must be enrolled in exactly one class for each subpart of a
015     * course.
016     * <li>If two subparts of a course have a parent-child relationship, a student
017     * enrolled in the parent class must also be enrolled in one of the child
018     * classes.
019     * </ul>
020     * Moreover, some of the classes of an offering may be required or prohibited
021     * for certain students, based on reservations that can be set on an offering, a
022     * configuration, or a class. <br>
023     * While the data are loaded into the solver, an initial sectioning of students into
024     * classes is processed (see {@link InitialSectioning}). However, it
025     * is still possible to improve on the number of student conflicts in the
026     * solution. This can be accomplished by moving students between alternative
027     * classes of the same course during or after the search (see
028     * {@link FinalSectioning}).
029     * 
030     * @version CourseTT 1.2 (University Course Timetabling)<br>
031     *          Copyright (C) 2014 Tomas Muller<br>
032     *          <a href="mailto:muller@unitime.org">muller@unitime.org</a><br>
033     *          <a href="http://muller.unitime.org">http://muller.unitime.org</a><br>
034     * <br>
035     *          This library is free software; you can redistribute it and/or modify
036     *          it under the terms of the GNU Lesser General Public License as
037     *          published by the Free Software Foundation; either version 3 of the
038     *          License, or (at your option) any later version. <br>
039     * <br>
040     *          This library is distributed in the hope that it will be useful, but
041     *          WITHOUT ANY WARRANTY; without even the implied warranty of
042     *          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
043     *          Lesser General Public License for more details. <br>
044     * <br>
045     *          You should have received a copy of the GNU Lesser General Public
046     *          License along with this library; if not see
047     *          <a href='http://www.gnu.org/licenses/'>http://www.gnu.org/licenses/</a>.
048     */
049    public interface StudentSectioning {
050    
051        /**
052         * Enroll students into the given offering during the initial data load.
053         * @param offeringId instructional offering id
054         * @param courseName course name
055         * @param students list of students to be sectioned
056         * @param configurations list of configurations the students are to be sectioned into
057         */
058        public void initialSectioning(Long offeringId, String courseName, Collection<Student> students, Collection<Configuration> configurations);
059        
060        /**
061         * Return true if final student sectioning is implemented. 
062         */
063        public boolean hasFinalSectioning();
064        
065        /**
066         * Run student final sectioning (switching students between sections of the same
067         * class in order to minimize overall number of student conflicts).
068         */
069        public void switchStudents(TimetableModel model);
070        
071        /**
072         * Perform sectioning on the given lecture
073         * @param lecture given lecture
074         * @param recursive recursively resection lectures affected by a student swap
075         * @param configAsWell resection students between configurations as well
076         **/
077        public void resection(Lecture lecture, boolean recursive, boolean configAsWell);
078    }