Class TemporalValue

This topic only applies to self-managed Intelligent Advisor edition

java.lang.Object

com.oracle.determinations.engine.TemporalValue

All Implemented Interfaces:: java.io.Serializable

public final class TemporalValue
extends java.lang.Object
implements java.io.Serializable

An immutable class that represents a temporal value. A temporal value is a value that changes over time. In the case of the determinations engine, a temporal value is specified as an initial value, plus zero or more change points. A change point indicates where the value changes at a given point in time. In this implementation, change points are an ordered list of values and a the start date at which the value applies. The change points are ordered in ascending order of applicable dates.

Since:: 9.1
See Also:: ChangePoint, YearMonthDay

Constructor Summary

Constructor and Description
`TemporalValue()` Create an unknown temporal value, with no change points specified.
`TemporalValue(java.lang.Object v)` Create a new temporal value containing the specified object value, and no change points.
`TemporalValue(java.lang.Object v, java.util.List<ChangePoint> changes)` Create a new temporal value containing a base object value, plus a list of zero or more ChangePoint objects.
`TemporalValue(java.lang.Object v, com.oracle.determinations.util.datetime.YearMonthDay d1, java.lang.Object v1)` Create a new temporal value containing a base object value, plus a single change point at which the value changes.
`TemporalValue(java.lang.Object v, com.oracle.determinations.util.datetime.YearMonthDay d1, java.lang.Object v1, com.oracle.determinations.util.datetime.YearMonthDay d2, java.lang.Object v2)` Create a new temporal value containing a base object value, and two change points at which the value changes.
`TemporalValue(java.lang.Object v, com.oracle.determinations.util.datetime.YearMonthDay d1, java.lang.Object v1, com.oracle.determinations.util.datetime.YearMonthDay d2, java.lang.Object v2, com.oracle.determinations.util.datetime.YearMonthDay d3, java.lang.Object v3)` Create a new temporal value containing a base object value, and three change points at which the value changes.
`TemporalValue(java.lang.Object v, com.oracle.determinations.util.datetime.YearMonthDay d1, java.lang.Object v1, com.oracle.determinations.util.datetime.YearMonthDay d2, java.lang.Object v2, com.oracle.determinations.util.datetime.YearMonthDay d3, java.lang.Object v3, com.oracle.determinations.util.datetime.YearMonthDay d4, java.lang.Object v4)` Create a new temporal value containing a base object value, and three change points at which the value changes.

Method Summary

Modifier and Type	Method and Description
`java.lang.Object`	`clip(com.oracle.determinations.util.datetime.YearMonthDay startDate, com.oracle.determinations.util.datetime.YearMonthDay endDate)` Clip the temporal window such that the given startDate and endDate are contained within the new window.
`static java.lang.Object`	`createAndMerge(java.lang.Object v, java.util.List<ChangePoint> changes)` Factory method for creating a new temporal value, based on a base value and a list of zero or more change points.
`void`	`ensureChangePointsOrdered()` Checks that change points are correctly ordered from earliest to latest.
`void`	`ensureValidType(byte dataType)` Checks if all values in this temporal attribute are valid as against the specified data type.
`boolean`	`equals(java.lang.Object arg0)` Determine if two temporal values are indeed equal.
`int`	`findChangePointIndex(com.oracle.determinations.util.datetime.YearMonthDay d)` Returns the index of the change point that covers the specified date.
`com.oracle.determinations.util.datetime.YearMonthDay`	`getDate(int idx)` Determine the change point date at the given index.
`java.lang.Object`	`getValue(int idx)` Determine the value at the given index.
`int`	`hashCode()` Determine the hash code for this temporal value.
`static boolean`	`isEqual(java.lang.Object a, java.lang.Object b)` Determine whether one object is equal to another.
`boolean`	`isEverUnknown()` Determine whether this temporal value contains an unknown value at any time.
`boolean`	`isUniversal()` Determine whether this temporal value contains any change points.
`com.oracle.determinations.util.datetime.YearMonthDay`	`nextDate(com.oracle.determinations.util.datetime.YearMonthDay d)` Returns the next change point for the given change point date.
`static double`	`numericValue(java.lang.Object v)` Simple algorithm for determining a simple numeric value from a Number object.
`com.oracle.determinations.util.datetime.YearMonthDay`	`previousDate(com.oracle.determinations.util.datetime.YearMonthDay d)` Returns the previous change point for the given change point date.
`int`	`size()` Determine the non-distinct number of values contained by this temporal value.
`java.lang.String`	`toString()` Handy output method for debugging purposes.
`java.lang.Object`	`valueAtDate(com.oracle.determinations.util.datetime.YearMonthDay d)` Returns the value corresponding to the specified date.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TemporalValue

public TemporalValue()

Create an unknown temporal value, with no change points specified.

TemporalValue

public TemporalValue(java.lang.Object v)

Create a new temporal value containing the specified object value, and no change points.

Parameters:: v - the base value to be represented by this temporal value

TemporalValue

public TemporalValue(java.lang.Object v,
             java.util.List<ChangePoint> changes)

Create a new temporal value containing a base object value, plus a list of zero or more ChangePoint objects. The list must be ordered in ascending order of change point dates. Each object value must be type-compatible to the attribute to which it will be assigned.

The change point list is not validated until the resulting temporal value object is assigned to an attribute. A defensive copy of the list is made.

Parameters:: v - the initial value of this temporal value; changes - a List<ChangePoint> of zero or more change points, in ascending order of change point dates, or null if there are no applicable change points
Throws:: java.lang.ClassCastException - one or more items in the change list is not a ChangePoint object

TemporalValue

public TemporalValue(java.lang.Object v,
             com.oracle.determinations.util.datetime.YearMonthDay d1,
             java.lang.Object v1)

Create a new temporal value containing a base object value, plus a single change point at which the value changes.

Parameters:: v - the initial value of this temporal value; d1 - the change point date at which the value changes; v1 - the value at the given change point

TemporalValue

public TemporalValue(java.lang.Object v,
             com.oracle.determinations.util.datetime.YearMonthDay d1,
             java.lang.Object v1,
             com.oracle.determinations.util.datetime.YearMonthDay d2,
             java.lang.Object v2)

Create a new temporal value containing a base object value, and two change points at which the value changes. The change points must be specified in ascending order of change point dates.

Parameters:: v - the initial value of this temporal value; d1 - the first change point date at which the value changes; v1 - the value at the first change point; d2 - the second change point date at which the value changes; v2 - the value at the second change point

TemporalValue

public TemporalValue(java.lang.Object v,
             com.oracle.determinations.util.datetime.YearMonthDay d1,
             java.lang.Object v1,
             com.oracle.determinations.util.datetime.YearMonthDay d2,
             java.lang.Object v2,
             com.oracle.determinations.util.datetime.YearMonthDay d3,
             java.lang.Object v3)

Create a new temporal value containing a base object value, and three change points at which the value changes. The change points must be specified in ascending order of change point dates.

Parameters:: v - the initial value of this temporal value; d1 - the first change point date at which the value changes; v1 - the value at the first change point; d2 - the second change point date at which the value changes; v2 - the value at the second change point; d3 - the third change point date at which the value changes; v3 - the value at the third change point

TemporalValue

public TemporalValue(java.lang.Object v,
             com.oracle.determinations.util.datetime.YearMonthDay d1,
             java.lang.Object v1,
             com.oracle.determinations.util.datetime.YearMonthDay d2,
             java.lang.Object v2,
             com.oracle.determinations.util.datetime.YearMonthDay d3,
             java.lang.Object v3,
             com.oracle.determinations.util.datetime.YearMonthDay d4,
             java.lang.Object v4)

Create a new temporal value containing a base object value, and three change points at which the value changes. The change points must be specified in ascending order of change point dates.

Parameters:: v - the initial value of this temporal value; d1 - the first change point date at which the value changes; v1 - the value at the first change point; d2 - the second change point date at which the value changes; v2 - the value at the second change point; d3 - the third change point date at which the value changes; v3 - the value at the third change point; d4 - the fourth change point date at which the value changes; v4 - the value at the fourth change point

Method Detail

clip

public java.lang.Object clip(com.oracle.determinations.util.datetime.YearMonthDay startDate,
                    com.oracle.determinations.util.datetime.YearMonthDay endDate)

Clip the temporal window such that the given startDate and endDate are contained within the new window. A new TemporalValue object is returned. The clipping range is start date inclusive, end date exclusive. If the clipping window results in only one value, the value itself is returned.

Parameters:: startDate - the start date from which the temporal value should be clipped; endDate - the end date from which the temporal value should be truncated
Returns:: a new TemporalValue object containing values within the specified change point window, or a simple value object if clipping results in a single value

createAndMerge

public static java.lang.Object createAndMerge(java.lang.Object v,
                              java.util.List<ChangePoint> changes)

Factory method for creating a new temporal value, based on a base value and a list of zero or more change points.

The change point list is scanned to ensure that change points are accumulated in ascending order. If consecutive change points are not in ascending order, the previous change point is removed from the list.

Parameters:: v - the base value for the temporal value; changes - a List<ChangePoint> of zero or more change points
Returns:: a new TemporalValue object if more than one change point is in effect, otherwise returns the base value
Throws:: java.lang.ClassCastException - one or more items in the change list is not a ChangePoint object

ensureChangePointsOrdered

public void ensureChangePointsOrdered()

Checks that change points are correctly ordered from earliest to latest.

Throws:: java.lang.IllegalArgumentException - if change points are unordered.

ensureValidType

public void ensureValidType(byte dataType)
                     throws java.lang.ClassCastException,
                            java.lang.IllegalArgumentException

Checks if all values in this temporal attribute are valid as against the specified data type.

Parameters:: dataType - the AttributeType to validate the values against
Throws:: java.lang.IllegalArgumentException - if dataType is not a valid AttributeType.; java.lang.ClassCastException - if any of the temporal values is not according to it type

equals

public boolean equals(java.lang.Object arg0)

Determine if two temporal values are indeed equal.

Overrides:: equals in class java.lang.Object

findChangePointIndex

public int findChangePointIndex(com.oracle.determinations.util.datetime.YearMonthDay d)

Returns the index of the change point that covers the specified date.

Parameters:: d - the date for which the index should be determined
Returns:: the index corresponding to the value at the specified date

getDate

public com.oracle.determinations.util.datetime.YearMonthDay getDate(int idx)

Determine the change point date at the given index. As a special case, the index of zero indicates the base value, and will always return null.

Parameters:: idx - the index of the change point date to be returned
Returns:: the corresponding change point date, or null to represent the base value
Throws:: java.lang.IndexOutOfBoundsException - the index is out of bounds

getValue

public java.lang.Object getValue(int idx)

Determine the value at the given index. As a special case, the index of zero always retrieves the base value.

Parameters:: idx - the index of the change point date to be returned
Returns:: the corresponding change point date, or null to represent the base value
Throws:: java.lang.IndexOutOfBoundsException - the index is out of bounds

hashCode

public int hashCode()

Determine the hash code for this temporal value.

Overrides:: hashCode in class java.lang.Object

isEqual

public static boolean isEqual(java.lang.Object a,
              java.lang.Object b)

Determine whether one object is equal to another. This method deals with either or both objects being null.

Parameters:: a - the first object to be compared, possibly null; b - the second object to be compared, possibly null
Returns:: true if both objects are equal or both objects are null, otherwise false

isEverUnknown

public boolean isEverUnknown()

Determine whether this temporal value contains an unknown value at any time.

Returns:: true if this temporal value is unknown at any point in time, otherwise false

isUniversal

public boolean isUniversal()

Determine whether this temporal value contains any change points.

Returns:: true if this temporal value contains change points, otherwise false

nextDate

public com.oracle.determinations.util.datetime.YearMonthDay nextDate(com.oracle.determinations.util.datetime.YearMonthDay d)

Returns the next change point for the given change point date.

Parameters:: d - the change point date for which the next change point should be determined
Returns:: the next change point date, or null if no next change point exists

numericValue

public static double numericValue(java.lang.Object v)

Simple algorithm for determining a simple numeric value from a Number object.

Parameters:: v - the object whose numeric value should be determined
Returns:: the numeric value of the number, as a double, otherwise 0.0d is returned

previousDate

public com.oracle.determinations.util.datetime.YearMonthDay previousDate(com.oracle.determinations.util.datetime.YearMonthDay d)

Returns the previous change point for the given change point date.

Parameters:: d - the change point date for which the previous change point should be determined
Returns:: the previous change point date, or null if no previous change point exists

size

public int size()

Determine the non-distinct number of values contained by this temporal value. If this temporal value contains no change points, the number 1 is returned. Otherwise, the number returned is one greater than the number of change points represented by this temporal value.

Returns:: the number of values contained by this temporal value

toString

public java.lang.String toString()

Handy output method for debugging purposes.

Overrides:: toString in class java.lang.Object

valueAtDate

public java.lang.Object valueAtDate(com.oracle.determinations.util.datetime.YearMonthDay d)

Returns the value corresponding to the specified date.

Parameters:: d - the date for which the value should be determined
Returns:: the value in effect at the specified date