merge branch 'test/course-section-block' into develop

Author: david-fong

ucst-core/src/main/java/com/dvf/ucst/core/courseutils/Course.java

@@ -280,12 +280,22 @@ private CourseSection(final Element sectionElement) throws
  SecXml.OPTIONAL_WAITLIST_FLAG_ATTR.getXmlConstantValue()
  );
 
+ // parse out [CourseSectionBlock]s.
  final List<Element> blockElements = XmlUtils.getChildElementsByTagName(
  sectionElement, CourseSectionBlock.Xml.BLOCK_TAG
  );
  final Set<CourseSectionBlock> blocks = new HashSet<>(blockElements.size());
  for (final Element blockElement : blockElements) {
- blocks.add(new CourseSectionBlock(blockElement));
+ final CourseSectionBlock blockObject = new CourseSectionBlock(blockElement);
+ blocks.add(blockObject);
+ }
+ try {
+ CourseSectionBlock.InternalConflictException.checkForConflicts(blocks);
+ } catch (final CourseSectionBlock.InternalConflictException e) {
+ throw new MalformedXmlDataException("Sections were verified not to have"
+ + " scheduling conflicts during fetching from UBC's registration"
+ + " site. Perhaps the user tampered with the xml files?", e
+ );
  }
  this.blocks = Collections.unmodifiableSet(blocks);
  }

ucst-core/src/main/java/com/dvf/ucst/core/courseutils/CourseSectionBlock.java

@@ -1,15 +1,18 @@
 package com.dvf.ucst.core.courseutils;
 
 import com.dvf.ucst.core.courseutils.UbcTimeUtils.BlockTime;
-import com.dvf.ucst.core.spider.CourseWip;
-import com.dvf.ucst.utils.general.WorkInProgress;
 import com.dvf.ucst.utils.xml.MalformedXmlDataException;
 import com.dvf.ucst.utils.xml.XmlUtils;
 import org.w3c.dom.Attr;
 import org.w3c.dom.Element;
 
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
 import java.util.function.Function;
 
+import static com.dvf.ucst.core.spider.CourseWip.CourseSectionWip.*;
+
 /**
  * One of several blocks (typically 2 or 3) that describe
  * specific meeting places and times for a [CourseSection].
@@ -69,10 +72,10 @@ public BlockTime getEndTime() {
  return timeEnclosure.end;
  }
 
- public static Element createXmlOfWorkInProgress(
+ static Element createXmlOfWorkInProgress(
  final Function<XmlUtils.XmlConstant, Element> elementSupplier,
- final CourseWip.CourseSectionWip.CourseSectionBlockWip wip
- ) throws WorkInProgress.IncompleteWipException, IllegalTimeEnclosureException {
+ final CourseSectionBlockWip wip
+ ) throws IncompleteWipException, IllegalTimeEnclosureException {
  final Element blockElement = elementSupplier.apply(Xml.BLOCK_TAG);
  blockElement.setAttribute(
  Xml.DAY_OF_WEEK_ATTR.getXmlConstantValue(),
@@ -97,8 +100,75 @@ public static Element createXmlOfWorkInProgress(
  return blockElement;
  }
 
+ /**
+ * @param elementSupplier A supplier of [Element]s with a [Document] anchor that
+ * elements of the returned collection of [Elements] will eventually be added to.
+ * @param wips A collection of [CourseSectionBlockWip]s that should be complete.
+ * @return A collection of [Element]s representing [wips] through xml.
+ * @throws IncompleteWipException If an element of [wips] did not contain all the
+ * required information for this method to perform its function.
+ * @throws IllegalTimeEnclosureException See [BlockTimeEnclosure].
+ * @throws InternalConflictException If any of the provided [CourseSectionBlockWip]s
+ * have a schedule conflict between them.
+ */
+ public static Set<Element> createXmlOfWorksInProgress(
+ final Function<XmlUtils.XmlConstant, Element> elementSupplier,
+ final Set<CourseSectionBlockWip> wips
+ ) throws IncompleteWipException, IllegalTimeEnclosureException, InternalConflictException {
+ // map the wips to xml elements:
+ final Set<Element> blockElements = new HashSet<>();
+ for (final CourseSectionBlockWip wip : wips) {
+ blockElements.add(createXmlOfWorkInProgress(elementSupplier, wip));
+ }
+
+ { // check if the section block wips have any conflicts with each other:
+ final Set<CourseSectionBlock> tempBlockObjects = new HashSet<>(blockElements.size());
+ for (final Element blockElement : blockElements) {
+ try {
+ tempBlockObjects.add(new CourseSectionBlock(blockElement));
+ } catch (MalformedXmlDataException e) {
+ // this shouldn't happen
+ throw new RuntimeException("Something is either wrong with"
+ + " ::createXmlOfWorkInProgress or the xml constructor", e
+ );
+ }
+ }
+ InternalConflictException.checkForConflicts(tempBlockObjects);
+ }
+ return blockElements;
+ }
+
 
+ /**
+ * Thrown when some source of a collection of coexisting [CourseSectionBLock]s
+ * contains blocks that conflict with each other.
+ */
+ public static final class InternalConflictException extends Exception {
+ // meirl
+ private InternalConflictException(final CourseSectionBlock block1, final CourseSectionBlock block2) {
+ super(String.format("The two blocks %s and %s cannot coexist"
+ + " because they conflict with one another",
+ block1, block2
+ ));
+ assert block1.overlapsWith(block2) : "Alright. who did this?";
+ }
 
+ static void checkForConflicts(final Set<CourseSectionBlock> blocks) throws InternalConflictException {
+ final Set<CourseSectionBlock> conflictFreeAccumulator = new HashSet<>();
+ for (final CourseSectionBlock block : Collections.unmodifiableSet(blocks)) {
+ for (final CourseSectionBlock addedBlock : conflictFreeAccumulator) {
+ if (block.overlapsWith(addedBlock)) {
+ throw new InternalConflictException(block, addedBlock);
+ }
+ }
+ conflictFreeAccumulator.add(block);
+ }
+ }
+ }
+
+ /**
+ * A begin and end time with non-zero positive duration.
+ */
  static final class BlockTimeEnclosure {
 
  private final BlockTime begin;

ucst-core/src/main/java/com/dvf/ucst/core/spider/CourseSectionSpider.java

@@ -23,6 +23,8 @@ public static CourseSectionWip fetchCourseSectionFromWeb(final String courseSect
  private static <T extends CourseSectionWip> T makeNonLectureSectionWip(final Element sectionDom, final T host) {
  // work goes here.
 
+ // see CourseSectionBlock::createXmlOfWorksInProgress
+
  return host;
  }
 

ucst-core/src/main/java/com/dvf/ucst/core/spider/CourseWip.java

@@ -49,17 +49,17 @@ CourseWip setDescriptionString(String descriptionString) {
  }
 
  CourseWip setLectureSections(Set<CourseLectureSectionWip> lectureSections) {
- this.lectureSections = lectureSections;
+ this.lectureSections = Collections.unmodifiableSet(lectureSections);
  return this;
  }
 
  CourseWip setLabSections(Set<CourseSectionWip> labSections) {
- this.labSections = labSections;
+ this.labSections = Collections.unmodifiableSet(labSections);
  return this;
  }
 
  CourseWip setTutorialSections(Set<CourseSectionWip> tutorialSections) {
- this.tutorialSections = tutorialSections;
+ this.tutorialSections = Collections.unmodifiableSet(tutorialSections);
  return this;
  }
 
@@ -157,7 +157,7 @@ public CourseSectionWip setWaitlist(Boolean waitlist) {
  }
 
  final CourseSectionWip setBlocks(Set<CourseSectionBlockWip> blocks) {
- this.blocks = blocks;
+ this.blocks = Collections.unmodifiableSet(blocks);
  return this;
  }
 
@@ -215,12 +215,12 @@ public static final class CourseLectureSectionWip extends CourseSectionWip {
  private Set<String> requiredTutorialOptionIdTokens;
 
  CourseLectureSectionWip setRequiredLabOptionIdTokens(Set<String> requiredLabOptionIdTokens) {
- this.requiredLabOptionIdTokens = requiredLabOptionIdTokens;
+ this.requiredLabOptionIdTokens = Collections.unmodifiableSet(requiredLabOptionIdTokens);
  return this;
  }
 
  CourseLectureSectionWip setRequiredTutorialSectionOptions(Set<String> requiredTutorialOptionIdTokens) {
- this.requiredTutorialOptionIdTokens = requiredTutorialOptionIdTokens;
+ this.requiredTutorialOptionIdTokens = Collections.unmodifiableSet(requiredTutorialOptionIdTokens);
  return this;
  }
 

ucst-core/src/test/java/com/dvf/ucst/core/courseutils/CourseSectionBlockTest.java

@@ -3,8 +3,18 @@
 import com.dvf.ucst.core.courseutils.CourseSectionBlock.BlockTimeEnclosure;
 import com.dvf.ucst.core.courseutils.CourseSectionBlock.IllegalTimeEnclosureException;
 import com.dvf.ucst.core.courseutils.UbcTimeUtils.BlockTime;
+import com.dvf.ucst.core.spider.CourseWip.CourseSectionWip.CourseSectionBlockWip;
+import com.dvf.ucst.utils.general.WorkInProgress;
+import com.dvf.ucst.utils.xml.MalformedXmlDataException;
+import com.dvf.ucst.utils.xml.XmlIoUtils;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.function.ThrowingSupplier;
+import org.w3c.dom.Document;
+import org.w3c.dom.Element;
 
+import javax.xml.transform.TransformerException;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
@@ -15,10 +25,91 @@
 
 class CourseSectionBlockTest {
 
+ @Test
+ void fromXml() {
+
+ }
+
+ // does not add element to doc.
+ private Element createBasicBlockXml(final Document doc) {
+ final CourseSectionBlockWip wip = new CourseSectionBlockWip()
+ .setBeginTime(T0800)
+ .setEndTime(T0900)
+ .setRepetitionType(CourseSectionBlock.BlockRepetition.EVERY_WEEK)
+ .setWeekDay(CourseUtils.WeekDay.MONDAY);
+ try {
+ return CourseSectionBlock.createXmlOfWorkInProgress(
+ tagName -> doc.createElement(tagName.getXmlConstantValue()),
+ wip
+ );
+ } catch (WorkInProgress.IncompleteWipException | IllegalTimeEnclosureException e) {
+ fail("Encountered unexpected " + e.getClass() + " exception");
+ return null;
+ }
+ }
+
+
+
+ /**
+ *
+ */
+ @Nested
+ final class CourseSectionBlockWipTest {
+
+ @Test
+ void makeWip() {
+ final CourseSectionBlockWip blockWip = new CourseSectionBlockWip()
+ .setBeginTime(T0800)
+ .setEndTime(T0900)
+ .setRepetitionType(CourseSectionBlock.BlockRepetition.EVERY_WEEK)
+ .setWeekDay(CourseUtils.WeekDay.MONDAY);
+ final Set<ThrowingSupplier<Object>> getters = Set.of(
+ blockWip::getBeginTime,
+ blockWip::getEndTime,
+ blockWip::getRepetitionType,
+ blockWip::getWeekDay
+ );
+ getters.forEach(Assertions::assertDoesNotThrow);
+ }
+
+ @Test
+ void assertThrowsIncomplete() {
+ // make a block wip and don't populate its fields:
+ final CourseSectionBlockWip blockWip = new CourseSectionBlockWip();
+ final Set<ThrowingSupplier<Object>> getters = Set.of(
+ blockWip::getBeginTime,
+ blockWip::getEndTime,
+ blockWip::getRepetitionType,
+ blockWip::getWeekDay
+ );
+ getters.forEach(getter -> assertThrows(
+ WorkInProgress.IncompleteWipException.class,
+ getter::get
+ ));
+ }
+
+ @Test
+ void toXml() {
+ final Document doc = XmlIoUtils.createNewXmlDocument();
+ doc.appendChild(createBasicBlockXml(doc));
+ try {
+ assertEquals(
+ "<Block begin=\"08:00\" day=\"mon\" end=\"09:00\"/>", // "\r\n"
+ XmlIoUtils.printNodeToString(doc).trim()
+ );
+ } catch (final TransformerException e) {
+ fail("Unexpected error serializing document to string");
+ }
+ }
+ }
+
+
+
  /**
  * Tests for the private class [BlockTimeEnclosure]
  */
- static final class BlockTimeEnclosureTest {
+ @Nested
+ final class BlockTimeEnclosureTest {
 
  @Test
  void assertNoOverlaps() {
@@ -115,7 +206,7 @@ void assertIllegalEnclosure() {
  }
 
  // for sake of brevity:
- private static BlockTimeEnclosure bte(
+ private BlockTimeEnclosure bte(
  final BlockTime begin,
  final BlockTime end
  ) throws IllegalTimeEnclosureException {

ucst-utils/src/main/java/com/dvf/ucst/utils/general/WorkInProgress.java

@@ -3,13 +3,28 @@
 /**
  * Ain't nobody here but us docs.
  *
+ *
  * Implementations of this interface should have the following properties:
+ *
  * - are located in the same package as whoever will call the setters (assemble the WIP)
+ * - unless necessary, should not provide or implement any constructors
+ *
  * - all fields are non-final and private
- * - all fields have public getters, collections must be wrapped as unmodifiable
+ * - no primitive fields - box them with their respective objects
+ * - fields may have default values as long is it is clearly documented in the class doc
+ *
+ * - all fields have public getters, collections must be wrapped as unmodifiable (even if redundant)
  * - getters should throw a [IncompleteWipException] if a property is known to be incomplete
+ * - if a getter's field has a default value, it may choose to force the setter to use the
+ * default value if the input would qualify as invalid (Ex. null), and forgo the exception
+ * in the getter.
+ *
  * - all fields have package-private setters that return the instance the setter was called off of
- * - unless necessary, should not provide or implement any constructors
+ * - unless absolutely necessary, setters must wrap input collections as unmodifiable before assigning to fields
+ * - setters may perform validation and throw exceptions as long as the validation does not
+ * depend on other fields with setters (to prevent user of setters from having to write
+ * ugly code that performs the same validation externally).
+ *
  */
 public interface WorkInProgress {
 
@@ -22,6 +37,10 @@ public IncompleteWipException(final String message) {
  super(message);
  }
 
+ public IncompleteWipException(final String message, Exception e) {
+ super(message, e);
+ }
+
  /**
  * @param wip the [WorkInProgress] considered to be missing the property
  * bound to a declared field of its own by the name [fieldName].

ucst-utils/src/main/java/com/dvf/ucst/utils/xml/MalformedXmlDataException.java

@@ -8,14 +8,18 @@
  */
 public class MalformedXmlDataException extends Exception {
 
- public MalformedXmlDataException(String message) {
+ public MalformedXmlDataException(final String message) {
  super(message);
  }
 
- public MalformedXmlDataException(Exception rootCause) {
+ public MalformedXmlDataException(final Exception rootCause) {
  super(rootCause);
  }
 
+ public MalformedXmlDataException(final String message, final Exception rootCause) {
+ super(message, rootCause);
+ }
+
  public static MalformedXmlDataException noSuchUniqueChildElement(final Element host, final String tagName) {
  return new MalformedXmlDataException(String.format("A unique %s by the tag name"
  + " \"%s\" could not be found as a direct child of the host %s",