You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by iv...@apache.org on 2007/09/24 23:34:48 UTC
svn commit: r578985 - in
/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util: time/
upload/
Author: ivaynberg
Date: Mon Sep 24 14:34:46 2007
New Revision: 578985
URL: http://svn.apache.org/viewvc?rev=578985&view=rev
Log:
WICKET-1000: javadoc cleanup
Modified:
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTime.java
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTimeValue.java
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Duration.java
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/ITimeFrameSource.java
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Time.java
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeFrame.java
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeMap.java
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeOfDay.java
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/package.html
wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/upload/package.html
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTime.java
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTime.java?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTime.java (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTime.java Mon Sep 24 14:34:46 2007
@@ -22,23 +22,21 @@
/**
* Abstract base class for subclasses that represent a point in time (as opposed
- * to a duration of time).
+ * to a {@link Duration} of time).
*
* @author Jonathan Locke
+ * @since 1.2.6
*/
abstract class AbstractTime extends AbstractTimeValue
{
- /** Calendar for the local timezone */
+ /** calendar for the local time zone */
static final Calendar localtime = Calendar.getInstance();
- /** Time format */
+ /** time format */
static final SimpleDateFormat timeFormat = new SimpleDateFormat("h.mma");
/**
- * Package local constructor for package subclasses only
- *
- * @param milliseconds
- * The number of milliseconds in this time value
+ * @see AbstractTimeValue
*/
AbstractTime(final long milliseconds)
{
@@ -46,9 +44,13 @@
}
/**
+ * Returns <code>true</code> if this <code>Time</code> value is after
+ * the given <code>Time</code> argument's value.
+ *
* @param that
- * The time to compare with
- * @return True if this time value is after that time value
+ * the <code>AbstractTimeValue</code> to compare with
+ * @return <code>true</code> if this <code>Time</code> value is after
+ * <code>that</code> <code>Time</code> value
*/
public final boolean after(final AbstractTimeValue that)
{
@@ -56,9 +58,13 @@
}
/**
+ * Returns <code>true</code> if this <code>Time</code> value is before
+ * the given <code>Time</code> argument's value.
+ *
* @param that
- * The time to compare with
- * @return True if this time value is before that time value
+ * the <code>AbstractTimeValue</code> to compare with
+ * @return <code>true</code> if this <code>Time</code> value is before
+ * <code>that</code> <code>Time</code> value
*/
public final boolean before(final AbstractTimeValue that)
{
@@ -66,9 +72,10 @@
}
/**
- * Converts this time to a time string using the formatter h.mma
+ * Converts this <code>Time</code> to a time <code>String</code> using
+ * the formatter 'h.mma'.
*
- * @return The date string
+ * @return the <code>Time</code> <code>String</code>
*/
public final String toTimeString()
{
@@ -76,11 +83,12 @@
}
/**
- * Converts this time to a date string using the date formatter h.mma
+ * Converts this <code>Time</code> to a <code>Date String</code> using
+ * the <code>Date</code> formatter 'h.mma'.
*
* @param calendar
- * The calendar to use in the conversion
- * @return The date string
+ * the <code>Calendar</code> to use in the conversion
+ * @return the <code>Date</code> <code>String</code>
*/
public final String toTimeString(final Calendar calendar)
{
@@ -95,9 +103,10 @@
}
/**
- * Converts this time to a string suitable for use in a filesystem name
+ * Converts this <code>Time</code> to a <code>String</code> suitable for
+ * use in a file system name.
*
- * @return This time as a formatted string
+ * @return this <code>Time</code> as a formatted <code>String</code>
*/
public String toString()
{
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTimeValue.java
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTimeValue.java?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTimeValue.java (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/AbstractTimeValue.java Mon Sep 24 14:34:46 2007
@@ -23,14 +23,15 @@
* and typical operations on such values.
*
* @author Jonathan Locke
+ * @since 1.2.6
*/
abstract class AbstractTimeValue extends LongValue
{
/**
- * Package local constructor for package subclasses only
+ * Package local constructor for package subclasses only.
*
* @param milliseconds
- * The number of milliseconds in this time value
+ * the number of milliseconds in this <code>Time</code> value
*/
AbstractTimeValue(final long milliseconds)
{
@@ -38,7 +39,9 @@
}
/**
- * @return Number of milliseconds in this abstract time value
+ * Retrieves the number of milliseconds in this <code>Time</code> value.
+ *
+ * @return the number of milliseconds in this <code>Time</code> value
*/
public final long getMilliseconds()
{
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Duration.java
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Duration.java?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Duration.java (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Duration.java Mon Sep 24 14:34:46 2007
@@ -27,70 +27,77 @@
/**
- * A duration is an immutable length of time stored as a number of milliseconds.
- * Various factory and conversion methods are available for convenience.
- * <P>
+ * A <code>Duration</code> is an immutable length of time stored as a number
+ * of milliseconds. Various factory and conversion methods are available for
+ * convenience.
+ * <p>
* These static factory methods allow easy construction of value objects using
- * either long values like seconds(2034) or hours(3):
+ * either long values like <code>seconds(2034)</code> or <code>hours(3)</code>:
* <p>
* <ul>
- * <li>Duration.milliseconds(long)
- * <li>Duration.seconds(int)
- * <li>Duration.minutes(int)
- * <li>Duration.hours(int)
- * <li>Duration.days(int)
+ * <li><code>Duration.milliseconds(long)</code>
+ * <li><code>Duration.seconds(int)</code>
+ * <li><code>Duration.minutes(int)</code>
+ * <li><code>Duration.hours(int)</code>
+ * <li><code>Duration.days(int)</code>
* </ul>
* <p>
- * or double precision floating point values like days(3.2):
+ * ...or double-precision floating point values like <code>days(3.2)</code>:
* <p>
* <ul>
- * <li>Duration.milliseconds(double)
- * <li>Duration.seconds(double)
- * <li>Duration.minutes(double)
- * <li>Duration.hours(double)
- * <li>Duration.days(double)
+ * <li><code>Duration.milliseconds(double)</code>
+ * <li><code>Duration.seconds(double)</code>
+ * <li><code>Duration.minutes(double)</code>
+ * <li><code>Duration.hours(double)</code>
+ * <li><code>Duration.days(double)</code>
* </ul>
* <p>
- * In the case of milliseconds(double), the value will be rounded off to the
- * nearest integral millisecond using Math.round().
+ * In the case of <code>milliseconds(double)</code>, the value will be
+ * rounded off to the nearest integral millisecond using
+ * <code>Math.round()</code>.
* <p>
- * The precise number of milliseconds represented by a Duration object can be
- * retrieved by calling the milliseconds() method. The value of a Duration
- * object in a given unit like days or hours can be retrieved by calling one of
- * the following unit methods, each of which returns a double precision floating
- * point number:
+ * The precise number of milliseconds represented by a <code>Duration</code>
+ * object can be retrieved by calling the <code>getMilliseconds</code> method.
+ * The value of a <code>Duration</code> object in a given unit like days or
+ * hours can be retrieved by calling one of the following unit methods, each of
+ * which returns a double-precision floating point number:
* <p>
* <ul>
- * <li>seconds()
- * <li>minutes()
- * <li>hours()
- * <li>days()
+ * <li><code>seconds()</code>
+ * <li><code>minutes()</code>
+ * <li><code>hours()</code>
+ * <li><code>days()</code>
* </ul>
* <p>
- * Values can be added and subtracted using the add() and subtract() methods,
- * each of which returns a new immutable Duration object.
+ * Values can be added and subtracted using the <code>add(Duration)</code> and
+ * <code>subtract(Duration)</code> methods, each of which returns a new
+ * immutable <code>Duration</code> object.
+ * <p>
+ * <code>String</code> values can be converted to <code>Duration</code>
+ * objects using the static <code>valueOf</code> factory methods. The
+ * <code>String</code> format is the opposite of the one created by
+ * <code>toString()</code>, which converts a <code>Duration</code> object
+ * to a readable form, such as "3.2 hours" or "32.5 minutes". Valid units are:
+ * milliseconds, seconds, minutes hours and days. Correct English plural forms
+ * are used in creating <code>String</code> values and are parsed as well. The
+ * <code>Locale</code> is respected and "," will be used instead of "." in the
+ * Eurozone.
* <p>
- * String values can be converted to Duration objects using the static valueOf
- * factory methods. The string format is the opposite of the one created by
- * toString(), which converts a Duration object to a readable form, such as "3.2
- * hours" or "32.5 minutes". Valid units are: milliseconds, seconds, minutes
- * hours and days. Correct English plural forms are used in creating string
- * values and are parsed as well. The Locale is respected and "," will be used
- * instead of "." in the Eurozone.
- * <p>
- * The benchmark method will "benchmark" a Runnable or an ICode implementing
- * object, returning a Duration object that represents the amount of time
- * elapsed in running the code.
+ * The benchmark method will "benchmark" a <code>Runnable</code> or an
+ * {@link ICode} implementing object, returning a <code>Duration</code> object
+ * that represents the amount of time elapsed in running the code.
* <p>
- * Finally, the sleep() method will sleep for the value of a Duration.
+ * Finally, the <code>sleep</code> method will sleep for the value of a
+ * <code>Duration</code>.
*
* @author Jonathan Locke
+ * @since 1.2.6
*/
public class Duration extends AbstractTimeValue
{
private static final long serialVersionUID = 1L;
- /** Constant for maximum duration */
+ /** Constant for maximum duration. */
public static final Duration MAXIMUM = milliseconds(Long.MAX_VALUE);
/** Constant for no duration. */
@@ -111,17 +118,19 @@
/** Constant for one week. */
public static final Duration ONE_WEEK = days(7);
- /** Pattern to match strings. */
+ /** pattern to match strings */
private static final Pattern pattern = Pattern.compile(
"([0-9]+([.,][0-9]+)?)\\s+(millisecond|second|minute|hour|day)s?",
Pattern.CASE_INSENSITIVE);
/**
+ * Benchmark the given command.
+ *
* @param code
- * The code
+ * an <code>ICode</code>
* @param log
- * Optional log to use with errors and exceptions
- * @return The duration it took to run the code
+ * optional logger to use with errors and exceptions
+ * @return the <code>Time</code> value it took to run the code
*/
public static Duration benchmark(final ICode code, final Logger log)
{
@@ -139,8 +148,8 @@
* Benchmark the given command.
*
* @param code
- * The code
- * @return The duration it took to run the code
+ * a <code>Runnable</code>
+ * @return the <code>Time</code> value it took to run the code
*/
public static Duration benchmark(final Runnable code)
{
@@ -155,10 +164,11 @@
}
/**
- * Gets the duration based on days.
+ * Retrieves the <code>Duration</code> based on days.
*
* @param days
- * @return duration
+ * days <code>double</code> value
+ * @return the <code>Duration</code> based on days
*/
public static Duration days(final double days)
{
@@ -166,10 +176,11 @@
}
/**
- * Gets the duration based on days.
+ * Retrieves the <code>Duration</code> based on days.
*
* @param days
- * @return duration
+ * days <code>int</code> value
+ * @return the <code>Duration</code> based on days
*/
public static Duration days(final int days)
{
@@ -177,12 +188,13 @@
}
/**
- * The amount of time elapsed since start time
+ * Calculates the amount of time elapsed since start time.
*
* @param start
- * The start time
- * @return The elapsed period
- * @throws IllegalStateException Thrown if start is in the future
+ * the start <code>Time</code>
+ * @return the elapsed period as a <code>Duration</code>
+ * @throws IllegalStateException
+ * if start <code>Time</code> is in the future
*/
public static Duration elapsed(final Time start)
{
@@ -190,10 +202,11 @@
}
/**
- * Gets the duration based on hours.
+ * Retrieves the <code>Duration</code> based on hours.
*
* @param hours
- * @return duration
+ * hours <code>double</code> value
+ * @return the <code>Duration</code> based on hours
*/
public static Duration hours(final double hours)
{
@@ -201,10 +214,11 @@
}
/**
- * Gets the duration based on hours.
+ * Retrieves the <code>Duration</code> based on hours.
*
* @param hours
- * @return duration
+ * hours <code>int</code> value
+ * @return the <code>Duration</code> based on hours
*/
public static Duration hours(final int hours)
{
@@ -212,10 +226,11 @@
}
/**
- * Gets the duration based on milliseconds.
+ * Retrieves the <code>Duration</code> based on milliseconds.
*
* @param milliseconds
- * @return duration
+ * milliseconds <code>double</code> value
+ * @return the <code>Duration</code> based on milliseconds
*/
public static Duration milliseconds(final double milliseconds)
{
@@ -223,10 +238,11 @@
}
/**
- * Gets the duration based on miliseconds.
+ * Retrieves the <code>Duration</code> based on miliseconds.
*
* @param milliseconds
- * @return duration
+ * milliseconds <code>long</code> value
+ * @return the <code>Duration</code> based on milliseconds
*/
public static Duration milliseconds(final long milliseconds)
{
@@ -234,10 +250,11 @@
}
/**
- * Gets the duration based on minutes.
+ * Retrieves the <code>Duration</code> based on minutes.
*
* @param minutes
- * @return duration
+ * minutes <code>double</code> value
+ * @return the <code>Duration</code> based on minutes
*/
public static Duration minutes(final double minutes)
{
@@ -245,10 +262,11 @@
}
/**
- * Gets the duration based on minutes.
+ * Retrieves the <code>Duration</code> based on minutes.
*
* @param minutes
- * @return duration
+ * minutes <code>int</code> value
+ * @return the <code>Duration</code> based on minutes
*/
public static Duration minutes(final int minutes)
{
@@ -256,10 +274,11 @@
}
/**
- * Gets the duration based on seconds.
+ * Retrieves the <code>Duration</code> based on seconds.
*
* @param seconds
- * @return duration
+ * seconds <code>double</code> value
+ * @return the <code>Duration</code> based on seconds
*/
public static Duration seconds(final double seconds)
{
@@ -267,10 +286,11 @@
}
/**
- * Gets the duration based on seconds.
+ * Retrieves the <code>Duration</code> based on seconds.
*
* @param seconds
- * @return duration
+ * seconds <code>int</code> value
+ * @return the <code>Duration</code> based on seconds
*/
public static Duration seconds(final int seconds)
{
@@ -278,11 +298,11 @@
}
/**
- * Gets the given long as a duration.
+ * Retrieves the given <code>long</code> as a <code>Duration</code>.
*
* @param time
- * The duration value in milliseconds
- * @return Duration value
+ * the duration <code>long</code> value in milliseconds
+ * @return the <code>Duration</code> value
*/
public static Duration valueOf(final long time)
{
@@ -290,14 +310,15 @@
}
/**
- * Converts the given string to a new duration object. The string can take
- * the form of a floating point number followed by a number of milliseconds,
- * seconds, minutes, hours or days. For example "6 hours" or "3.4 days".
- * Parsing is case insensitive.
+ * Converts the given <code>String</code> to a new <code>Duration</code>
+ * object. The string can take the form of a floating point number followed
+ * by a number of milliseconds, seconds, minutes, hours or days. For example
+ * "6 hours" or "3.4 days". Parsing is case-insensitive.
*
* @param string
- * The string to parse
- * @return The duration value of the given string
+ * a <code>String</code> to parse
+ * @return the <code>Duration</code> value of the given
+ * <code>String</code>
* @throws StringValueConversionException
*/
public static Duration valueOf(final String string) throws StringValueConversionException
@@ -306,16 +327,17 @@
}
/**
- * Converts the given string to a new Duration object. The string can take
- * the form of a floating point number followed by a number of milliseconds,
- * seconds, minutes, hours or days. For example "6 hours" or "3.4 days".
- * Parsing is case insensitive.
+ * Converts the given <code>String</code> to a new <code>Duration</code>
+ * object. The string can take the form of a floating point number followed
+ * by a number of milliseconds, seconds, minutes, hours or days. For example
+ * "6 hours" or "3.4 days". Parsing is case-insensitive.
*
* @param string
- * The string to parse
+ * a <code>String</code> to parse
* @param locale
- * Locale used for parsing
- * @return The duration value of the given string
+ * the <code>Locale</code> used for parsing
+ * @return the <code>Duration</code> value of the given
+ * <code>String</code>
* @throws StringValueConversionException
*/
public static Duration valueOf(final String string, final Locale locale)
@@ -363,7 +385,7 @@
* Private constructor forces use of static factory methods.
*
* @param milliseconds
- * Number of milliseconds in this duration
+ * number of milliseconds in this <code>Duration</code>
*/
protected Duration(final long milliseconds)
{
@@ -371,11 +393,11 @@
}
/**
- * Adds a given duration to this duration.
+ * Adds a given <code>Duration</code> to this <code>Duration</code>.
*
* @param duration
- * The duration to add
- * @return The sum of the durations
+ * the <code>Duration</code> to add
+ * @return the sum of the <code>Duration</code>s
*/
public Duration add(final Duration duration)
{
@@ -383,9 +405,9 @@
}
/**
- * Gets number of days of the current duration.
+ * Retrieves the number of days of the current <code>Duration</code>.
*
- * @return number of days of the current duration
+ * @return number of days of the current <code>Duration</code>
*/
public final double days()
{
@@ -393,9 +415,9 @@
}
/**
- * Gets number of hours of the current duration.
+ * Retrieves the number of hours of the current <code>Duration</code>.
*
- * @return number of hours of the current duration
+ * @return number of hours of the current <code>Duration</code>
*/
public final double hours()
{
@@ -403,9 +425,9 @@
}
/**
- * Gets number of minutes of the current duration.
+ * Retrieves the number of minutes of the current <code>Duration</code>.
*
- * @return number of minutes of the current duration
+ * @return number of minutes of the current <code>Duration</code>
*/
public final double minutes()
{
@@ -413,9 +435,9 @@
}
/**
- * Gets number of seconds of the current duration.
+ * Retrieves the number of seconds of the current <code>Duration</code>.
*
- * @return number of seconds of the current duration
+ * @return number of seconds of the current <code>Duration</code>
*/
public final double seconds()
{
@@ -423,7 +445,7 @@
}
/**
- * Sleep for the current duration.
+ * Sleeps for the current <code>Duration</code>.
*/
public final void sleep()
{
@@ -441,11 +463,11 @@
}
/**
- * Subtract a given duration from this duration.
+ * Subtracts a given <code>Duration</code> from this <code>Duration</code>.
*
* @param that
- * The duration to subtract
- * @return This duration minus that duration
+ * the <code>Duration</code> to subtract
+ * @return this <code>Duration</code> minus that <code>Duration</code>
*/
public Duration subtract(final Duration that)
{
@@ -453,10 +475,11 @@
}
/**
- * Gets the string representation of this duration in days, hours, minutes,
- * seconds or milliseconds, as appropriate. Uses the default locale.
+ * Retrieves the <code>String</code> representation of this
+ * <code>Duration</code> in days, hours, minutes, seconds or milliseconds,
+ * as appropriate. Uses the default <code>Locale</code>.
*
- * @return String representation
+ * @return a <code>String</code> representation
*/
public String toString()
{
@@ -464,12 +487,13 @@
}
/**
- * Gets the string representation of this duration in days, hours, minutes,
- * seconds or milliseconds, as appropriate.
+ * Retrieves the <code>String</code> representation of this
+ * <code>Duration</code> in days, hours, minutes, seconds or milliseconds,
+ * as appropriate.
*
* @param locale
- * the locale
- * @return String representation
+ * a <code>Locale</code>
+ * @return a <code>String</code> representation
*/
public String toString(final Locale locale)
{
@@ -504,16 +528,16 @@
}
/**
- * Converts a value to a unit suffixed value, taking care of English
+ * Converts a value to a unit-suffixed value, taking care of English
* singular/plural suffix.
*
* @param value
- * The value to format
+ * a <code>double</code> value to format
* @param units
- * The units to apply singular or plural suffix to
+ * the units to apply singular or plural suffix to
* @param locale
- * The locale
- * @return A string for the value
+ * the <code>Locale</code>
+ * @return a <code>String</code> representation
*/
private String unitString(final double value, final String units, final Locale locale)
{
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/ITimeFrameSource.java
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/ITimeFrameSource.java?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/ITimeFrameSource.java (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/ITimeFrameSource.java Mon Sep 24 14:34:46 2007
@@ -17,17 +17,21 @@
package org.apache.wicket.util.time;
/**
- * A timeframe source produces time frame values. The value returned by a
- * timeframe source may vary over time.
+ * An <code>ITimeFrameSource</code> produces <code>TimeFrame</code> values.
+ * The value returned by an <code>ITimeFrameSource</code> source may vary over
+ * time.
*
- * @see org.apache.wicket.util.time.TimeFrame
+ * @see TimeFrame
*
* @author Jonathan Locke
+ * @since 1.2.6
*/
public interface ITimeFrameSource
{
/**
- * @return Gets current time frame value
+ * Retrieves the current <code>TimeFrame</code> value.
+ *
+ * @return the current <code>TimeFrame</code> value
*/
TimeFrame getTimeFrame();
}
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Time.java
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Time.java?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Time.java (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/Time.java Mon Sep 24 14:34:46 2007
@@ -22,34 +22,35 @@
import java.util.Date;
/**
- * An immutable Time class that represents a specific point in time. The
- * underlying representation is a long value which holds a number of
- * milliseconds since January 1, 1970, 0:00 GMT. To represent a time duration,
- * such as "6 seconds", use the Duration class. To represent a time period with
- * a start and end time, use the TimeFrame class. To represent a time of day,
- * use the TimeOfDay class.
+ * An immutable <code>Time</code> class that represents a specific point in time. The
+ * underlying representation is a <code>long</code> value which holds a number of
+ * milliseconds since January 1, 1970, 0:00 GMT. To represent a duration of time,
+ * such as "6 seconds", use the <code>Duration</code> class. To represent a time period with
+ * a start and end time, use the <code>TimeFrame</code> class. To represent a time of day,
+ * use the <code>TimeOfDay</code> class.
*
* @author Jonathan Locke
+ * @since 1.2.6
*/
public final class Time extends AbstractTime
{
private static final long serialVersionUID = 1L;
- /** The beginning of UNIX time: January 1, 1970, 0:00 GMT. */
+ /** the beginning of UNIX time: January 1, 1970, 0:00 GMT. */
public static final Time START_OF_UNIX_TIME = milliseconds(0);
- /** Parser in 'yyyy.MM.dd' format. */
+ /** parser in 'yyyy.MM.dd' format. */
private static final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy.MM.dd");
- /** Parser in 'yyyy.MM.dd-h.mma' format. */
+ /** parser in 'yyyy.MM.dd-h.mma' format. */
private static final SimpleDateFormat dateTimeFormat = new SimpleDateFormat("yyyy.MM.dd-h.mma");
/**
- * Gets a Time instance based on the given miliseconds.
+ * Retrieves a <code>Time</code> instance based on the given milliseconds.
*
* @param time
- * The time in milliseconds since START_OF_UNIX_TIME
- * @return The given time
+ * the time value in milliseconds since START_OF_UNIX_TIME
+ * @return the given <code>Time</code>
*/
public static Time milliseconds(final long time)
{
@@ -57,9 +58,9 @@
}
/**
- * Gets a Time instance based on the current time.
+ * Retrieves a <code>Time</code> instance based on the current time.
*
- * @return The current time
+ * @return the current <code>Time</code>
*/
public static Time now()
{
@@ -67,13 +68,14 @@
}
/**
- * Gets time by parsing 'yyyy.MM.dd' format.
+ * Retrieves a <code>Time</code> instance by parsing 'yyyy.MM.dd' format.
*
* @param calendar
- * The calendar to use when parsing date string
+ * the <code>Calendar</code> to use when parsing date
+ * <code>String</code>
* @param string
- * The string
- * @return The time
+ * the <code>String</code> to parse
+ * @return the time
* @throws ParseException
*/
public static Time parseDate(final Calendar calendar, final String string)
@@ -91,11 +93,12 @@
}
/**
- * Gets time by parsing 'yyyy.MM.dd' format using a localtime calendar.
+ * Retrieves a <code>Time</code> instance by parsing 'yyyy.MM.dd' format
+ * using a local time <code>Calendar</code>.
*
* @param string
- * The string
- * @return The time
+ * the <code>String</code> to parse
+ * @return the time
* @throws ParseException
*/
public static Time parseDate(final String string) throws ParseException
@@ -104,13 +107,15 @@
}
/**
- * Gets time by parsing yyyy.MM.dd-h.mma format.
+ * Retrieves a <code>Time</code> instance by parsing 'yyyy.MM.dd-h.mma'
+ * format.
*
* @param calendar
- * The calendar to use when parsing the string
+ * the <code>Calendar</code> to use when parsing the
+ * <code>String</code>
* @param string
- * The string
- * @return An immutable UNIX time value
+ * the <code>String</code> to parse
+ * @return an immutable UNIX <code>Time</code> value
* @throws ParseException
*/
public static Time valueOf(final Calendar calendar, final String string) throws ParseException
@@ -127,14 +132,14 @@
}
/**
- * Gets a Time instance based on the given calendar and {@link TimeOfDay}
- * objects.
+ * Retrieves a <code>Time</code> instance based on the given
+ * <code>Calendar</code> and {@link TimeOfDay} objects.
*
* @param calendar
- * The calendar to use
+ * the <code>Calendar</code> to use
* @param timeOfDay
- * The time of day
- * @return A time value for the time of day today
+ * the time of day
+ * @return a <code>Time</code> value for the time of day today
*/
public static Time valueOf(final Calendar calendar, final TimeOfDay timeOfDay)
{
@@ -152,11 +157,12 @@
}
/**
- * Gets a Time instance based on the given date object.
+ * Retrieves a <code>Time</code> instance based on the given
+ * <code>Date</code> object.
*
* @param date
- * A java.util.Date object
- * @return A corresponding immutable Time object
+ * a <code>java.util.Date</code> object
+ * @return a corresponding immutable <code>Time</code> object
*/
public static Time valueOf(final Date date)
{
@@ -164,11 +170,12 @@
}
/**
- * Gets a Time instance based on the given miliseconds.
+ * Retrieves a <code>Time</code> instance based on the given milliseconds.
*
* @param time
- * The time in milliseconds since START_OF_UNIX_TIME
- * @return A corresponding immutable Time object
+ * the <code>Time</code> value in milliseconds since
+ * START_OF_UNIX_TIME
+ * @return a corresponding immutable <code>Time</code> object
*/
public static Time valueOf(final long time)
{
@@ -176,11 +183,11 @@
}
/**
- * Gets time by parsing yyyy.MM.dd-h.mma format.
+ * Retrieves a <code>Time</code> instance by parsing 'yyyy.MM.dd-h.mma' format.
*
* @param string
- * The string
- * @return The time
+ * the <code>String</code> to parse
+ * @return the <code>Time</code> instance
* @throws ParseException
*/
public static Time valueOf(final String string) throws ParseException
@@ -189,13 +196,14 @@
}
/**
- * Gets time by parsing 'pattern' format.
+ * Retrieves a <code>Time</code> instance by parsing 'pattern' format.
*
* @param string
* input
* @param pattern
- * pattern to use
- * @return Time instance that resulted from parsing the given string
+ * the pattern to parse
+ * @return a <code>Time</code> instance that resulted from parsing the
+ * given <code>String</code>
* @throws ParseException
*/
public static Time valueOf(final String string, final String pattern) throws ParseException
@@ -206,11 +214,12 @@
}
/**
- * Gets a Time instance based on the given {@link TimeOfDay}object.
+ * Retrieves a <code>Time</code> instance based on the given
+ * {@link TimeOfDay} object.
*
* @param timeOfDay
- * The time of day in localtime
- * @return A time value for the time of day today
+ * the time of day in local time
+ * @return a <code>Time</code> value for the time of day today
*/
public static Time valueOf(final TimeOfDay timeOfDay)
{
@@ -221,7 +230,8 @@
* Private constructor forces use of static factory methods.
*
* @param time
- * The time in milliseconds since START_OF_UNIX_TIME
+ * the <code>Time</code> value in milliseconds since
+ * START_OF_UNIX_TIME
*/
private Time(final long time)
{
@@ -229,12 +239,12 @@
}
/**
- * Adds the given duration to this time object, moving the time into the
- * future.
+ * Adds the given <code>Duration</code> to this <code>Time</code>
+ * object, moving the time into the future.
*
* @param duration
- * The duration to add
- * @return This time + duration
+ * the <code>Duration</code> to add
+ * @return this <code>Time</code> + <code>Duration</code>
*/
public Time add(final Duration duration)
{
@@ -242,8 +252,13 @@
}
/**
- * @return Amount of time that has elapsed since this time
- * @throws IllegalStateException Thrown if this time is in the future
+ * Calculates the amount of time that has elapsed since this
+ * <code>Time</code> value.
+ *
+ * @return the amount of time that has elapsed since this <code>Time</code>
+ * value
+ * @throws IllegalStateException
+ * thrown if this <code>Time</code> value is in the future
*/
public Duration elapsedSince()
{
@@ -256,11 +271,13 @@
}
/**
- * Gets the duration from now to this time value. If this time value is in
- * the past, then the Duration returned will be negative. Otherwise, it will
- * be the number of milliseconds from now to this Time.
+ * Retrieves the <code>Duration</code> from now to this <code>Time</code>
+ * value. If this <code>Time</code> value is in the past, then the
+ * <code>Duration</code> returned will be negative. Otherwise, it will be
+ * the number of milliseconds from now to this <code>Time</code>.
*
- * @return The duration from now to this time value
+ * @return the <code>Duration</code> from now to this <code>Time</code>
+ * value
*/
public Duration fromNow()
{
@@ -268,13 +285,14 @@
}
/**
- * Gets the value of a field from the given calendar.
+ * Retrieves the value of a field from the given <code>Calendar</code>.
*
* @param calendar
- * The calendar to use
+ * the <code>Calendar</code> to use
* @param field
- * The calendar field to get
- * @return The field's value for this point in time on the given calendar
+ * the <code>Calendar</code> field to get
+ * @return the field's value for this point in time on the given
+ * <code>Calendar</code>
*/
public int get(final Calendar calendar, final int field)
{
@@ -287,11 +305,11 @@
}
/**
- * Gets the value of a field.
+ * Retrieves the value of a field.
*
* @param field
- * The calendar field to get
- * @return The field's value (in localtime)
+ * the <code>Calendar</code> field to get
+ * @return the field's value (in local time)
*/
public int get(final int field)
{
@@ -299,9 +317,9 @@
}
/**
- * Gets the day of month field of the current calendar.
+ * Retrieves the day of month field of the current <code>Calendar</code>.
*
- * @return the field value
+ * @return the day of month field value
*/
public int getDayOfMonth()
{
@@ -309,11 +327,11 @@
}
/**
- * Gets the day of month field of the given calendar.
+ * Retrieves the day of month field of the given <code>Calendar</code>.
*
* @param calendar
- * the calendar to get the field value from
- * @return the field value
+ * the <code>Calendar</code> to get the field value from
+ * @return the day of month field value
*/
public int getDayOfMonth(final Calendar calendar)
{
@@ -321,9 +339,9 @@
}
/**
- * Gets the hour field of the current calendar.
+ * Retrieves the hour field of the current <code>Calendar</code>.
*
- * @return the field value
+ * @return the hour field value
*/
public int getHour()
{
@@ -331,11 +349,11 @@
}
/**
- * Gets the hour field of the given calendar.
+ * Retrieves the hour field of the given <code>Calendar</code>.
*
* @param calendar
- * the calendar to get the field value from
- * @return the field value
+ * the <code>Calendar</code> to get the field value from
+ * @return the hour field value
*/
public int getHour(final Calendar calendar)
{
@@ -343,9 +361,9 @@
}
/**
- * Gets the minute field of the current calendar.
+ * Retrieves the minute field of the current <code>Calendar</code>.
*
- * @return the field value
+ * @return the minute field value
*/
public int getMinute()
{
@@ -353,11 +371,11 @@
}
/**
- * Gets the minute field of the given calendar.
+ * Retrieves the minute field of the given <code>Calendar</code>.
*
* @param calendar
- * the calendar to get the field value from
- * @return the field value
+ * the <code>Calendar</code> from which to get the field value
+ * @return the minute field value
*/
public int getMinute(final Calendar calendar)
{
@@ -365,9 +383,9 @@
}
/**
- * Gets the month field of the current calendar.
+ * Retrieves the month field of the current <code>Calendar</code>.
*
- * @return the field value
+ * @return the month field value
*/
public int getMonth()
{
@@ -375,11 +393,11 @@
}
/**
- * Gets the month field of the given calendar.
+ * Retrieves the month field of the given <code>Calendar</code>.
*
* @param calendar
- * the calendar to get the field value from
- * @return the field value
+ * the <code>Calendar</code> from which to get the field value
+ * @return the month field value
*/
public int getMonth(final Calendar calendar)
{
@@ -387,9 +405,9 @@
}
/**
- * Gets the second field of the current calendar.
+ * Retrieves the seconds field of the current <code>Calendar</code>.
*
- * @return the field value
+ * @return the seconds field value
*/
public int getSecond()
{
@@ -397,11 +415,11 @@
}
/**
- * Gets the second field of the given calendar.
+ * Retrieves the seconds field of the given <code>Calendar</code>.
*
* @param calendar
- * the calendar to get the field value from
- * @return the field value
+ * the <code>Calendar</code> from which to get the field value
+ * @return the seconds field value
*/
public int getSecond(final Calendar calendar)
{
@@ -409,9 +427,9 @@
}
/**
- * Gets the year field of the current calendar.
+ * Retrieves the year field of the current <code>Calendar</code>.
*
- * @return the field value
+ * @return the year field value
*/
public int getYear()
{
@@ -419,11 +437,11 @@
}
/**
- * Gets the year field of the given calendar.
+ * Retrieves the year field of the given <code>Calendar</code>.
*
* @param calendar
- * the calendar to get the field value from
- * @return the field value
+ * the <code>Calendar</code> from which to get the field value
+ * @return the year field value
*/
public int getYear(final Calendar calendar)
{
@@ -431,12 +449,12 @@
}
/**
- * Adds the given duration to this time object, moving the time into the
- * future.
+ * Adds the given <code>Duration</code> to this <code>Time</code>
+ * object, moving the time into the future.
*
* @param duration
- * The duration to add
- * @return This time - duration
+ * the <code>Duration</code> to add
+ * @return this duration of time
*/
public Time subtract(final Duration duration)
{
@@ -444,11 +462,12 @@
}
/**
- * Subtract time from this and returns the difference as a duration object.
+ * Subtract time from this and returns the difference as a
+ * <code>Duration</code> object.
*
* @param that
- * The time to subtract
- * @return The duration between this and that time
+ * the time to subtract
+ * @return the <code>Duration</code> between this and that time
*/
public Duration subtract(final Time that)
{
@@ -456,10 +475,12 @@
}
/**
- * Gets a Date object for this time object. A new Date object is always
- * returned rather than attempting to cache a date since Date is mutable.
+ * Retrieves a <code>Date</code> object for this <code>Time</code>
+ * object. A new <code>Date</code> object is always returned rather than
+ * attempting to cache a date since <code>Date</code> is mutable.
*
- * @return This immutable time object as a mutable java.util.Date object
+ * @return this immutable <code>Time</code> object as a mutable
+ * <code>java.util.Date</code> object
*/
public Date toDate()
{
@@ -467,10 +488,10 @@
}
/**
- * Converts this time to a date string using the date formatter
- * 'yyyy.MM.dd'.
+ * Converts this <code>Time</code> value to a date <code>String</code>
+ * using the date formatter 'yyyy.MM.dd'.
*
- * @return The date string
+ * @return the date string
*/
public String toDateString()
{
@@ -478,11 +499,12 @@
}
/**
- * Converts this time to a date string using the formatter 'yyyy.MM.dd'.
+ * Converts this <code>Time</code> value to a date <code>String</code>
+ * using the formatter 'yyyy.MM.dd'.
*
* @param calendar
- * The calendar to use in the conversion
- * @return The date string
+ * the <code>Calendar</code> to use in the conversion
+ * @return the date <code>String</code>
*/
public String toDateString(final Calendar calendar)
{
@@ -498,9 +520,10 @@
}
/**
- * Converts this time to a string suitable for use in a filesystem name.
+ * Converts this <code>Time</code> value to a <code>String</code>
+ * suitable for use in a file system name.
*
- * @return This time as a formatted string
+ * @return this <code>Time</code> value as a formatted <code>String</code>
*/
public String toString()
{
@@ -508,13 +531,14 @@
}
/**
- * Converts this time to a string using the given calendar and format.
+ * Converts this <code>Time</code> object to a <code>String</code> using
+ * the given <code>Calendar</code> and format.
*
* @param calendar
- * the calendar to use
+ * the <code>Calendar</code> to use in the conversion
* @param format
* the format to use
- * @return This time as a formatted string
+ * @return this <code>Time</code> value as a formatted <code>String</code>
*/
public String toString(final Calendar calendar, final String format)
{
@@ -524,11 +548,11 @@
}
/**
- * Converts this time to a string using the given format.
+ * Converts this <code>Time</code> value to a <code>String</code> using the given format.
*
* @param format
* the format to use
- * @return This time as a formatted string
+ * @return this <code>Time</code> value as a formatted string
*/
public String toString(final String format)
{
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeFrame.java
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeFrame.java?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeFrame.java (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeFrame.java Mon Sep 24 14:34:46 2007
@@ -20,47 +20,56 @@
* 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.
+ * is the last value in the <code>TimeFrame</code>.
* <p>
- * 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.
+ * <code>TimeFrame</code>s can be constructed by calling the
+ * <code>valueOf</code> static factory methods
+ * <code>valueOf(Time, Time)</code> (yielding a <code>TimeFrame</code>
+ * between two absolute times) and <code>valueOf(Time, Duration)</code>
+ * yielding a <code>TimeFrame</code> starting at an absolute time and having a
+ * given length.
* <p>
- * The start and end of a TimeFrame can be retrieved by calling getStart() and
- * getEnd(). Its duration can be retrieved by calling getDuration().
+ * The start and end of a <code>TimeFrame</code> can be retrieved by calling
+ * <code>getStart</code> and <code>getEnd</code>. Its duration can be
+ * retrieved by calling <code>getDuration</code>.
* <p>
- * 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 <code>contains(Time)</code> method can be called to determine if a
+ * <code>TimeFrame</code> contains a given point in time. The
+ * <code>overlaps(TimeFrame)</code> method can be called to determine if two
+ * <code>TimeFrames</code> overlap.
* <p>
- * 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).
+ * The <code>eachDay(TimeOfDay, TimeOfDay)</code> will return a
+ * <code>TimeFrameSource</code> which generates a <code>TimeFrame</code>
+ * using the two times of day. In other words, if the start is 3pm and the end
+ * is 4pm, the <code>TimeFrameSource</code> 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
{
- /** End of this timeframe */
+ /** end of this <code>TimeFrame</code> */
private final Time end;
- /** Begining of this timeframe */
+ /** beginning of this <code>TimeFrame</code> */
private final Time start;
/**
- * Returns a timeframe source for a start and end time-of-day. 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.
+ * Creates an <code>ITimeFrameSource</code> source for start and end
+ * <code>TimeOfDay</code>s. For example, called with 3pm and 5pm as
+ * parameters, the <code>TimeFrame</code> source returned would produce
+ * <code>TimeFrame</code> objects representing 3pm-5pm on whatever day it
+ * is when the caller calls the <code>TimeFrameSource</code> interface.
*
* @param startTimeOfDay
- * The start time for this time frame each day
+ * the start <code>TimeOfDay</code> for this
+ * <code>TimeFrame</code> each day
* @param endTimeOfDay
- * The end time for this time frame each day
- * @return A timeframe source which will return the specified timeframe each
- * day
+ * the end <code>TimeOfDay</code> for this
+ * <code>TimeFrame</code> each day
+ * @return a <code>TimeFrameSource</code> which will return the specified
+ * <code>TimeFrame</code> each day
*/
public static ITimeFrameSource eachDay(final TimeOfDay startTimeOfDay,
final TimeOfDay endTimeOfDay)
@@ -77,15 +86,17 @@
}
/**
- * Creates a time frame for a start and duration
+ * Creates a <code>TimeFrame</code> for a start <code>Time</code> and
+ * <code>Duration</code>.
*
* @param start
- * The start time
+ * the start <code>Time</code>
* @param duration
- * The duration
- * @return The time frame
+ * the <code>Duration</code>
+ * @return the <code>TimeFrame</code>
* @throws IllegalArgumentException
- * Thrown if start time is before end time
+ * thrown if start <code>Time</code> value is before end
+ * <code>Time</code> value
*/
public static TimeFrame valueOf(final Time start, final Duration duration)
{
@@ -93,15 +104,17 @@
}
/**
- * Creates a time frame for a start and end time
+ * Creates a <code>TimeFrame</code> for given start and end
+ * <code>Time</code>s.
*
* @param start
- * The start time
+ * the start <code>Time</code>
* @param end
- * The end time
- * @return The time frame
+ * the end <code>Time</code>
+ * @return the <code>TimeFrame</code>
* @throws IllegalArgumentException
- * Thrown if start time is before end time
+ * thrown if start <code>Time</code> value is before end
+ * <code>Time</code> value
*/
public static TimeFrame valueOf(final Time start, final Time end)
{
@@ -109,15 +122,15 @@
}
/**
- * Checks consistency of start and end values, ensuring that the end value
- * is less than the start value.
+ * Checks consistency of start and end <code>AbstractTimeValue</code>
+ * values, ensuring that the end value is less than the start value.
*
* @param start
- * Start value
+ * start <code>AbstractTimeValue</code> value
* @param end
- * End value
+ * end <code>AbstractTimeValue</code> value
* @throws IllegalArgumentException
- * Thrown if end is less than start
+ * thrown if end is less than start
*/
private static void check(final AbstractTimeValue start, final AbstractTimeValue end)
{
@@ -130,14 +143,15 @@
}
/**
- * Private constructor to force use of static factory methods
+ * Private constructor to force use of static factory methods.
*
* @param start
- * The start time
+ * the start <code>Time</code>
* @param end
- * The end time
+ * the end <code>Time</code>
* @throws IllegalArgumentException
- * Thrown if start time is before end time
+ * thrown if start <code>Time</code> value is before end
+ * <code>Time</code> value
*/
private TimeFrame(final Time start, final Time end)
{
@@ -147,9 +161,13 @@
}
/**
+ * Determines if this <code>TimeFrame</code> contains a given point in
+ * time.
+ *
* @param time
- * The time to check
- * @return True if this time frame contains the given time
+ * the <code>Time</code> to check
+ * @return <code>true</code> if this <code>TimeFrame</code> contains the
+ * given time
*/
public boolean contains(final Time time)
{
@@ -157,7 +175,9 @@
}
/**
- * @return The duration of this time frame
+ * Retrieves the <code>Duration</code> of this <code>TimeFrame</code>.
+ *
+ * @return the <code>Duration</code> of this <code>TimeFrame</code>
*/
public Duration getDuration()
{
@@ -165,7 +185,9 @@
}
/**
- * @return The end of this time frame
+ * Retrieves the end <code>Time</code> of this <code>TimeFrame</code>.
+ *
+ * @return the end of this <code>TimeFrame</code>
*/
public Time getEnd()
{
@@ -173,7 +195,9 @@
}
/**
- * @return The start of this time frame
+ * Retrieves the start <code>Time</code> of this <code>TimeFrame</code>.
+ *
+ * @return the start of this <code>TimeFrame</code>
*/
public Time getStart()
{
@@ -181,9 +205,10 @@
}
/**
- * Implementation of ITimeFrameSource that simply returns this timeframe
+ * Implementation of <code>ITimeFrameSource</code> that simply returns
+ * this <code>TimeFrame</code>.
*
- * @return Gets this timeframe
+ * @return this <code>TimeFrame</code>
*/
public TimeFrame getTimeFrame()
{
@@ -191,9 +216,12 @@
}
/**
+ * Determines if two <code>TimeFrame</code>s overlap.
+ *
* @param timeframe
- * The timeframe to test
- * @return True if the given timeframe overlaps this one
+ * the <code>TimeFrame</code> to test
+ * @return <code>true</code> if the given <code>TimeFrame</code>
+ * overlaps this one
*/
public boolean overlaps(final TimeFrame timeframe)
{
@@ -202,7 +230,9 @@
}
/**
- * @return String representation of this object
+ * Converts this <code>TimeFrame</code> to a <code>String</code> representation.
+ *
+ * @return a <code>String</code> representation of this object
*/
public String toString()
{
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeMap.java
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeMap.java?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeMap.java (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeMap.java Mon Sep 24 14:34:46 2007
@@ -21,27 +21,37 @@
import java.util.Map;
/**
- * This class maps ITimeFrames to Objects. Since values are stored using
- * ITimeFrameSource implementing objects, the value returned by the source may
- * vary over time. For example, one implementation of ITimeFrameSource might
- * return the start and end time of lunch on any given day.
+ * This class maps <code>ITimeFrame</code>s to <code>Object</code>s. Since
+ * values are stored using <code>ITimeFrameSource</code> implementing objects,
+ * the value returned by the source may vary over time. For example, one
+ * implementation of <code>ITimeFrameSource</code> might return the start and
+ * end time of lunch on any given day.
* <p>
- * To associate an object with a dynamic TimeFrame (via ITimeFrameSource), call
- * put(ITimeFrameSource, Object). You can later retrieve the first object for a
- * point in time with get(Time). The method get() is provided for convenience
- * and is equivalent to get(Time.now()).
+ * To associate an object with a dynamic <code>TimeFrame</code> (via
+ * <code>ITimeFrameSource</code>), call
+ * <code>put(ITimeFrameSource, Object)</code>. You can later retrieve the
+ * first object for a point in time with <code>get(Time)</code>. The
+ * <code>get</code> method is provided for convenience and is equivalent to
+ * <code>get(Time.now())</code>.
* <p>
- * This class is not threadsafe.
+ * This class is not thread-safe.
*
* @author Jonathan Locke
+ * @since 1.2.6
*/
public final class TimeMap
{
- /** Map from ITimeFrameSource implementing objects to Object values. */
+ /**
+ * <code>Map</code> from <code>ITimeFrameSource</code> implementing
+ * objects to <code>Object</code> values.
+ */
private final Map sources = new HashMap();
/**
- * @return Object for the current time
+ * Retrieves an <code>Object</code> for the current <code>Time</code>
+ * value.
+ *
+ * @return <code>Object</code> for the current <code>Time</code> value
*/
public Object get()
{
@@ -49,9 +59,13 @@
}
/**
+ * Retrieves an <code>Object</code> for the given <code>Time</code>
+ * value.
+ *
* @param time
- * The time
- * @return Gets an Object for the given time value or null if none exists
+ * the <code>Time</code> value
+ * @return gets an <code>Object</code> for the given <code>Time</code>
+ * value or <code>null</code> if none exists
*/
public Object get(final Time time)
{
@@ -68,13 +82,14 @@
}
/**
- * Associates an object with a dynamic time frame
+ * Associates an <code>Object</code> with a dynamic <code>TimeFrame</code>.
*
* @param source
- * A source that can produce a timeframe to compare a time value
- * with
+ * a source that can produce a <code>TimeFrame</code> with
+ * which to compare a <code>Time</code> value
* @param o
- * The object to be returned for the given dynamic timeframe
+ * the <code>Object</code> to be returned for the given dynamic
+ * <code>TimeFrame</code>
*/
public void put(final ITimeFrameSource source, final Object o)
{
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeOfDay.java
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeOfDay.java?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeOfDay.java (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/TimeOfDay.java Mon Sep 24 14:34:46 2007
@@ -28,32 +28,42 @@
* <p>
* Values can be constructed using various factory methods:
* <ul>
- * <li>valueOf(long) where long is milliseconds since midnight
- * <li>valueOf(String) where the string is in h.mma format
- * <li>valueOf(Calendar, String) where the string is in h.mma format
- * <li>valueOf(Duration) where duration is time since midnight
- * <li>valueOf(Time) where time is some point in time today
- * <li>valueOf(Calendar, Time) where time is some point in time today
- * <li>militaryTime(int hour, int minute, int second) for 24 hour time
- * <li>time(int hour, int minute, Meridian) where Meridian is AM or PM
- * <li>time(int hour, int minute, int second, Meridian) where Meridian is AM or
- * PM
- * <li>now() to construct the current time of day
- * <li>now(Calendar) to construct the current time of day using a given
- * calendar
+ * <li><code>valueOf(long)</code> where <code>long</code> is milliseconds
+ * since midnight
+ * <li><code>valueOf(String)</code> where the <code>String</code> is in
+ * 'h.mma' format
+ * <li><code>valueOf(Calendar, String)</code> where the <code>String</code>
+ * is in 'h.mma' format
+ * <li><code>valueOf(Duration)</code> where <code>Duration</code> is time
+ * since midnight
+ * <li><code>valueOf(Time)</code> where <code>Time</code> is some point in
+ * time today
+ * <li><code>valueOf(Calendar, Time)</code> where <code>Time</code> is some
+ * point in time today
+ * <li><code>militaryTime(int hour, int minute, int second)</code> for
+ * 24-hour time
+ * <li><code>time(int hour, int minute, Meridian)</code> where
+ * <code>Meridian</code> is AM or PM
+ * <li><code>time(int hour, int minute, int second, Meridian)</code> where
+ * <code>Meridian</code> is AM or PM
+ * <li><code>now()</code> to construct the current time of day
+ * <li><code>now(Calendar)</code> to construct the current time of day using
+ * a given <code>Calendar</code>
* </ul>
* <p>
* 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.
+ * greater than 24 hours worth of milliseconds), an
+ * <code>IllegalArgumentException</code> will be thrown.
* <p>
* Military hours, minutes and seconds of the time of day can be retrieved by
- * calling hour(), minute() and second().
+ * calling the <code>hour</code>, <code>minute</code>, and
+ * <code>second</code> methods.
* <p>
- * The next occurrence of a given time of day can be retrieved by calling next()
- * or next(Calendar).
+ * The next occurrence of a given <code>TimeOfDay</code> can
+ * be retrieved by calling <code>next()</code> or <code>next(Calendar)</code>.
*
* @author Jonathan Locke
+ * @since 1.2.6
*/
public final class TimeOfDay extends AbstractTime
{
@@ -77,7 +87,7 @@
private static final long serialVersionUID = 1L;
/**
- * Construct.
+ * Constructor.
*
* @param name
* the meridian name (value)
@@ -89,15 +99,15 @@
}
/**
- * Gets a time of day value on a 24 hour clock.
+ * Retrieves a <code>TimeOfDay</code> value on a 24-hour clock.
*
* @param hour
- * The hour (0-23)
+ * the hour (0-23)
* @param minute
- * The minute (0-59)
+ * the minute (0-59)
* @param second
- * The second (0-59)
- * @return The time of day
+ * the second (0-59)
+ * @return the time of day
*/
public static TimeOfDay militaryTime(final int hour, final int minute, final int second)
{
@@ -121,9 +131,9 @@
}
/**
- * Gets the time of day it is now.
+ * Retrieves the <code>TimeOfDay</code> representing 'now'.
*
- * @return The time of day it is now
+ * @return the time of day it is now
*/
public static TimeOfDay now()
{
@@ -131,11 +141,12 @@
}
/**
- * Gets the time of day it is now on the given calendar.
+ * Retrieves the <code>TimeOfDay</code> representing 'now' on the given
+ * <code>Calendar</code>.
*
* @param calendar
- * The calendar to use
- * @return The time of day it is now on the given calendar
+ * the <code>Calendar</code> to use
+ * @return the time of day it is now on the given <code>Calendar</code>
*/
public static TimeOfDay now(final Calendar calendar)
{
@@ -143,17 +154,17 @@
}
/**
- * Gets a time of day on a 12 hour clock.
+ * Retrieves a <code>TimeOfDay</code> on a 12-hour clock.
*
* @param hour
- * The hour (1-12)
+ * the hour (1-12)
* @param minute
- * The minute (0-59)
+ * the minute (0-59)
* @param second
- * The second (0-59)
+ * the second (0-59)
* @param meridian
- * AM/PM
- * @return The time value
+ * AM or PM
+ * @return the <code>TimeOfDay</code> value
*/
public static TimeOfDay time(final int hour, final int minute, final int second,
final Meridian meridian)
@@ -183,15 +194,15 @@
}
/**
- * Gets a time of day on a 12 hour clock.
+ * Retrieves a <code>TimeOfDay</code> on a 12-hour clock.
*
* @param hour
- * The hour (1-12)
+ * the hour (1-12)
* @param minute
- * The minute (0-59)
+ * the minute (0-59)
* @param meridian
- * AM/PM
- * @return The time value
+ * AM of PM
+ * @return the <code>TimeOfDay</code> value
*/
public static TimeOfDay time(final int hour, final int minute, final Meridian meridian)
{
@@ -199,13 +210,15 @@
}
/**
- * Converts to TimeOfDay instance.
+ * Converts a time <code>String</code> and <code>Calendar</code> to a
+ * <code>TimeOfDay</code> instance.
*
* @param calendar
- * The calendar to use when parsing time string
+ * the <code>Calendar</code> to use when parsing time
+ * <code>String</code>
* @param time
- * A string in h.mma format
- * @return The time of day on the given calendar
+ * a <code>String</code> in 'h.mma' format
+ * @return the <code>TimeOfDay</code> on the given <code>Calendar</code>
* @throws ParseException
*/
public static TimeOfDay valueOf(final Calendar calendar, final String time)
@@ -222,13 +235,14 @@
}
/**
- * Converts to TimeOfDay instance.
+ * Converts a <code>Time</code> instance and <code>Calendar</code> to a
+ * <code>TimeOfDay</code> instance.
*
* @param calendar
- * The calendar to use when converting time value
+ * the <code>Calendar</code> to use
* @param time
- * The time to convert to a time of day
- * @return The time of day for this time
+ * a <code>Time</code> instance
+ * @return the <code>TimeOfDay</code> on the given <code>Calendar</code>
*/
public static TimeOfDay valueOf(final Calendar calendar, final Time time)
{
@@ -237,11 +251,12 @@
}
/**
- * Converts to TimeOfDay instance.
+ * Converts a <code>Duration</code> instance to a <code>TimeOfDay</code>
+ * instance.
*
* @param duration
- * The duration
- * @return The time of day for the duration since midnight
+ * the <code>Duration</code> to use
+ * @return the <code>TimeOfDay</code> of the given <code>Duration</code>
*/
public static TimeOfDay valueOf(final Duration duration)
{
@@ -249,11 +264,12 @@
}
/**
- * Converts to TimeOfDay instance.
+ * Converts a <code>long</code> value to a <code>TimeOfDay</code>
+ * instance.
*
* @param time
- * The time in milliseconds today
- * @return The time of day
+ * the time in milliseconds today
+ * @return the <code>TimeOfDay</code>
*/
public static TimeOfDay valueOf(final long time)
{
@@ -261,11 +277,12 @@
}
/**
- * Converts to TimeOfDay instance.
+ * Converts a <code>String</code> value to a <code>TimeOfDay</code>
+ * instance.
*
* @param time
- * A string in h.mma format
- * @return The time of day on the given calendar
+ * a <code>String</code> in 'h.mma' format
+ * @return the <code>TimeOfDay</code>
* @throws ParseException
*/
public static TimeOfDay valueOf(final String time) throws ParseException
@@ -274,11 +291,12 @@
}
/**
- * Converts to TimeOfDay instance.
+ * Converts a <code>String</code> value to a <code>TimeOfDay</code>
+ * instance.
*
* @param time
- * Time to convert to time of day
- * @return The time of day in the current timezone
+ * a <code>Time</code> to convert to <code>TimeOfDay</code>
+ * @return the <code>TimeOfDay</code> in the current time zone
*/
public static TimeOfDay valueOf(final Time time)
{
@@ -289,7 +307,7 @@
* Private utility constructor forces use of static factory methods.
*
* @param time
- * Time today in milliseconds
+ * the time today in milliseconds
*/
private TimeOfDay(final long time)
{
@@ -303,9 +321,9 @@
}
/**
- * Gets the hour of the day.
+ * Retrieves the hour of the day.
*
- * @return The hour of the day (0-23)
+ * @return the hour (0-23) of this <code>TimeOfDay</code>
*/
public int hour()
{
@@ -313,9 +331,9 @@
}
/**
- * Gets the minute.
+ * Retrieves the minute.
*
- * @return The minute (0-59)
+ * @return the minute (0-59) of this <code>TimeOfDay</code>
*/
public int minute()
{
@@ -323,9 +341,11 @@
}
/**
- * Gets the next occurrence of this time of day in localtime.
+ * Retrieves the next occurrence of this <code>TimeOfDay</code> in local
+ * time.
*
- * @return The next occurrence of this time of day in localtime
+ * @return the next occurrence of this <code>TimeOfDay</code> in local
+ * time
*/
public Time next()
{
@@ -333,11 +353,13 @@
}
/**
- * Gets the next occurence of this time of day on the given calendar.
+ * Retrieves the next occurrence of this <code>TimeOfDay</code> on the
+ * given <code>Calendar</code>.
*
* @param calendar
- * The calendar to use
- * @return The next occurrence of this time of day on the given calendar
+ * the <code>Calendar</code> to use
+ * @return the next occurrence of this <code>TimeOfDay</code> on the given
+ * <code>Calendar</code>
*/
public Time next(final Calendar calendar)
{
@@ -358,9 +380,9 @@
}
/**
- * Gets the second.
+ * Retrieves the second.
*
- * @return The second (0-59)
+ * @return the second (0-59)
*/
public int second()
{
@@ -377,10 +399,10 @@
}
/**
- * Gets miliseconds as hours.
+ * Retrieves milliseconds as hours.
*
* @param milliseconds
- * miliseconds to convert
+ * milliseconds to convert
* @return converted input
*/
private int toHours(final long milliseconds)
@@ -389,10 +411,10 @@
}
/**
- * Gets miliseconds as minutes.
+ * Retrieves milliseconds as minutes.
*
* @param milliseconds
- * miliseconds to convert
+ * milliseconds to convert
* @return converted input
*/
private int toMinutes(final long milliseconds)
@@ -401,10 +423,10 @@
}
/**
- * Gets miliseconds as seconds.
+ * Retrieves milliseconds as seconds.
*
* @param milliseconds
- * miliseconds to convert
+ * milliseconds to convert
* @return converted input
*/
private int toSeconds(final long milliseconds)
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/package.html
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/package.html?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/package.html (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/time/package.html Mon Sep 24 14:34:46 2007
@@ -16,12 +16,14 @@
-->
<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 3.2 Final//NL">
<html>
-<head>
-<title>wicket.util.time package</title>
-</head>
-<body>
-<p>
-Utilities for working with time(s).
-</p>
-</body>
+ <head>
+ <title>
+ org.apache.wicket.util.time package
+ </title>
+ </head>
+ <body>
+ <p>
+ Utilities for working with <code>Time</code>(s).
+ </p>
+ </body>
</html>
Modified: wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/upload/package.html
URL: http://svn.apache.org/viewvc/wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/upload/package.html?rev=578985&r1=578984&r2=578985&view=diff
==============================================================================
--- wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/upload/package.html (original)
+++ wicket/trunk/jdk-1.4/wicket/src/main/java/org/apache/wicket/util/upload/package.html Mon Sep 24 14:34:46 2007
@@ -16,13 +16,15 @@
-->
<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 3.2 Final//NL">
<html>
-<head>
-<title>wicket.util.upload package</title>
-</head>
-<body>
-<p>
-Protocol independent upload utilities. Copied from the
-Apache Jakarta Commons FileUpload project (1.1-dev, HEAD at 21st of august 2005).
-</p>
-</body>
+ <head>
+ <title>
+ org.apache.wicket.util.upload package
+ </title>
+ </head>
+ <body>
+ <p>
+ Protocol independent upload utilities. Copied from the
+ Apache Jakarta Commons FileUpload project (1.1-dev, HEAD at 21st of august 2005).
+ </p>
+ </body>
</html>