Package org.apache.derby.iapi.types
Class SQLTime
java.lang.Object
org.apache.derby.iapi.types.DataType
org.apache.derby.iapi.types.SQLTime
- All Implemented Interfaces:
Externalizable
,Serializable
,Comparable
,Formatable
,Storable
,TypedFormat
,DataValueDescriptor
,DateTimeDataValue
,Orderable
This contains an instance of a SQL Time
Our current implementation doesn't implement time precision so the fractional
seconds portion of the time is always 0. The default when no time precision
is specified is 0 fractional seconds. A SQL Time without timezone information
is assumed to be in the local time zone. The local time is stored as is
and doesn't change if the timezone changes. This is in conformance with the
SQL99 standard. The SQL92 standard indicates that the time is in GMT and
changes with the timezone. The SQL99 standard clarifies this to allow time without
timezoned to be stored as the local time.
Time is stored as two ints. The first int represents hour, minute, second and the second represents fractional seconds (currently 0 since we don't support time precision) encodedTime = -1 indicates null PERFORMANCE OPTIMIZATION: The java.sql.Time object is only instantiated on demand for performance reasons.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final String[]
private static final char[]
private static final int
private int
private int
private static final char[]
private static final char
private static final char[]
(package private) static final char
private static final char[]
Fields inherited from interface org.apache.derby.iapi.types.DataValueDescriptor
UNKNOWN_LOGICAL_LENGTH
Fields inherited from interface org.apache.derby.iapi.types.DateTimeDataValue
DAY_FIELD, DAY_INTERVAL, FRAC_SECOND_INTERVAL, HOUR_FIELD, HOUR_INTERVAL, MINUTE_FIELD, MINUTE_INTERVAL, MONTH_FIELD, MONTH_INTERVAL, QUARTER_INTERVAL, SECOND_FIELD, SECOND_INTERVAL, WEEK_INTERVAL, YEAR_FIELD, YEAR_INTERVAL
Fields inherited from interface org.apache.derby.iapi.types.Orderable
ORDER_OP_EQUALS, ORDER_OP_GREATEROREQUALS, ORDER_OP_GREATERTHAN, ORDER_OP_LESSOREQUALS, ORDER_OP_LESSTHAN
-
Constructor Summary
ConstructorsModifierConstructorDescriptionSQLTime()
no-arg constructor required by Formattableprivate
SQLTime
(int encodedTime, int encodedTimeFraction) SQLTime
(String timeStr, boolean isJdbcEscape, LocaleFinder localeFinder) Construct a time from a string.SQLTime
(String timeStr, boolean isJdbcEscape, LocaleFinder localeFinder, Calendar cal) Construct a time from a string. -
Method Summary
Modifier and TypeMethodDescriptioncloneValue
(boolean forceMaterialization) Clone this DataValueDescriptor.boolean
compare
(int op, DataValueDescriptor other, boolean orderedNulls, boolean unknownRV) Compare this Orderable with a given Orderable for the purpose of qualification and sorting.int
compare
(DataValueDescriptor other) Orderable interface(package private) static int
computeEncodedTime
(int hour, int minute, int second) (package private) static int
Calculate the encoded time from a Calendar object encoded time is hour << 16 + min << 8 + sec this function is also used by SQLTimestampprivate int
computeEncodedTime
(Date value) Compute encoded time value Time is represented by hour << 16 + minute << 8 + seconds(package private) static int
computeEncodedTime
(Date value, Calendar currentCal) protected static String
encodedTimeToString
(int encodedTime) Get the String version from the encodedTime.int
Estimate the memory usage in bytes of the data value and the overhead of the class.getDate
(NumberDataValue result) Get the day of the month.(package private) int
protected static int
getHour
(int encodedTime) Get the encoded hour value (may be different than hour value for current timezone if value encoded in a different timezone)getHours
(NumberDataValue result) Get the hour of the day out of a time or timestamp.int
Gets the length of the data value.protected static int
getMinute
(int encodedTime) Get the encoded minute value (may be different than the minute value for current timezone if value encoded in a different timezone)getMinutes
(NumberDataValue result) Get the minute of the hour out of a time or timestamp.getMonth
(NumberDataValue result) Get the month number out of a date.Get a new null value of the same type as this data value.Gets the value in the data value descriptor as a int.protected static int
getSecond
(int encodedTime) Get the encoded second value (may be different than the second value for current timezone if value encoded in a different timezone)getSeconds
(NumberDataValue result) Get the second of the minute out of a time or timestamp.Gets the value in the data value descriptor as a String.Get the time value Since this is a JDBC object we use the JDBC definition we use the JDBC definition, see JDBC API Tutorial and Reference section 47.3.12 Date is set to Jan. 1, 1970(package private) static Time
Get a java.sql.Time object from an encoded time and nano-second value.getTimestamp
(Calendar cal) Convert a SQL TIME to a JDBC java.sql.Timestamp.int
Return my format identifier.Get the SQL name of the datatypegetYear
(NumberDataValue result) Get the year number out of a date.int
hashCode()
final boolean
isNull()
Check if the value is null.(package private) NumberDataValue
private void
parseTime
(String timeStr, boolean isJdbcEscape, LocaleFinder localeFinder, Calendar cal) private void
void
void
Restore this object to its (SQL)null value.protected void
setFrom
(DataValueDescriptor theValue) Set the value of this DataValueDescriptor based on the value of the specified DataValueDescriptor.void
setInto
(PreparedStatement ps, int position) Adding this method to ensure that super class' setInto method doesn't get called that leads to the violation of JDBC spec( untyped nulls ) when batching is turned on.(package private) void
Set the value from a correctly typed Time object.(package private) static void
setTimeInCalendar
(Calendar cal, int encodedTime) Set the time portion of a date-time value into the passed in Calendar object from its encodedTime value.void
Set the value of this DataValueDescriptor.void
Set the value of this DataValueDescriptor.void
Set the value of this DataValueDescriptor.void
setValueFromResultSet
(ResultSet resultSet, int colNumber, boolean isNullable) Set the value based on the value for the specified DataValueDescriptor from the specified ResultSet.timestampAdd
(int intervalType, NumberDataValue intervalCount, Date currentDate, DateTimeDataValue resultHolder) Add a number of intervals to a datetime value.timestampDiff
(int intervalType, DateTimeDataValue time1, Date currentDate, NumberDataValue resultHolder) Finds the difference between two datetime values as a number of intervals.(package private) static void
timeToString
(int hour, int minute, int second, StringBuffer sb) Convert a time to a JDBC escape format stringtoString()
private SQLTimestamp
toTimestamp
(Date currentDate) int
Each built-in type in JSQL has a precedence.void
Methods inherited from class org.apache.derby.iapi.types.DataType
checkHostVariable, cloneHolder, coalesce, compare, compare, compareTo, dataTypeConversion, equals, equals, flip, genericSetObject, getBoolean, getByte, getBytes, getDate, getDouble, getFloat, getInt, getLong, getShort, getStream, getTraceString, getTypeName, greaterOrEquals, greaterThan, hasStream, in, invalidFormat, isNotNull, isNullOp, lessOrEquals, lessThan, normalize, notEquals, outOfRange, readExternalFromArray, recycle, setBigDecimal, setInto, setObjectForCast, setToNull, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, throwLangSetMismatch, throwLangSetMismatch, typeToBigDecimal
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.apache.derby.iapi.types.DataValueDescriptor
checkHostVariable, cloneHolder, coalesce, compare, compare, equals, getBoolean, getByte, getBytes, getDate, getDouble, getFloat, getInt, getLong, getShort, getStream, getTraceString, greaterOrEquals, greaterThan, hasStream, in, isNotNull, isNullOp, lessOrEquals, lessThan, normalize, notEquals, readExternalFromArray, recycle, setBigDecimal, setInto, setObjectForCast, setToNull, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, typeToBigDecimal
-
Field Details
-
encodedTime
private int encodedTime -
encodedTimeFraction
private int encodedTimeFraction -
BASE_MEMORY_USAGE
private static final int BASE_MEMORY_USAGE -
IBM_EUR_SEPARATOR
private static final char IBM_EUR_SEPARATOR- See Also:
-
IBM_EUR_SEPARATOR_OR_END
private static final char[] IBM_EUR_SEPARATOR_OR_END -
JIS_SEPARATOR
static final char JIS_SEPARATOR- See Also:
-
US_OR_JIS_MINUTE_END
private static final char[] US_OR_JIS_MINUTE_END -
ANY_SEPARATOR
private static final char[] ANY_SEPARATOR -
AM_PM
-
END_OF_STRING
private static final char[] END_OF_STRING
-
-
Constructor Details
-
SQLTime
public SQLTime()no-arg constructor required by Formattable -
SQLTime
- Throws:
StandardException
-
SQLTime
private SQLTime(int encodedTime, int encodedTimeFraction) -
SQLTime
public SQLTime(String timeStr, boolean isJdbcEscape, LocaleFinder localeFinder) throws StandardException Construct a time from a string. The allowed time formats are:- old ISO and IBM European standard: hh.mm[.ss]
- IBM USA standard: hh[:mm] {AM | PM}
- JIS and current ISO: hh:mm[:ss]
- Throws:
StandardException
- if the syntax is invalid or the value is out of range
-
SQLTime
public SQLTime(String timeStr, boolean isJdbcEscape, LocaleFinder localeFinder, Calendar cal) throws StandardException Construct a time from a string. The allowed time formats are:- old ISO and IBM European standard: hh.mm[.ss]
- IBM USA standard: hh[:mm] {AM | PM}
- JIS and current ISO: hh:mm[:ss]
- Throws:
StandardException
- if the syntax is invalid or the value is out of range
-
-
Method Details
-
estimateMemoryUsage
public int estimateMemoryUsage()Description copied from interface:DataValueDescriptor
Estimate the memory usage in bytes of the data value and the overhead of the class.- Specified by:
estimateMemoryUsage
in interfaceDataValueDescriptor
- Returns:
- the estimated memory usage
-
getString
Description copied from interface:DataValueDescriptor
Gets the value in the data value descriptor as a String. Throws an exception if the data value is not a string.- Specified by:
getString
in interfaceDataValueDescriptor
- Returns:
- The data value as a String.
-
getEncodedTime
int getEncodedTime() -
getTimestamp
Convert a SQL TIME to a JDBC java.sql.Timestamp. Behaviour is to set the date portion of the Timestamp to the actual current date, which may not match the SQL CURRENT DATE, which remains fixed for the lifetime of a SQL statement. JDBC drivers (especially network client drivers) could not be expected to fetch the CURRENT_DATE SQL value on every query that involved a TIME value, so the current date as seen by the JDBC client was picked as the logical behaviour. See DERBY-1811.- Specified by:
getTimestamp
in interfaceDataValueDescriptor
- Overrides:
getTimestamp
in classDataType
- Parameters:
cal
- calendar for object creation- Returns:
- The data value as a java.sql.Timestamp.
-
getObject
Description copied from class:DataType
Gets the value in the data value descriptor as a int. Throws an exception if the data value is not receivable as a int.- Specified by:
getObject
in interfaceDataValueDescriptor
- Overrides:
getObject
in classDataType
- Returns:
- The data value as a int.
-
getLength
public int getLength()Description copied from interface:DataValueDescriptor
Gets the length of the data value. The meaning of this is implementation-dependent. For string types, it is the number of characters in the string. For numeric types, it is the number of bytes used to store the number. This is the actual length of this value, not the length of the type it was defined as. For example, a VARCHAR value may be shorter than the declared VARCHAR (maximum) length.- Specified by:
getLength
in interfaceDataValueDescriptor
- Returns:
- The length of the data value
-
getTypeName
Description copied from interface:DataValueDescriptor
Get the SQL name of the datatype- Specified by:
getTypeName
in interfaceDataValueDescriptor
- Returns:
- The SQL name of the datatype
-
getTypeFormatId
public int getTypeFormatId()Return my format identifier.- Specified by:
getTypeFormatId
in interfaceTypedFormat
- Returns:
- The identifier. (A UUID stuffed in an array of 16 bytes).
- See Also:
-
writeExternal
- Specified by:
writeExternal
in interfaceExternalizable
- Throws:
IOException
- error writing data
-
readExternal
- Specified by:
readExternal
in interfaceExternalizable
- Throws:
IOException
- Thrown on error reading the object- See Also:
-
cloneValue
Description copied from interface:DataValueDescriptor
Clone this DataValueDescriptor. Results in a new object that has the same value as this but can be modified independently.Even though the objects can be modified independently regardless of the value of
forceMaterialization
, both the clone and the original may be dependent on the store state ifforceMaterialization
is set tofalse
. An example is if you need to access the value you just read usingcloneValue
after the current transaction has ended, or after the source result set has been closed.- Specified by:
cloneValue
in interfaceDataValueDescriptor
- Parameters:
forceMaterialization
- any streams representing the data value will be materialized iftrue
, the data value will be kept as a stream if possible iffalse
- Returns:
- A clone of the
DataValueDescriptor
with the same initial value as this. - See Also:
-
getNewNull
Description copied from interface:DataValueDescriptor
Get a new null value of the same type as this data value.- Specified by:
getNewNull
in interfaceDataValueDescriptor
- See Also:
-
restoreToNull
public void restoreToNull()Description copied from interface:Storable
Restore this object to its (SQL)null value.- Specified by:
restoreToNull
in interfaceStorable
- See Also:
-
setValueFromResultSet
public void setValueFromResultSet(ResultSet resultSet, int colNumber, boolean isNullable) throws SQLException, StandardException Description copied from interface:DataValueDescriptor
Set the value based on the value for the specified DataValueDescriptor from the specified ResultSet.- Specified by:
setValueFromResultSet
in interfaceDataValueDescriptor
- Parameters:
resultSet
- The specified ResultSet.colNumber
- The 1-based column # into the resultSet.isNullable
- Whether or not the column is nullable (No need to call wasNull() if not)- Throws:
SQLException
- Thrown on errorStandardException
- Thrown on error- See Also:
-
compare
Orderable interface- Specified by:
compare
in interfaceDataValueDescriptor
- Parameters:
other
- The Orderable to compare this one to.- Returns:
- <0 - this Orderable is less than other. 0 - this Orderable equals other. >0 - this Orderable is greater than other. The code should not explicitly look for -1, or 1.
- Throws:
StandardException
- thrown on failure- See Also:
-
compare
public boolean compare(int op, DataValueDescriptor other, boolean orderedNulls, boolean unknownRV) throws StandardException Description copied from interface:DataValueDescriptor
Compare this Orderable with a given Orderable for the purpose of qualification and sorting. The caller gets to determine how nulls should be treated - they can either be ordered values or unknown values.- Specified by:
compare
in interfaceDataValueDescriptor
- Overrides:
compare
in classDataType
- Parameters:
op
- Orderable.ORDER_OP_EQUALS means do an = comparison. Orderable.ORDER_OP_LESSTHAN means compare this < other. Orderable.ORDER_OP_LESSOREQUALS means compare this <= other.other
- The DataValueDescriptor to compare this one to.orderedNulls
- True means to treat nulls as ordered values, that is, treat SQL null as equal to null, and less than all other values. False means to treat nulls as unknown values, that is, the result of any comparison with a null is the UNKNOWN truth value.unknownRV
- The return value to use if the result of the comparison is the UNKNOWN truth value. In other words, if orderedNulls is false, and a null is involved in the comparison, return unknownRV. This parameter is not used orderedNulls is true.- Returns:
- true if the comparison is true (duh!)
- Throws:
StandardException
- thrown on error
-
parseTime
- Throws:
StandardException
-
parseTime
private void parseTime(String timeStr, boolean isJdbcEscape, LocaleFinder localeFinder, Calendar cal) throws StandardException - Throws:
StandardException
-
setObject
Set the value from a correctly typed Time object.- Overrides:
setObject
in classDataType
- Throws:
StandardException
-
setFrom
Description copied from class:DataType
Set the value of this DataValueDescriptor based on the value of the specified DataValueDescriptor.- Overrides:
setFrom
in classDataType
- Parameters:
theValue
- The DataValueDescriptor that holds the value to which we want to set this DataValueDescriptor's value.- Throws:
StandardException
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
value
- The Time value to set this DataValueDescriptor tocal
- The time zone from the calendar is used to construct the database time value- Throws:
StandardException
- thrown on failure.- See Also:
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
value
- The Timestamp value to set this DataValueDescriptor tocal
- The time zone from the calendar is used to construct the database timestamp value- Throws:
StandardException
- thrown on failure.- See Also:
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The BigDecimal value to set this DataValueDescriptor to- Throws:
StandardException
-
nullValueInt
NumberDataValue nullValueInt() -
getYear
Description copied from interface:DateTimeDataValue
Get the year number out of a date.- Specified by:
getYear
in interfaceDateTimeDataValue
- Parameters:
result
- The result of the previous call to this method, null if not called yet.- Returns:
- A NumberDataValue containing the year number.
- Throws:
StandardException
- Thrown on error- See Also:
-
getMonth
Description copied from interface:DateTimeDataValue
Get the month number out of a date.- Specified by:
getMonth
in interfaceDateTimeDataValue
- Parameters:
result
- The result of the previous call to this method, null if not called yet.- Returns:
- A NumberDataValue containing the month number.
- Throws:
StandardException
- Thrown on error- See Also:
-
getDate
Description copied from interface:DateTimeDataValue
Get the day of the month.- Specified by:
getDate
in interfaceDateTimeDataValue
- Parameters:
result
- The result of the previous call to this method, null if not called yet.- Returns:
- A NumberDataValue containing the day of the month.
- Throws:
StandardException
- Thrown on error- See Also:
-
getHours
Description copied from interface:DateTimeDataValue
Get the hour of the day out of a time or timestamp.- Specified by:
getHours
in interfaceDateTimeDataValue
- Parameters:
result
- The result of the previous call to this method, null if not called yet.- Returns:
- A NumberDataValue containing the hour of the day.
- Throws:
StandardException
- Thrown on error- See Also:
-
getMinutes
Description copied from interface:DateTimeDataValue
Get the minute of the hour out of a time or timestamp.- Specified by:
getMinutes
in interfaceDateTimeDataValue
- Parameters:
result
- The result of the previous call to this method, null if not called yet.- Returns:
- A NumberDataValue containing the minute of the hour.
- Throws:
StandardException
- Thrown on error- See Also:
-
getSeconds
Description copied from interface:DateTimeDataValue
Get the second of the minute out of a time or timestamp.- Specified by:
getSeconds
in interfaceDateTimeDataValue
- Parameters:
result
- The result of the previous call to this method, null if not called yet.- Returns:
- A NumberDataValue containing the second of the minute.
- Throws:
StandardException
- Thrown on error- See Also:
-
toString
-
hashCode
public int hashCode() -
typePrecedence
public int typePrecedence()Description copied from class:DataType
Each built-in type in JSQL has a precedence. This precedence determines how to do type promotion when using binary operators. For example, float has a higher precedence than int, so when adding an int to a float, the result type is float. The precedence for some types is arbitrary. For example, it doesn't matter what the precedence of the boolean type is, since it can't be mixed with other types. But the precedence for the number types is critical. The SQL standard requires that exact numeric types be promoted to approximate numeric when one operator uses both. Also, the precedence is arranged so that one will not lose precision when promoting a type.- Specified by:
typePrecedence
in interfaceDataValueDescriptor
- Overrides:
typePrecedence
in classDataType
- Returns:
- The precedence of this type.
- See Also:
-
isNull
public final boolean isNull()Check if the value is null. -
getTime
Get the time value Since this is a JDBC object we use the JDBC definition we use the JDBC definition, see JDBC API Tutorial and Reference section 47.3.12 Date is set to Jan. 1, 1970- Specified by:
getTime
in interfaceDataValueDescriptor
- Overrides:
getTime
in classDataType
- Parameters:
cal
- calendar for object creation- Returns:
- The localized time value.
-
setTimeInCalendar
Set the time portion of a date-time value into the passed in Calendar object from its encodedTime value. Note that this is only the time down to a resolution of one second. Only the HOUR_OF_DAY, MINUTE and SECOND fields are modified. The remaining state of the Calendar is not modified. -
getTime
Get a java.sql.Time object from an encoded time and nano-second value. As required by JDBC the date component of the Time object will be set to Jan. 1, 1970- Parameters:
cal
- Calendar to use for conversionencodedTime
- Derby encoded time valuenanos
- number of nano-seconds.- Returns:
- Valid Time object.
-
getHour
protected static int getHour(int encodedTime) Get the encoded hour value (may be different than hour value for current timezone if value encoded in a different timezone)- Returns:
- hour value
-
getMinute
protected static int getMinute(int encodedTime) Get the encoded minute value (may be different than the minute value for current timezone if value encoded in a different timezone)- Returns:
- minute value
-
getSecond
protected static int getSecond(int encodedTime) Get the encoded second value (may be different than the second value for current timezone if value encoded in a different timezone)- Returns:
- second value
-
computeEncodedTime
Calculate the encoded time from a Calendar object encoded time is hour << 16 + min << 8 + sec this function is also used by SQLTimestamp- Parameters:
cal
- calendar with time set- Returns:
- encoded time
- Throws:
StandardException
- if the time is not in the DB2 range
-
computeEncodedTime
- Throws:
StandardException
-
timeToString
Convert a time to a JDBC escape format string- Parameters:
hour
-minute
-second
-sb
- The resulting string is appended to this StringBuffer
-
encodedTimeToString
Get the String version from the encodedTime.- Returns:
- string value.
-
computeEncodedTime
Compute encoded time value Time is represented by hour << 16 + minute << 8 + seconds- Throws:
StandardException
-
computeEncodedTime
- Throws:
StandardException
-
setInto
Adding this method to ensure that super class' setInto method doesn't get called that leads to the violation of JDBC spec( untyped nulls ) when batching is turned on.- Specified by:
setInto
in interfaceDataValueDescriptor
- Overrides:
setInto
in classDataType
- Throws:
SQLException
- thrown by the PreparedStatement objectStandardException
- thrown by me accessing my value.
-
timestampAdd
public DateTimeDataValue timestampAdd(int intervalType, NumberDataValue intervalCount, Date currentDate, DateTimeDataValue resultHolder) throws StandardException Add a number of intervals to a datetime value. Implements the JDBC escape TIMESTAMPADD function.- Specified by:
timestampAdd
in interfaceDateTimeDataValue
- Parameters:
intervalType
- One of FRAC_SECOND_INTERVAL, SECOND_INTERVAL, MINUTE_INTERVAL, HOUR_INTERVAL, DAY_INTERVAL, WEEK_INTERVAL, MONTH_INTERVAL, QUARTER_INTERVAL, or YEAR_INTERVALintervalCount
- The number of intervals to addcurrentDate
- Used to convert time to timestampresultHolder
- If non-null a DateTimeDataValue that can be used to hold the result. If null then generate a new holder- Returns:
- startTime + intervalCount intervals, as a timestamp
- Throws:
StandardException
-
toTimestamp
- Throws:
StandardException
-
timestampDiff
public NumberDataValue timestampDiff(int intervalType, DateTimeDataValue time1, Date currentDate, NumberDataValue resultHolder) throws StandardException Finds the difference between two datetime values as a number of intervals. Implements the JDBC TIMESTAMPDIFF escape function.- Specified by:
timestampDiff
in interfaceDateTimeDataValue
- Parameters:
intervalType
- One of FRAC_SECOND_INTERVAL, SECOND_INTERVAL, MINUTE_INTERVAL, HOUR_INTERVAL, DAY_INTERVAL, WEEK_INTERVAL, MONTH_INTERVAL, QUARTER_INTERVAL, or YEAR_INTERVALtime1
-currentDate
- Used to convert time to timestampresultHolder
- If non-null a NumberDataValue that can be used to hold the result. If null then generate a new holder- Returns:
- the number of intervals by which this datetime is greater than time1
- Throws:
StandardException
-