NSTimestamp

Inherits from:

java.sql.Timestamp : java.util.Date : Object

Implements:

NSCoding

Package:

com.webobjects.foundation

Class Description

NSTimestamp objects represent a particular instance in time. NSTimestamp is a subclass of java.sql.Timestamp, itself a subclass of java.util.Date. Unlike the NSGregorianDate class in previous versions of the Foundation framework, NSTimestamp does not support calendar functions. Refer to the table below to determine which classes to use to perform date operations in WebObjects.

See the Sun's documentation for the java.util.GregorianCalendar class for more information about using calendars in Java.

Common Date Operations

For the following code segments, you need to import java.util.* to access Java's date API.

To break up a NSTimestamp into its component year, month, day, hour, etc., you can convert it into a java.util.GregorianCalendar and invoke its get method on the individual fields:

NSTimestamp myNSTimestamp = new NSTimestamp();
GregorianCalendar myCalendar = new GregorianCalendar();
myCalendar.setTime(myNSTimestamp);
int year = myCalendar.get(GregorianCalendar.YEAR);
int dayOfMonth = myCalendar.get(GregorianCalendar.DAY_OF_MONTH);

To create an NSTimestamp based on its components, use the following code:

NSTimeZone tz = NSTimeZone.timeZoneWithName("America/Los_Angeles", true);
NSTimestamp myNSTimestamp = new NSTimestamp(year, month, day, hour, minute, seconds, tz);
		

To add an offset in Gregorian units to an NSTimestamp, use the following code:

NSTimestamp myNSTimestamp = new NSTimestamp();
myNSTimestamp.timestampByAddingGregorianUnits(year, month, day, hour, minute, seconds);

To create an NSTimestamp representing the current time, use the no-argument constructor:

NSTimestamp currentTime = new NSTimestamp();

The Enterprise Objects Framework expects dates to be represented as NSTimestamp objects. To convert a java.util.Date to an NSTimestamp use:

NSTimestamp myNSTimestamp = new NSTimestamp(myJavaUtilDate);

Since NSTimestamp is a subclass of java.util.Date, you don't need to convert an NSTimestamp into a java.util.Date.

Constants

NSTimestamp provides the following constants.

Interfaces Implemented

NSCoding

classForCoder

decodeObject

encodeWithCoder

Method Types

Constructors

NSTimestamp

Instance methods

compare

toString

Deprecated methods

currentTimeIntervalSinceReferenceDate

dayOfCommonEra

dayOfMonth

dayOfWeek

dayOfYear

distantFuture

distantPast

earlierTimestamp

gregorianUnitsSinceTimestamp

hourOfDay

laterTimestamp

microsecondOfSecond

millisecondsToTimeInterval

minuteOfHour

monthOfYear

secondOfMinute

timeIntervalSinceNow

timeIntervalSinceReferenceDate

timeIntervalSinceTimestamp

timeIntervalToMilliseconds

setDate

setHours

setMinutes

setMonth

setNanos

setSeconds

setTime

setYear

timestampByAddingGregorianUnits

timestampByAddingTimeInterval

timeZone

yearOfCommonEra

Constructors

NSTimestamp

public NSTimestamp()

public NSTimestamp(java.sql.Timestamp date)

public NSTimestamp(java.util.Date date)

public NSTimestamp(long milliseconds)

public NSTimestamp( long milliseconds, java.util.TimeZone timezone)

public NSTimestamp( long milliseconds, int nanoseconds)

public NSTimestamp( long milliseconds, int nanoseconds, java.util.TimeZone timezone)

public NSTimestamp( long milliseconds, NSTimestamp timestamp)

public NSTimestamp( int year, int month, int day, int hours, int minutes, int seconds, java.util.TimeZone timezone)

Creates an NSTimestamp object representing the specified year, month, day, hours, minutes, and seconds in the specified time zone.

Static Methods

currentTimeIntervalSinceReferenceDate

public static long currentTimeIntervalSinceReferenceDate()

Returns the number of milliseconds between the system's absolute reference date (the first instant of 1 January 1970, GMT) and the current date and time.

decodeObject

public static Object decodeObject(NSCoder coder)

See Also: NSCoding

distantFuture

public static NSTimestamp distantFuture()

Creates and returns an NSTimestamp that represents a date many centuries in the future. You can pass this value where an NSTimestamp is required to have the date argument essentially ignored. For example, the NSLock method tryLock(NSTimeStamp) returns false if the receiver fails to acquire the lock before the specified date. You can use the object returned by distantFuture as the date argument to wait indefinitely to acquire the lock.

distantPast

public static NSTimestamp distantPast()

Creates and returns an NSTimestamp that represents a date many centuries in the past. You can use this object in your code as a control date, a guaranteed temporal boundary.

millisecondsToTimeInterval

public static long millisecondsToTimeInterval(long milliseconds)

Returns the time interval in seconds corresponding to the specified time represented in milliseconds. Any fractional part of a second is truncated.

timeIntervalToMilliseconds

public static long timeIntervalToMilliseconds(long timeInterval)

Returns a time interval in milliseconds corresponding to the specified time interval represented in seconds.

Instance Methods

classForCoder

public Class classForCoder()

compare

public int compare(NSTimestamp timestamp)

dayOfCommonEra

public int dayOfCommonEra()

Returns the number of days since the beginning of the Common Era. The base year of the Common Era is 1 C.E. (which is the same as 1 A.D.).

dayOfMonth

public int dayOfMonth()

Returns a number that indicates the day of the month (1 through 31) of the receiver.

dayOfWeek

public int dayOfWeek()

Returns a number that indicates the day of the week (0 through 6) of the receiver; 0 indicates Sunday.

dayOfYear

public int dayOfYear()

Returns a number that indicates the day of the year (1 through 366) of the receiver.

earlierTimestamp

public NSTimestamp earlierTimestamp(NSTimestamp timestamp)

Returns the receiver or timestamp, whichever is earlier.

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

gregorianUnitsSinceTimestamp

public void gregorianUnitsSinceTimestamp( NSTimestamp.IntRef years, NSTimestamp.IntRef months, NSTimestamp.IntRef days, NSTimestamp.IntRef hours, NSTimestamp.IntRef minutes, NSTimestamp.IntRef seconds, NSTimestamp timestamp)

Computes the time difference in calendar units between the receiver and timestamp and returns it in years, months, days, hours, minutes, and seconds. NSTimestamp.IntRef is a local class that contains a single element: the integer value.

You can choose any representation you wish for the time difference by passing null for the arguments you want to ignore. For example, the following code fragment computes the difference in months, days, and years between two dates:

NSTimestamp momsBDay = 
    new NSTimestamp(1936, 1, 8, 7, 30, 0, java.util.TimeZone.getTimeZone("EST"));
NSTimestamp dateOfBirth = 
    new NSTimestamp(1965, 12, 7, 17, 25, 0, new NSTimeZone("EST"));

NSTimestamp.IntRef years = new NSTimestamp.IntRef();
NSTimestamp.IntRef months = new NSTimestamp.IntRef();
NSTimestamp.IntRef days = new NSTimestamp.IntRef();

dateOfBirth.gregorianUnitsSinceTimestamp(momsBDay, years, months, days, 
    null, null, null)

This message returns 29 years, 10 months, and 29 days. If you want to express the years in terms of months, you pass null for the years argument:

dateOfBirth.gregorianUnitsSinceTimestamp(momsBDay, null, months, days,      null, null, null);

This message returns 358 months and 29 days.

hourOfDay

public int hourOfDay()

Returns the hour value (0 through 23) of the receiver. On Daylight Savings "fall back" days, a value of 1 is returned for two consecutive hours, but with a different time zone (the first in daylight savings time and the second in standard time).

laterTimestamp

public NSTimestamp laterTimestamp(NSTimestamp timestamp)

Returns the receiver or timestamp, whichever is later.

microsecondOfSecond

public int microsecondOfSecond()

Returns the microseconds value (0 through 999,999) of the receiver.

minuteOfHour

public int minuteOfHour()

Returns the minutes value (0 through 59) of the receiver.

monthOfYear

public int monthOfYear()

Returns a number that indicates the month of the year (1 through 12) of the receiver.

secondOfMinute

public int secondOfMinute()

Returns the seconds value (0 through 59) of the receiver. See the "Class Description" (page 283) for NSTimestamp for an alternative.

setDate

public void setDate(int date)

setHours

public void setHours(int hours)

setMinutes

public void setMinutes(int minutes)

setMonth

public void setMonth(int month)

setNanos

public void setNanos(int nanoseconds)

setSeconds

public void setSeconds(int seconds)

setTime

public void setTime(long milliseconds)

setYear

public void setYear(int year)

timeIntervalSinceNow

public long timeIntervalSinceNow()

Returns the number of milliseconds between the receiver's time and the current system time. This value is negative if the receiver's time is earlier than the current system time.

timeIntervalSinceReferenceDate

public long timeIntervalSinceReferenceDate()

Returns the number of milliseconds between the receiver's time and the reference date (January 1, 1970, 00:00 GMT). This value is negative if the receiver's time is earlier than the reference date.

timeIntervalSinceTimestamp

public long timeIntervalSinceTimestamp(NSTimestamp time)

Returns the number of milliseconds between the receiver's time and time. This value is negative if the receiver's time is earlier than time.

timestampByAddingGregorianUnits

public NSTimestamp timestampByAddingGregorianUnits( int year, int month, int day, int hour, int minute, int second)

Returns an NSTimestamp that is updated with the year, month, day, hour, minute, and second offsets specified as arguments. The offsets can be positive (future) or negative (past). This method preserves "clock time" across changes in Daylight Savings Time zones and leap years. For example, adding one month to an NSTimestamp with a time of 12 noon correctly maintains time at 12 noon.

The following code fragment shows an NSTimestamp created with a date a week later than an existing NSTimestamp.

NSTimestamp now = new NSTimestamp();
NSTimestamp nextWeek = 
    now.timestampByAddingGregorianUnits(0, 0, 7, 0, 0, 0);

timestampByAddingTimeInterval

public NSTimestamp timestampByAddingTimeInterval(long timeInterval)

Returns an NSTimestamp with the specified time interval in milliseconds added to the receiver's time.

timeZone

public java.util.TimeZone timeZone()

Returns the time zone object associated with the receiver. You can explicitly set the time zone to an java.util.TimeZone object using a constructor that takes an java.util.TimeZone object as an argument. If you do not specify a time zone for an object at initialization time, NSTimestamp uses the default time zone for the locale.

toString

public String toString()

yearOfCommonEra

public int yearOfCommonEra()

Returns a number that indicates the year, including the century, of the receiver (for example, 1995). The base year of the Common Era is 1 C.E. (which is the same as 1 A.D).

© 2001 Apple Computer, Inc. (Last Published April 17, 2001)