SectionsController.java
package edu.ucsb.cs156.frontiers.controllers;
import edu.ucsb.cs156.frontiers.entities.Course;
import edu.ucsb.cs156.frontiers.entities.Section;
import edu.ucsb.cs156.frontiers.errors.EntityNotFoundException;
import edu.ucsb.cs156.frontiers.repositories.CourseRepository;
import edu.ucsb.cs156.frontiers.repositories.SectionRepository;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import java.util.List;
import java.util.Optional;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
/**
* CRUD endpoints for the Sections table, scoped by course. Sections map a raw section identifier
* (e.g. the value that appears in a roster CSV) to a human readable label; they are used when the
* TRANSLATE_SECTIONS course option is enabled.
*/
@Tag(name = "Sections")
@RequestMapping("/api/courses/{courseId}/sections")
@RestController
@Slf4j
public class SectionsController extends ApiController {
@Autowired private SectionRepository sectionRepository;
@Autowired private CourseRepository courseRepository;
/**
* List all sections for a course, ordered by section.
*
* @param courseId the id of the course
* @return the sections for the course
*/
@Operation(summary = "List all sections for a course")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@GetMapping("")
public List<Section> getSections(@Parameter(name = "courseId") @PathVariable Long courseId) {
ensureCourseExists(courseId);
return sectionRepository.findByCourseIdOrderBySectionAsc(courseId);
}
/**
* Create a new section for a course.
*
* @param courseId the id of the course
* @param section the section identifier (must be unique within the course)
* @param label the human readable label for the section
* @param slackChannelName the Slack channel associated with the section, if any
* @return the created section
*/
@Operation(summary = "Create a new section for a course")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@PostMapping("")
public Section postSection(
@Parameter(name = "courseId") @PathVariable Long courseId,
@Parameter(name = "section") @RequestParam String section,
@Parameter(name = "label") @RequestParam String label,
@Parameter(name = "slackChannelName") @RequestParam(required = false)
String slackChannelName) {
Course course = ensureCourseExists(courseId);
String normalizedSection = normalizeRequired("section", section);
String normalizedLabel = normalizeRequired("label", label);
String normalizedSlackChannelName = normalizeOptional(slackChannelName);
if (sectionRepository.findByCourseIdAndSection(courseId, normalizedSection).isPresent()) {
throw new ResponseStatusException(
HttpStatus.CONFLICT,
"Section %s already exists for course %d".formatted(normalizedSection, courseId));
}
Section newSection =
Section.builder()
.course(course)
.section(normalizedSection)
.label(normalizedLabel)
.slackChannelName(normalizedSlackChannelName)
.build();
return sectionRepository.save(newSection);
}
/**
* Update an existing section for a course.
*
* @param courseId the id of the course
* @param id the id of the section to update
* @param section the new section identifier (must be unique within the course)
* @param label the new human readable label for the section
* @param slackChannelName the Slack channel associated with the section, if any
* @return the updated section
*/
@Operation(summary = "Update a section for a course")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@PutMapping("/{id}")
public Section putSection(
@Parameter(name = "courseId") @PathVariable Long courseId,
@Parameter(name = "id") @PathVariable Long id,
@Parameter(name = "section") @RequestParam String section,
@Parameter(name = "label") @RequestParam String label,
@Parameter(name = "slackChannelName") @RequestParam(required = false)
String slackChannelName) {
ensureCourseExists(courseId);
Section existing = findSectionInCourse(courseId, id);
String normalizedSection = normalizeRequired("section", section);
String normalizedLabel = normalizeRequired("label", label);
String normalizedSlackChannelName = normalizeOptional(slackChannelName);
Optional<Section> duplicate =
sectionRepository.findByCourseIdAndSection(courseId, normalizedSection);
if (duplicate.isPresent() && !duplicate.get().getId().equals(id)) {
throw new ResponseStatusException(
HttpStatus.CONFLICT,
"Section %s already exists for course %d".formatted(normalizedSection, courseId));
}
existing.setSection(normalizedSection);
existing.setLabel(normalizedLabel);
existing.setSlackChannelName(normalizedSlackChannelName);
return sectionRepository.save(existing);
}
/**
* Delete a section from a course.
*
* @param courseId the id of the course
* @param id the id of the section to delete
* @return a message indicating the section was deleted
*/
@Operation(summary = "Delete a section from a course")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@DeleteMapping("/{id}")
@Transactional
public Object deleteSection(
@Parameter(name = "courseId") @PathVariable Long courseId,
@Parameter(name = "id") @PathVariable Long id) {
Course course = ensureCourseExists(courseId);
Section existing = findSectionInCourse(courseId, id);
// Disconnect from course so that the cascade=ALL relationship on Course.sections
// does not cause Hibernate to re-persist the section when the course is flushed.
course.getSections().remove(existing);
existing.setCourse(null);
sectionRepository.delete(existing);
return genericMessage("Section with id %d deleted".formatted(id));
}
private Course ensureCourseExists(Long courseId) {
return courseRepository
.findById(courseId)
.orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
}
/**
* Look up a section by id and verify that it belongs to the given course. A section that exists
* but belongs to a different course is treated as not found, so that callers cannot read or
* modify sections of courses they do not have access to.
*/
private Section findSectionInCourse(Long courseId, Long id) {
return sectionRepository
.findById(id)
.filter(s -> s.getCourse().getId().equals(courseId))
.orElseThrow(() -> new EntityNotFoundException(Section.class, id));
}
private String normalizeRequired(String fieldName, String value) {
String normalized = value.strip();
if (normalized.isEmpty()) {
throw new IllegalArgumentException("%s must not be blank".formatted(fieldName));
}
return normalized;
}
/**
* Normalizes an optional field: {@code null} or blank values are treated as "not set" and
* normalized to {@code null}; otherwise the trimmed value is returned.
*/
private String normalizeOptional(String value) {
if (value == null) {
return null;
}
String normalized = value.strip();
return normalized.isEmpty() ? null : normalized;
}
}