Record Class MergeOptions

java.lang.Object

java.lang.Record

de.gustavblass.fsu.fmi.roombooking.model.room.schedule.MergeOptions

Record Components:

asymmetricMergeMode - Whether to merge everything, only partially-occupied periods or nothing.

recurse - If true, merged items may be merged again if necessary; so that an arbitrary number of RoomScheduleItems may be merged into one (as long as the criteria are fulfilled). If false, two RoomScheduleItems newly merged together shall not be merged a second time.

maximumComponentLength - If set, RoomScheduleItems whose duration is longer than this Duration shall not be merged.

maximumGap - If set, then two items are considered “consecutive” if they are no further than this Duration apart. If unset, there must be no gap between two items in order to be considered consecutive.

public record MergeOptions(MergeOptions.AsymmetricMergeMode asymmetricMergeMode, boolean recurse, @Nullable Duration maximumComponentLength, @Nullable Duration maximumGap)
extends Record

Specifies the behaviour when merging two RoomScheduleItems into one.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	MergeOptions.AsymmetricMergeMode	Specifies which RoomScheduleItems are allowed to be merged.

Field Summary

Fields

Modifier and Type	Field	Description
private final MergeOptions.AsymmetricMergeMode	asymmetricMergeMode	The field for the asymmetricMergeMode record component.
private final @Nullable Duration	maximumComponentLength	The field for the maximumComponentLength record component.
private final @Nullable Duration	maximumGap	The field for the maximumGap record component.
private final boolean	recurse	The field for the recurse record component.

Constructor Summary

Constructors

Constructor	Description
MergeOptions(MergeOptions.AsymmetricMergeMode asymmetricMergeMode, boolean recurse, @Nullable Duration maximumComponentLength, @Nullable Duration maximumGap)	Creates an instance of a MergeOptions record class.

Method Summary

Modifier and Type	Method	Description
MergeOptions.AsymmetricMergeMode	asymmetricMergeMode()	Returns the value of the asymmetricMergeMode record component.
double	computeMergeScore(@NonNull RoomScheduleItem lastItem, @NonNull RoomScheduleItem newItem, int roomCapacity)	Calculates a score that indicates how well the given RoomScheduleItems are suited for merging.
final boolean	equals(Object o)	Indicates whether some other object is "equal to" this one.
@NonNull Optional<Duration>	getMaximumComponentLength()
final int	hashCode()	Returns a hash code value for this object.
boolean	isMergeRequired(@NonNull RoomScheduleItem lastItem, @NonNull RoomScheduleItem newItem, int roomCapacity)	Determines whether the given two RoomScheduleItems shall be merged.
private static boolean	isPairing(@NonNull RoomScheduleItem item1, @NonNull RoomScheduleItem item2, @NonNull RoomStatus status1, @NonNull RoomStatus status2, boolean orderMatters)	Checks whether the given RoomScheduleItems have the given RoomStatuses as the RoomScheduleItem.status.
@Nullable Duration	maximumComponentLength()	Returns the value of the maximumComponentLength record component.
@Nullable Duration	maximumGap()	Returns the value of the maximumGap record component.
boolean	recurse()	Returns the value of the recurse record component.
final String	toString()	Returns a string representation of this record class.
private boolean	violatesMergeMode(@NonNull RoomScheduleItem item1, @NonNull RoomScheduleItem item2)	Checks whether the asymmetricMergeMode prohibits merging the given two RoomScheduleItems.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

asymmetricMergeMode

@NonNull
private final MergeOptions.AsymmetricMergeMode asymmetricMergeMode

The field for the asymmetricMergeMode record component.

recurse

private final boolean recurse

The field for the recurse record component.

maximumComponentLength

@Nullable
private final @Nullable Duration maximumComponentLength

The field for the maximumComponentLength record component.

maximumGap

@Nullable
private final @Nullable Duration maximumGap

The field for the maximumGap record component.

Constructor Details

MergeOptions

public MergeOptions(@NonNull
 MergeOptions.AsymmetricMergeMode asymmetricMergeMode,
 boolean recurse,
 @Nullable
 @Nullable Duration maximumComponentLength,
 @Nullable
 @Nullable Duration maximumGap)

Creates an instance of a MergeOptions record class.

Parameters:

asymmetricMergeMode - the value for the asymmetricMergeMode record component

recurse - the value for the recurse record component

maximumComponentLength - the value for the maximumComponentLength record component

maximumGap - the value for the maximumGap record component

Method Details

getMaximumComponentLength

@Contract(pure=true)
@NonNull
public @NonNull Optional<Duration> getMaximumComponentLength()

Returns:

The maximumComponentLength in a null-safe manner.

isMergeRequired

@Contract(pure=true)
public boolean isMergeRequired(@NonNull
 @NonNull RoomScheduleItem lastItem,
 @NonNull
 @NonNull RoomScheduleItem newItem,
 int roomCapacity)

Determines whether the given two RoomScheduleItems shall be merged.

Parameters:

lastItem - The RoomScheduleItem that comes first in time.

newItem - The RoomScheduleItem that comes second in time.

roomCapacity - The Room.capacity of the Reservation.room which the given RoomScheduleItems correspond to.

Returns:

True if they shall be merged, false otherwise.

computeMergeScore

@Contract(pure=true)
public double computeMergeScore(@NonNull
 @NonNull RoomScheduleItem lastItem,
 @NonNull
 @NonNull RoomScheduleItem newItem,
 int roomCapacity)

Calculates a score that indicates how well the given RoomScheduleItems are suited for merging. The higher the score, the better the two items are suited to be merged together.

The result will be calculated as follows, in this exact order of importance:

• 0 if the two items overlap or if the newItem comes before the lastItem.
• 0 if the gap between the RoomScheduleItem.endTime of the lastItem and the RoomScheduleItem.startTime of the newItem is greater than the maximumGap.
• 0 if no maximumGap is set and the end time of the lastItem does not match the start time of the newItem.
• Double.MAX_VALUE if both items have the same RoomScheduleItem.occupancy and there is no gap.
• 0 if asymmetricMergeMode is set to NONE.
• 0 if asymmetricMergeMode prohibits merging.
• 0 if maximumComponentLength is set and both items have a longer duration.
• Otherwise, the result is min{1, |1/x|} * min{1, |1/y|} * min{1, |o - u|} * min{1, √g} ∈ (0,1] where
  • x is the lastItem's duration in minutes,
  • y is the newItem's duration in minutes,
  • o is the lastItem's RoomScheduleItem.occupancy (or 0 if null),
  • u is the newItem's occupancy (or 0 if null) and
  • g is the gap between the two items in minutes

In other words, items that are not consecutive shall never be merged, and consecutive items with the same occupancy shall always be merged.

Parameters:

lastItem - The RoomScheduleItem that comes first.

newItem - The RoomScheduleItem that comes second.

roomCapacity - The Room.capacity of the Reservation.room which the given RoomScheduleItems correspond to.

Returns:

The merge score.

Implementation Note:

This method has constant time complexity.

violatesMergeMode

@Contract(pure=true)
private boolean violatesMergeMode(@NonNull
 @NonNull RoomScheduleItem item1,
 @NonNull
 @NonNull RoomScheduleItem item2)

Checks whether the asymmetricMergeMode prohibits merging the given two RoomScheduleItems.

Merging is allowed if:

• The merge mode is not MergeOptions.AsymmetricMergeMode.PARTIAL_OCCUPANCIES or
• both items have RoomStatus.PARTIALLY_OCCUPIED as the RoomScheduleItem.status.

Merging a partially occupied and a free item

Naturally, when there is a gap between two RoomScheduleItems o1 and o2 which both indicate that the Room is partially or fully occupied, then those items are usually separated by a free item f instead of empty space: o1 f o2. If the gap – i.e. the free item f – does not exceed the maximumGap threshold, then the two partially/fully occupied items o1 and o2 shall be merged. Technically, however, the free item f which represents the gap must be included in the merge, i.e. all three items must be merged.

So, if one of the two items given to this method is a “partially occupied” item while the other one is a free item, then they are allowed to be merged if there is no gap between them and if the free item is shorter than the maximumGap duration.

If no maximumGap is set, then o1 and o2 would only be allowed to be merged if there were no gap (i.e. free item f). But there is a gap (namely item f), so merging o1 and o2 is not permitted in the absence of the maximumGap, and thus o1 cannot be merged with f either.

Parameters:

item1 - The item that comes first in time.

item2 - The item that comes second in time.

Returns:

True if the two items must not be merged because of the merge mode. False if the merge mode does not ban merging the two items. However, some other condition might prevent the items from being merged.

isPairing

@Contract(pure=true)
private static boolean isPairing(@NonNull
 @NonNull RoomScheduleItem item1,
 @NonNull
 @NonNull RoomScheduleItem item2,
 @NonNull
 @NonNull RoomStatus status1,
 @NonNull
 @NonNull RoomStatus status2,
 boolean orderMatters)

Checks whether the given RoomScheduleItems have the given RoomStatuses as the RoomScheduleItem.status.

Parameters:

item1 - The first RoomScheduleItem to check.

item2 - The second RoomScheduleItem to check.

status1 - The status that item1 must have if the orderMatters. If the order does not matter, either item1 or item2 must have this status.

status2 - The status that item2 must have if the orderMatters. If the order does not matter, either item1 or item2 must have this status.

orderMatters - If true, then item1 must match status2 and item2 must match status2. If false, then the combination “item1 matches status2 and item2 matches status1” is also permitted.

Returns:

True if the items match the specified pairing, false otherwise.

toString

public final String toString()

Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.

Specified by:

toString in class Record

Returns:

a string representation of this object

hashCode

public final int hashCode()

Returns a hash code value for this object. The value is derived from the hash code of each of the record components.

Specified by:

hashCode in class Record

Returns:

a hash code value for this object

equals

public final boolean equals(Object o)

Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.

Specified by:

equals in class Record

Parameters:

o - the object with which to compare

Returns:

true if this object is the same as the o argument; false otherwise.

asymmetricMergeMode

@NonNull
public MergeOptions.AsymmetricMergeMode asymmetricMergeMode()

Returns the value of the asymmetricMergeMode record component.

Returns:

the value of the asymmetricMergeMode record component

recurse

public boolean recurse()

Returns the value of the recurse record component.

Returns:

the value of the recurse record component

maximumComponentLength

@Nullable
public @Nullable Duration maximumComponentLength()

Returns the value of the maximumComponentLength record component.

Returns:

the value of the maximumComponentLength record component

maximumGap

@Nullable
public @Nullable Duration maximumGap()

Returns the value of the maximumGap record component.

Returns:

the value of the maximumGap record component