org.apache.wicket.util.time.TimeFrame Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.wicket.util.time;
import org.apache.wicket.util.lang.Objects;
/**
* Immutable class which represents an interval of time with a beginning and an end. The beginning
* value is inclusive and the end value is exclusive. In other words, the time frame of 1pm to 2pm
* includes 1pm, but not 2pm. 1:59:59 is the last value in the TimeFrame.
*
* TimeFrames can be constructed by calling the valueOf static factory
* methods valueOf(Time, Time) (yielding a TimeFrame between two absolute
* times) and valueOf(Time, Duration) yielding a TimeFrame starting at an
* absolute time and having a given length.
*
* The start and end of a TimeFrame can be retrieved by calling getStart
* and getEnd. Its duration can be retrieved by calling getDuration.
*
* The contains(Time) method can be called to determine if a TimeFrame
* contains a given point in time. The overlaps(TimeFrame) method can be called to
* determine if two TimeFrames overlap.
*
* The eachDay(TimeOfDay, TimeOfDay) will return a TimeFrameSource which
* generates a TimeFrame using the two times of day. In other words, if the start is
* 3pm and the end is 4pm, the TimeFrameSource returned will yield 3-4pm on the day it
* is called (each day).
*
* @author Jonathan Locke
* @since 1.2.6
*/
public final class TimeFrame implements ITimeFrameSource
{
private static final long serialVersionUID = 1L;
/** end of this TimeFrame */
private final Time end;
/** beginning of this TimeFrame */
private final Time start;
/**
* Creates an ITimeFrameSource source for start and end TimeOfDays.
* For example, called with 3pm and 5pm as parameters, the TimeFrame source
* returned would produce TimeFrame objects representing 3pm-5pm on whatever day it
* is when the caller calls the TimeFrameSource interface.
*
* @param startTimeOfDay
* the start TimeOfDay for this TimeFrame each day
* @param endTimeOfDay
* the end TimeOfDay for this TimeFrame each day
* @return a TimeFrameSource which will return the specified TimeFrame
* each day
*/
public static ITimeFrameSource eachDay(final TimeOfDay startTimeOfDay,
final TimeOfDay endTimeOfDay)
{
check(startTimeOfDay, endTimeOfDay);
return new ITimeFrameSource()
{
private static final long serialVersionUID = 1L;
@Override
public TimeFrame getTimeFrame()
{
return new TimeFrame(Time.valueOf(startTimeOfDay), Time.valueOf(endTimeOfDay));
}
};
}
/**
* Creates a TimeFrame for a start Time and Duration.
*
* @param start
* the start Time
* @param duration
* the Duration
* @return the TimeFrame
* @throws IllegalArgumentException
* thrown if start Time value is before end Time value
*/
public static TimeFrame valueOf(final Time start, final Duration duration)
{
return new TimeFrame(start, start.add(duration));
}
/**
* Creates a TimeFrame for given start and end Times.
*
* @param start
* the start Time
* @param end
* the end Time
* @return the TimeFrame
* @throws IllegalArgumentException
* thrown if start Time value is before end Time value
*/
public static TimeFrame valueOf(final Time start, final Time end)
{
return new TimeFrame(start, end);
}
/**
* Checks consistency of start and end AbstractTimeValue values, ensuring that the
* end value is less than the start value.
*
* @param start
* start AbstractTimeValue value
* @param end
* end AbstractTimeValue value
* @throws IllegalArgumentException
* thrown if end is less than start
*/
private static void check(final AbstractTimeValue start, final AbstractTimeValue end)
{
// Throw illegal argument exception if end is less than start
if (end.lessThan(start))
{
throw new IllegalArgumentException("Start time of time frame " + start +
" was after end time " + end);
}
}
/**
* Private constructor to force use of static factory methods.
*
* @param start
* the start Time
* @param end
* the end Time
* @throws IllegalArgumentException
* thrown if start Time value is before end Time value
*/
private TimeFrame(final Time start, final Time end)
{
check(start, end);
this.start = start;
this.end = end;
}
/**
* Determines if this TimeFrame contains a given point in time.
*
* @param time
* the Time to check
* @return true if this TimeFrame contains the given time
*/
public boolean contains(final Time time)
{
return (start.equals(time) || start.before(time)) && end.after(time);
}
/**
* Retrieves the Duration of this TimeFrame.
*
* @return the Duration of this TimeFrame
*/
public Duration getDuration()
{
return end.subtract(start);
}
/**
* Retrieves the end Time of this TimeFrame.
*
* @return the end of this TimeFrame
*/
public Time getEnd()
{
return end;
}
/**
* Retrieves the start Time of this TimeFrame.
*
* @return the start of this TimeFrame
*/
public Time getStart()
{
return start;
}
/**
* Implementation of ITimeFrameSource that simply returns this
* TimeFrame.
*
* @return this TimeFrame
*/
@Override
public TimeFrame getTimeFrame()
{
return this;
}
/**
* Determines if two TimeFrames overlap.
*
* @param timeframe
* the TimeFrame to test
* @return true if the given TimeFrame overlaps this one
*/
public boolean overlaps(final TimeFrame timeframe)
{
return contains(timeframe.start) || contains(timeframe.end) || timeframe.contains(start) ||
timeframe.contains(end);
}
@Override
public int hashCode()
{
return Objects.hashCode(start, end);
}
@Override
public boolean equals(final Object obj)
{
if (this == obj)
{
return true;
}
if (obj == null)
{
return false;
}
if (getClass() != obj.getClass())
{
return false;
}
TimeFrame other = (TimeFrame)obj;
return Objects.equal(start, other.start) && Objects.equal(end, other.end);
}
/**
* Converts this TimeFrame to a String representation.
*
* @return a String representation of this object
*/
@Override
public String toString()
{
return "[start=" + start + ", end=" + end + "]";
}
}