org.apache.wicket.util.time.TimeOfDay 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 java.text.ParseException;
import java.util.Calendar;
import org.apache.wicket.util.lang.EnumeratedType;
/**
* An immutable time of day value represented as milliseconds since the most recent midnight.
*
* Values can be constructed using various factory methods:
*
* valueOf(long) where long is milliseconds since midnight
* valueOf(String) where the String is in 'h.mma' format
* valueOf(Calendar, String) where the String is in 'h.mma' format
* valueOf(Duration) where Duration is time since midnight
* valueOf(Time) where Time is some point in time today
* valueOf(Calendar, Time) where Time is some point in time today
* militaryTime(int hour, int minute, int second) for 24-hour time
* time(int hour, int minute, Meridian) where Meridian is AM or PM
* time(int hour, int minute, int second, Meridian) where Meridian is
* AM or PM
* now() to construct the current time of day
* now(Calendar) to construct the current time of day using a given
* Calendar
*
*
* If an attempt is made to construct an illegal time of day value (one that is greater than 24
* hours worth of milliseconds), an IllegalArgumentException will be thrown.
*
* Military hours, minutes and seconds of the time of day can be retrieved by calling the
* hour, minute, and second methods.
*
* The next occurrence of a given TimeOfDay can be retrieved by calling
* next() or next(Calendar).
*
* @author Jonathan Locke
* @since 1.2.6
*/
public final class TimeOfDay extends AbstractTime
{
private static final long serialVersionUID = 1L;
/** Constant for AM time. */
public static final Meridian AM = new Meridian("AM");
/** Constant for midnight. */
public static final TimeOfDay MIDNIGHT = time(12, 0, AM);
/** Constant for PM time. */
public static final Meridian PM = new Meridian("PM");
/** Constant for noon. */
public static final TimeOfDay NOON = time(12, 0, PM);
/** Typesafe AM/PM enumeration. */
public static final class Meridian extends EnumeratedType
{
private static final long serialVersionUID = 1L;
/**
* Constructor.
*
* @param name
* the meridian name (value)
*/
Meridian(final String name)
{
super(name);
}
}
/**
* Retrieves a TimeOfDay value on a 24-hour clock.
*
* @param hour
* the hour (0-23)
* @param minute
* the minute (0-59)
* @param second
* the second (0-59)
* @return the time of day
*/
public static TimeOfDay militaryTime(final int hour, final int minute, final int second)
{
if ((hour > 23) || (hour < 0))
{
throw new IllegalArgumentException("Hour " + hour + " is not valid");
}
if ((minute > 59) || (minute < 0))
{
throw new IllegalArgumentException("Minute " + minute + " is not valid");
}
if ((second > 59) || (second < 0))
{
throw new IllegalArgumentException("Second " + second + " is not valid");
}
return valueOf(Duration.hours(hour)
.add(Duration.minutes(minute))
.add(Duration.seconds(second)));
}
/**
* Retrieves the TimeOfDay representing 'now'.
*
* @return the time of day it is now
*/
public static TimeOfDay now()
{
return valueOf(Time.now());
}
/**
* Retrieves the TimeOfDay representing 'now' on the given Calendar.
*
* @param calendar
* the Calendar to use
* @return the time of day it is now on the given Calendar
*/
public static TimeOfDay now(final Calendar calendar)
{
return valueOf(calendar, Time.now());
}
/**
* Retrieves a TimeOfDay on a 12-hour clock.
*
* @param hour
* the hour (1-12)
* @param minute
* the minute (0-59)
* @param second
* the second (0-59)
* @param meridian
* AM or PM
* @return the TimeOfDay value
*/
public static TimeOfDay time(final int hour, final int minute, final int second,
final Meridian meridian)
{
if (meridian == PM)
{
if (hour == 12)
{
return militaryTime(12, minute, second);
}
else
{
return militaryTime(hour + 12, minute, second);
}
}
else
{
if (hour == 12)
{
return militaryTime(0, minute, second);
}
else
{
return militaryTime(hour, minute, second);
}
}
}
/**
* Retrieves a TimeOfDay on a 12-hour clock.
*
* @param hour
* the hour (1-12)
* @param minute
* the minute (0-59)
* @param meridian
* AM of PM
* @return the TimeOfDay value
*/
public static TimeOfDay time(final int hour, final int minute, final Meridian meridian)
{
return time(hour, minute, 0, meridian);
}
/**
* Converts a time String and Calendar to a TimeOfDay
* instance.
*
* @param calendar
* the Calendar to use when parsing time String
* @param time
* a String in 'h.mma' format
* @return the TimeOfDay on the given Calendar
* @throws ParseException
*/
public static TimeOfDay valueOf(final Calendar calendar, final String time)
throws ParseException
{
synchronized (timeFormat)
{
synchronized (calendar)
{
timeFormat.setCalendar(calendar);
return new TimeOfDay(timeFormat.parse(time).getTime());
}
}
}
/**
* Converts a Time instance and Calendar to a TimeOfDay
* instance.
*
* @param calendar
* the Calendar to use
* @param time
* a Time instance
* @return the TimeOfDay on the given Calendar
*/
public static TimeOfDay valueOf(final Calendar calendar, final Time time)
{
return militaryTime(time.getHour(calendar), time.getMinute(calendar),
time.getSecond(calendar));
}
/**
* Converts a Duration instance to a TimeOfDay instance.
*
* @param duration
* the Duration to use
* @return the TimeOfDay of the given Duration
*/
public static TimeOfDay valueOf(final Duration duration)
{
return new TimeOfDay(duration.getMilliseconds());
}
/**
* Converts a long value to a TimeOfDay instance.
*
* @param time
* the time in milliseconds today
* @return the TimeOfDay
*/
public static TimeOfDay valueOf(final long time)
{
return new TimeOfDay(time);
}
/**
* Converts a String value to a TimeOfDay instance.
*
* @param time
* a String in 'h.mma' format
* @return the TimeOfDay
* @throws ParseException
*/
public static TimeOfDay valueOf(final String time) throws ParseException
{
return valueOf(localtime, time);
}
/**
* Converts a String value to a TimeOfDay instance.
*
* @param time
* a Time to convert to TimeOfDay
* @return the TimeOfDay in the current time zone
*/
public static TimeOfDay valueOf(final Time time)
{
return valueOf(AbstractTime.localtime, time);
}
/**
* Private utility constructor forces use of static factory methods.
*
* @param time
* the time today in milliseconds
*/
private TimeOfDay(final long time)
{
super(time);
// A time of day value must be less than 1 day of milliseconds
if (Duration.valueOf(time).greaterThan(Duration.ONE_DAY))
{
throw new IllegalArgumentException("Time " + this + " is not a time of day value");
}
}
/**
* Retrieves the hour of the day.
*
* @return the hour (0-23) of this TimeOfDay
*/
public int hour()
{
return toHours(getMilliseconds());
}
/**
* Retrieves the minute.
*
* @return the minute (0-59) of this TimeOfDay
*/
public int minute()
{
return toMinutes(getMilliseconds()) % 60;
}
/**
* Retrieves the next occurrence of this TimeOfDay in local time.
*
* @return the next occurrence of this TimeOfDay in local time
*/
public Time next()
{
return next(AbstractTime.localtime);
}
/**
* Retrieves the next occurrence of this TimeOfDay on the given
* Calendar.
*
* @param calendar
* the Calendar to use
* @return the next occurrence of this TimeOfDay on the given Calendar
*/
public Time next(final Calendar calendar)
{
// Get this time of day today
final Time timeToday = Time.valueOf(calendar, this);
// If it has already passed
if (timeToday.before(Time.now()))
{
// Return the time tomorrow
return Time.valueOf(calendar, this).add(Duration.ONE_DAY);
}
else
{
// Time hasn't happened yet today
return timeToday;
}
}
/**
* Retrieves the second.
*
* @return the second (0-59)
*/
public int second()
{
return toSeconds(getMilliseconds()) % 60;
}
/**
* @see Object#toString()
*/
@Override
public String toString()
{
final int second = second();
return "" + hour() + ":" + minute() + (second != 0 ? ":" + second : "");
}
/**
* Retrieves milliseconds as hours.
*
* @param milliseconds
* milliseconds to convert
* @return converted input
*/
private int toHours(final long milliseconds)
{
return toMinutes(milliseconds) / 60;
}
/**
* Retrieves milliseconds as minutes.
*
* @param milliseconds
* milliseconds to convert
* @return converted input
*/
private int toMinutes(final long milliseconds)
{
return toSeconds(milliseconds) / 60;
}
/**
* Retrieves milliseconds as seconds.
*
* @param milliseconds
* milliseconds to convert
* @return converted input
*/
private int toSeconds(final long milliseconds)
{
return (int)(milliseconds / 1000);
}
}