org.ceryle.util.timeline
Class TimeLine

java.lang.Object
  org.ceryle.util.timeline.TimeLine

All Implemented Interfaces:

Constants

public class TimeLine
extends Object
implements Constants

A utility for the processing of time strings and generation of timelines. This class generates a time line from a Start and End time, or a Start time and Duration. This timeline is then used to generate the time extents and populate an org.ceryle.util.timeline.TimeScale for application to an extension of a TouchGraph Node, a topic node or TNode (see TNode). This may also be used as a utility class for processing date and time information.

Includes validation (parsing) methods for both date-time and duration strings, trying each of the four Date parsing formats successively until one works:

• DateFormat.SHORT: "2/16/2002"
• DateFormat.MEDIUM: "Feb 16, 2002"
• DateFormat.LONG: "February 16, 2002"
• DateFormat.FULL: "Saturday, February 16, 2002"

Durations are input as a comma-delimited list of values, each a number followed by a calendar field string. TimeLine's field strings vary from that of java.util.Calendar with the addition of three new fields: centuries, decades, and weeks. While these can be input as part of a duration, note that weeks are not included on output scales. Entry order is not significant, and the parser is case insensitive (though this may not hold true on non-English localizations due to case folding rules).

Acceptable singular and plural field strings (which can be localized to other languages, see the Messages class), are shown below, each followed by its enumerated Clock constant:

• "century", "centuries", Clock.FIELD_CENTURY
• "decade", "decades", Clock.FIELD_DECADE
• "year", "years", Clock.FIELD_YEAR
• "month", "months", Clock.FIELD_MONTH
• "week", "weeks", Clock.FIELD_WEEK
• "day", "days", Clock.FIELD_DAY
• "hour", "hours", Clock.FIELD_HOUR
• "minute", "minutes", Clock.FIELD_MINUTE
• "second", and "seconds" Clock.FIELD_SECOND.

Since:

JDK1.3

Version:

$Id: TimeLine.java,v 3.4 2007-06-15 12:10:05 altheim Exp $

Author:

Murray Altheim

See Also:

TimeExtentDialog, TimeExtentPanel

Field Summary

protected String[]	FIELD_NAME Date field names (in singular and plural, 9 elements between) as Strings.
static long[]	SEC_PER_FIELD Constants for calculating elapsed times.
static Date	TIME_NOT_SET A Date constant indicating a time not yet initialized/set (uses TIME_NOT_SET_MS).
static long	TIME_NOT_SET_MS A long constant indicating a time not yet initialized/set (the default is -7, indicating 7 milliseconds before midnight of 1 Jan 1970).

Fields inherited from interface org.ceryle.util.Constants

Amp, AMP, Apos, APOS, APP_NAME, APP_VERSION_NAME, APP_VERSION_NUMBER, AT, BANG, BAR, BIT_dev, BIT_http, BIT_ignoreCom, BIT_merge, BIT_none, BIT_noPreload, BIT_simple, BIT_ui, BIT_unused1, BIT_unused2, BIT_unused3, BIT_validating, BIT_verbose, BIT_xcatalog, BIT_xlink, BIT_xmlnsAware, BIT_xsd, BROKB, BSlash, BSLASH, CERYLE_CREDITS_FILE, CERYLE_DATA_DIR, CERYLE_HIST_FILE, CERYLE_LICENSE_FILE, CERYLE_PREF_FILE, CERYLE_PROP, CERYLE_PROP_BASE, CERYLE_PROP_FILE, CERYLE_RSRC_DIR, CERYLE_THANKS_FILE, CFLEX, Colon, COLON, Comma, COMMA, CR, CRet, Dash, DASH, DEFAULT_DIRECTORY, DEVELOPER, DOLR, Dot, DOT, EIGHT, Ellip, EOF, EqQuot, EQUAL, Equals, False, FALSE, FileProt, Filesep, FileURL, Five, FIVE, FONTSIZES, Four, FOUR, FSchar, GCOL_PROP, GRAPH_PROP, GRAVE, GT, Hash, HASH, HOME_DIRECTORY, HOME_DIRECTORY_PATH, HOME_DIRECTORY_URL, HTML, HttpProt, HttpURL, INDENT, INDENT_0, INDENT_1, INDENT_10, INDENT_2, INDENT_3, INDENT_4, INDENT_5, INDENT_6, INDENT_7, INDENT_8, INDENT_9, INIT, LCURL, LCurly, LF, LFS, Localhost, LPAR, LParen, LS, LSBrkt, LSBrkt2, LSQB, LT, MT, NBSP, NEL, NINE, NL, NL20x, NLchar, No, Null, NULL, NULL_STATE, NumParams, One, ONE, Pathsep, Percent, PERO, PLUS, Prcnt, PS, QMark, QMARK, Quot, QUOT, RCURL, RCurly, RESOURCE_BUNDLE, RPAR, RParen, RSBrkt, RSBrkt2, RSQB, Semi, SEMI, SEVEN, SIX, Slash, SLASH, SP, SPACE, Stago, Star, STAR, Tab, TAB, Tee, Three, THREE, Tilde, TILDE, TM_PROP, True, TRUE, Two, TWO, Under, UNDER, URI, URL, VBar, WIKI_PROP, XNodePfx, XNodeURL, XtmExt, Yes, Zero, ZERO

Constructor Summary

TimeLine(Services services)
Constructor with a reference to the application Services services.

Method Summary

static GregorianCalendar	addDuration(GregorianCalendar gc, int[] dur) Add the provided duration array to the GregorianCalendar gc, returning the modified calendar.
void	calculateResolution() Display the field counts between the start and end extents of this TimeLine.
void	displayElapsed() Display the elapsed time between the start and end extents of this TimeLine.
TimeScale	generateScale(long count, int minorScaleIndex) Generate a scale, provided count as the number of minor ticks, minorScaleIndex is field index of the minor tick field, and variance is how far from perfect.
String	getDateAsString(Date date) Returns the provided Date date as a String, formatted to DateFormat.MEDIUM, the String "not set" if null.
int[]	getDuration() Returns the duration of this TimeLine as an array of field values representing a duration.
String	getDurationAsString(int[] duration, boolean includeTime) Return the provided array of long integers representing a duration, as a String.
int[]	getDurationFromDates(Date startDate, Date endDate) Return the elapsed time as an int[] array between the start and end extents of this TimeLine.
Date	getEnd() Returns the end of this TimeLine as a Date, null if this has not been set.
GregorianCalendar	getEndAsGregorianCalendar() Returns the end of this TimeLine as a GregorianCalendar, null if this has not been set.
long	getEndInMillis() Returns the end of this TimeLine as a long, the constant TIME_NOT_SET_MS if this has not been set.
Date	getStart() Returns the start of this TimeLine as a Date, null if this has not been set.
GregorianCalendar	getStartAsGregorianCalendar() Returns the start of this TimeLine as GregorianCalendar, null if this has not been set.
long	getStartInMillis() Returns the start of this TimeLine as a long, the constant TIME_NOT_SET_MS if this has not been set.
TimeScale	getTimeScale() Returns the TimeScale established by this TimeLine, null if not set.
GregorianCalendar	parseDateTime(String dt) Parses the provided String dt to a GregorianCalendar date, returning the result.
long[]	parseDuration(String duration) Parses the String duration representing a time duration, whose format is a comma-separated list of values, eg., "1 century, 6 decades, 3 years, 4 months, 2 weeks, 7 days, 4 hours, 23 minutes, 56 seconds", returning an array of long ints.
void	setDuration(int[] duration) Sets the duration of this TimeLine provided with an array of int values representing a duration.
void	setEnd(GregorianCalendar end) Sets the end of this TimeLine provided with an ending date as the GregorianCalendar end.
void	setPixelsPerTick(int pixelsPerTick) Sets the minimum pixels/tick, used to establish scale resolution.
void	setStart(GregorianCalendar start) Sets the start of this TimeLine provided with a starting date as a GregorianCalendar start.
GregorianCalendar	setStartAndDuration(GregorianCalendar start, int[] duration) Sets the dateTime extent of this TimeLine provided with starting date as a GregorianCalendar start and a String duration representing the duration (for the format of this String, see TimeLine).
int[]	setStartAndEnd(GregorianCalendar start, GregorianCalendar end) Sets the time extent of this TimeLine provided with starting and ending times as the GregorianCalendars start and end.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FIELD_NAME

protected String[] FIELD_NAME

Date field names (in singular and plural, 9 elements between) as Strings.

TIME_NOT_SET

public static final Date TIME_NOT_SET

A Date constant indicating a time not yet initialized/set (uses TIME_NOT_SET_MS).

TIME_NOT_SET_MS

public static final long TIME_NOT_SET_MS

A long constant indicating a time not yet initialized/set (the default is -7, indicating 7 milliseconds before midnight of 1 Jan 1970). In the unlikely event that the application needs to store this particular date, this constant may need to be altered.

SEC_PER_FIELD

public static final long[] SEC_PER_FIELD

Constants for calculating elapsed times.

Constructor Detail

TimeLine

public TimeLine(Services services)

Constructor with a reference to the application Services services.

Method Detail

setPixelsPerTick

public void setPixelsPerTick(int pixelsPerTick)

Sets the minimum pixels/tick, used to establish scale resolution. This serves as a recommendation only. Acceptable values are between 2 and 100.

getTimeScale

public TimeScale getTimeScale()

Returns the TimeScale established by this TimeLine, null if not set.

setStart

public void setStart(GregorianCalendar start)

Sets the start of this TimeLine provided with a starting date as a GregorianCalendar start.

getStart

public Date getStart()

Returns the start of this TimeLine as a Date, null if this has not been set.

getStartInMillis

public long getStartInMillis()

Returns the start of this TimeLine as a long, the constant TIME_NOT_SET_MS if this has not been set.

getStartAsGregorianCalendar

public GregorianCalendar getStartAsGregorianCalendar()

Returns the start of this TimeLine as GregorianCalendar, null if this has not been set.

setDuration

public void setDuration(int[] duration)

Sets the duration of this TimeLine provided with an array of int values representing a duration.

getDuration

public int[] getDuration()

Returns the duration of this TimeLine as an array of field values representing a duration.

setEnd

public void setEnd(GregorianCalendar end)

Sets the end of this TimeLine provided with an ending date as the GregorianCalendar end.

getEnd

public Date getEnd()

Returns the end of this TimeLine as a Date, null if this has not been set.

getEndInMillis

public long getEndInMillis()

Returns the end of this TimeLine as a long, the constant TIME_NOT_SET_MS if this has not been set.

getEndAsGregorianCalendar

public GregorianCalendar getEndAsGregorianCalendar()

Returns the end of this TimeLine as a GregorianCalendar, null if this has not been set.

setStartAndEnd

public int[] setStartAndEnd(GregorianCalendar start,
                            GregorianCalendar end)

Sets the time extent of this TimeLine provided with starting and ending times as the GregorianCalendars start and end. If the end date is prior to the start date, reverses their values (rather than flagging an error). The difference between calling setStart() and setEnd() separately is that this method will calculate the Duration, returning its value as a int[] array.

setStartAndDuration

public GregorianCalendar setStartAndDuration(GregorianCalendar start,
                                             int[] duration)

Sets the dateTime extent of this TimeLine provided with starting date as a GregorianCalendar start and a String duration representing the duration (for the format of this String, see TimeLine). The difference between calling setStart() and setDuration() separately is that this method will calculate the End date, returning its value as a GregorianCalendar.

addDuration

public static GregorianCalendar addDuration(GregorianCalendar gc,
                                            int[] dur)

Add the provided duration array to the GregorianCalendar gc, returning the modified calendar.

parseDateTime

public GregorianCalendar parseDateTime(String dt)

Parses the provided String dt to a GregorianCalendar date, returning the result. This tries each date format in succession. If unable to parse as a date, this is noted in a status error, returning null.

parseDuration

public long[] parseDuration(String duration)
                     throws ProcessException

Parses the String duration representing a time duration, whose format is a comma-separated list of values, eg., "1 century, 6 decades, 3 years, 4 months, 2 weeks, 7 days, 4 hours, 23 minutes, 56 seconds", returning an array of long ints. Because a century is 3,151,440,000 seconds, ints aren't large enough (Integer.MAX_VALUE is a bit over 2 million).

The calendar field names are internationalized in both singular and plural (via the Messages class), and are parsed case insensitively (insofar as string matching following lowercase wrapping functions in each localization). Field names are padded with spaces so that string matches won't accidentally match a singular where a plural is intended (eg., the algorithm searches for " year " and " years ", not "year" and "years").

Note that any portion of the duration can be negative, though this might be rather confusing if not managed correctly (eg., a duration of "6 years, -23 weeks, -4 days" is difficult to understand even when correctly added to the start date). Also, if a field redundancy occurs (eg., "2 weeks, 4 weeks"), only the last value is used.

If a parsing error occurs, generates an error message to the MessageHandler and returns null.

Parameters:

duration - a comma-delimited String of duration values

Returns:

an array of long ints representing the duration

Throws:

ProcessException

getDateAsString

public String getDateAsString(Date date)

Returns the provided Date date as a String, formatted to DateFormat.MEDIUM, the String "not set" if null.

getDurationAsString

public String getDurationAsString(int[] duration,
                                  boolean includeTime)

Return the provided array of long integers representing a duration, as a String. If the boolean includeTime is true, includes time fields, otherwise only date fields are returned.

getDurationFromDates

public int[] getDurationFromDates(Date startDate,
                                  Date endDate)

Return the elapsed time as an int[] array between the start and end extents of this TimeLine.

calculateResolution

public void calculateResolution()
                         throws ProcessException

Display the field counts between the start and end extents of this TimeLine.

Throws:

ProcessException

generateScale

public TimeScale generateScale(long count,
                               int minorScaleIndex)
                        throws ProcessException

Generate a scale, provided count as the number of minor ticks, minorScaleIndex is field index of the minor tick field, and variance is how far from perfect.

Throws:

ProcessException

displayElapsed

public void displayElapsed()

Display the elapsed time between the start and end extents of this TimeLine.