de.schlichtherle.util.zip
Class DateTimeConverter

java.lang.Object
  de.schlichtherle.util.zip.DateTimeConverter

public abstract class DateTimeConverter
extends Object

Converts Java time values to DOS date/time values and vice versa. This class has been introduced in order to enhance interoperability between different flavours of the ZIP file format specification when converting date/time from the serialized DOS format in a ZIP file to the local system time, which is represented by a UNIX-like encoding by the Java API.

This class is thread-safe.

Since:

TrueZIP 6.7

Version:

$Id: DateTimeConverter.java 5e709f50671d 2010/11/05 11:52:07 christian $

Author:

Christian Schlichtherle

Field Summary

private ThreadLocal	calendar
static DateTimeConverter	JAR This instance applies the schedule for Daylight Saving Time (DST), i.e. all time conversions will apply DST where appropriate to a particular date.
(package private) static long	MIN_DOS_TIME Smallest supported DOS date/time value in a ZIP file, which is January 1st, 1980 AD 00:00:00 local time.
static DateTimeConverter	ZIP This instance ignores the schedule for Daylight Saving Time (DST), i.e. all time conversions will use the same raw offset and current DST savings, regardless of whether DST savings should be applied to a particular date or not.

Constructor Summary

DateTimeConverter()

Method Summary

protected abstract TimeZone	createTimeZone() Returns a new timezone to use for date/time conversion.
private Calendar	getCalendar() Returns a thread local Calendar instance for the date/time conversion which has its timezone set to the return value of createTimeZone().
protected abstract boolean	roundUp(long jTime) Returns whether a Java time should be rounded up or down to the next two second interval when converting it to a DOS date/time.
(package private) long	toDosTime(long jTime) Converts a Java time value to a DOS date/time value.
(package private) long	toJavaTime(long dTime) Converts a DOS date/time value to a Java time value.

Methods inherited from class java.lang.Object

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

Field Detail

MIN_DOS_TIME

static final long MIN_DOS_TIME

Smallest supported DOS date/time value in a ZIP file, which is January 1^st, 1980 AD 00:00:00 local time.

See Also:

Constant Field Values

JAR

public static final DateTimeConverter JAR

This instance applies the schedule for Daylight Saving Time (DST), i.e. all time conversions will apply DST where appropriate to a particular date.

This behaviour provides best interoperability with:

• Java SE: jar utility and java.util.zip package
• Info-ZIP: unzip

ZIP

public static final DateTimeConverter ZIP

This instance ignores the schedule for Daylight Saving Time (DST), i.e. all time conversions will use the same raw offset and current DST savings, regardless of whether DST savings should be applied to a particular date or not.

This behavior provides best interoperability with:

• Windows Vista Explorer (as of June 30^th, 2009)
• WinZip 12.0
• 7-Zip 4.65

calendar

private final ThreadLocal calendar

See Also:

getCalendar()

Constructor Detail

DateTimeConverter

public DateTimeConverter()

Method Detail

toDosTime

final long toDosTime(long jTime)

Converts a Java time value to a DOS date/time value. The returned value is rounded up or down to even seconds, depending on roundUp(long). If the Java time value is earlier than January 1^st, 1980 AD 00:00:00 local time, then this value is returned instead.

This method uses a Calendar for the date/time conversion which has its timezone set to the return value of createTimeZone().

Parameters:

jTime - The number of milliseconds since midnight, January 1st, 1970 AD UTC (called the epoch alias Java time).

Returns:

A DOS date/time value reflecting the local time zone and rounded down to even seconds which is minimum January 1^st, 1980 AD 00:00:00.

Throws:

RuntimeException - If jTime is negative or later than 2107 AD.

See Also:

toJavaTime(long), createTimeZone()

toJavaTime

final long toJavaTime(long dTime)

Converts a DOS date/time value to a Java time value. DOS date/time values are encoded using 32 bit integers. However, not all 32 bit integers make a valid DOS date/time value. If an illegal 32 bit integer is provided, the behaviour of this method depends on the assertion status:

This method uses a Calendar for the date/time conversion which has its timezone set to the return value of createTimeZone().

If assertions are enabled, Calendard.setLenient(false) is called in order to throw a RuntimeException when parsing illegal DOS date/time field values. This can be used in order to detect bogus ZIP archive files created by third party tools.

If assertions are disabled however, Calendard.setLenient(true) is called in order to adjust illegal DOS date/time field values by overflowing them into their adjacent fields. This can be used in order to read bogus ZIP archive files created by third party tools. However, the returned Java time may differ from its intended value at the time of the creation of the ZIP archive file and when converting it back again, the resulting DOS date/time will not be the same as dTime. Hence, interoperability is negatively affected in this case.

Parameters:

dTime - The DOS date/time value.

Returns:

The number of milliseconds since midnight, January 1st, 1970 AD UTC (called the epoch alias Java time).

Throws:

RuntimeException - If dTime is earlier than 1980 AD or greater than 0xffffffffL or holds an illegal DOS date/time field combination and assertions are enabled.

See Also:

toDosTime(long), createTimeZone()

getCalendar

private Calendar getCalendar()

Returns a thread local Calendar instance for the date/time conversion which has its timezone set to the return value of createTimeZone().

Returns:

A Calendar instance.

createTimeZone

protected abstract TimeZone createTimeZone()

Returns a new timezone to use for date/time conversion. All returned instances must have the same rules.

Returns:

A new timezone for date/time conversion - never null.

roundUp

protected abstract boolean roundUp(long jTime)

Returns whether a Java time should be rounded up or down to the next two second interval when converting it to a DOS date/time.

Parameters:

jTime - The number of milliseconds since midnight, January 1st, 1970 AD UTC (called the epoch alias Java time).

Returns:

yes for round-up, no for round-down.