Interface RoomMapper

public interface RoomMapper
Converts Rooms to data-transfer objects.

  • Method Details

    • toDto

      RoomDTO toDto(Room room)
      Converts a general Room to a RoomDTO.
      Parameters:
      room - The Room that shall be turned into a data-transfer object. If it is a ConferenceRoom, then information will be lost, because the common equipment only exists on the ConferenceRoom class, but not on the Room class.
      Returns:
      The given Room as a data-transfer object.
      Implementation Note:
      The RoomDTO.commonEquipment is mapped by createRoom(NewRoomDTO).

    • toDto

      RoomDTO toDto(ConferenceRoom room)
      Converts a ConferenceRoom to a RoomDTO.
      Parameters:
      room - The Room that shall be turned into a data-transfer object.
      Returns:
      The given ConferenceRoom as a data-transfer object.

    • fromDto

      Room fromDto(NewRoomDTO newRoomDTO) throws de.gustavblass.commons.exceptions.IllegalArgumentException
      Converts a NewRoomDTO to a Room.
      Parameters:
      newRoomDTO - The data-transfer object to turn into a proper model object.
      Returns:
      The given DTO as a proper Room. Will not have a Room.id and no Room.reservations.
      Throws:
      de.gustavblass.commons.exceptions.IllegalArgumentException - Because of Room.setCapacity(int).

    • toSummaryDto

      RoomSummaryDTO toSummaryDto(Room room)
      Converts a given Room to a RoomSummaryDTO.
      Parameters:
      room - The Room that shall become a summarised data-transfer object.
      Returns:
      The summarised data-transfer object created from the given Room.

    • createRoom

      @NonNull default @NonNull Room createRoom(@NonNull @NonNull NewRoomDTO dto)

      Creates a new QuietStudyRoom or ConferenceRoom, depending on the NewRoomDTO.type.

      Adds the NewRoomDTO.individualEquipment and – possibly – the NewRoomDTO.commonEquipment to the Room. Sets the new Room as the back-reference on the individual equipment.

      Parameters:
      dto - The data-transfer object which the new Room shall be based on.
      Returns:
      The new Room of the correct concrete class and with the DTO's equipment.
      Implementation Note:
      1. Why is this method necessary?

      This method is necessary because

      • MapStruct is apparently unable to choose the correct concrete implementation of the abstract Room class,
      • it could not be determined how to tell MapStruct to set up the back-reference on the individual equipment,
      • MapStruct is unable to map NewRoomDTO.commonEquipment to ConferenceRoom.commonEquipment, because the return type is the abstract Room class.
      2. Why does this method not throw an exception for illegal common equipment?

      As specified elsewhere, NewRoomDTO.commonEquipment must only be specified if NewRoomDTO.type is set to RoomType.CONFERENCE_ROOM. However, if this requirement is not met, this method does not throw an exception and instead ignores the common equipment.

      2.1. The critical error case

      This may be counterintuitive, but has a very specific reason. Imagine this scenario:

      1. User sets the room type to conference room.
      2. User selects several types of common equipment.
      3. User switches the room type back to RoomType.QUIET_STUDY_ROOM.
      4. User presses “submit”.

      Then, the HTTP request would still include the common equipment from step 2 because the respective HTML input fields have not been reset. The server would yell at the user: “How dare you select any common equipment for a quiet-study room?!”

      However, we absolutely do not want the user to manually unselect all the common equipment, so the common equipment must be unselected automatically for the user.

      2.2. Approaches to automatically reset the input fields

      CSS can only (visually) hide the common equipment's HTML input fields, but cannot change their actual values. So, in order to unset the common-equipment whenever the user switches from RoomType.CONFERENCE_ROOM to RoomType.QUIET_STUDY_ROOM, we would have to either …

      1. … rely on (i.e. mandatorily require) JavaScript (which is not desirable for accessibility reasons) or
      2. make an HTTP request asking the server to reset the common equipment in the form. Such an HTTP request could only be made with a special submit button. However, if we did nothing besides adding the new submit button, the server would think that the HTTP request serves the purpose of creating a new Room. So, in order to tell the server that the second button is only meant to reset the common equipment, we would either …
        • … need to use a different form action path (but the room-type input field can only be part of one form, so this option is impossible) or
        • add a special input HTML element, but – again – we could not modify its value dynamically.

      In other words, option 2 cannot be implemented. Only option 1 can be implemented, but would not work for any user who has disabled JavaScript.

      3. Conclusion

      Therefore, if we do not want to impose a JavaScript requirement on the users, we must silently discard the common equipment for quiet-study rooms.

      Why does this method not throw an exception for individual equipment whose count is zero?

      Once again, without JavaScript, we cannot modify the values of the individual-equipment's HTML input fields. Therefore, on the server side, we cannot distinguish between these cases:

      1. The user forgot to select a valid equipment count.
      2. The user set the IndividualEquipment.count to zero because they want no individual equipment of that RoomEquipment.type in the new Room.

      Consequently, we can only ignore individual equipment where count == 0.

    • convertCommonEquipmentToDto

      @NonNull default @NonNull Set<String> convertCommonEquipmentToDto(@NonNull @NonNull Set<CommonEquipment> commonEquipment)
      Converts a Set of CommonEquipment to a Set of CommonEquipmentType. This is done because the only additional information a CommonEquipment object holds is a database ID, which is irrelevant when communicating the facilities of a ConferenceRoom.
      Parameters:
      commonEquipment - The CommonEquipment that shall be reduced to the matching CommonEquipmentTypes.
      Returns:
      The CommonEquipmentTypes present in the given Set.