| PATH |
- Inherits from:
- java.sql.Timestamp : java.util.Date : Object
- Implements:
- NSCoding
- Package:
- com.webobjects.foundation
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.
| Class | Description |
| NSTimestamp | Represents an instance in time |
| java.util.GregorianCalendar | Represents a calendar date |
| NSTimeZone | Represents a time zone |
| NSTimestampFormatter | Converts NSTimestamps to strings and vice versa. |
See the Sun's documentation for the java.util.GregorianCalendar class for more information about using calendars in Java.
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.
NSTimestamp provides the following constants.
- NSCoding
- classForCoder
- decodeObject
- encodeWithCoder
- 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
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.
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.
public static Object decodeObject(NSCoder coder)
See Also: NSCoding
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.
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.
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.
public static long timeIntervalToMilliseconds(long timeInterval)
Returns a time interval in milliseconds corresponding to the specified time interval represented in seconds.
public Class classForCoder()
public int compare(NSTimestamp timestamp)
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.).
public int dayOfMonth()
Returns a number that indicates the day of the month (1 through 31) of the receiver.
public int dayOfWeek()
Returns a number that indicates the day of the week (0 through 6) of the receiver; 0 indicates Sunday.
public int dayOfYear()
Returns a number that indicates the day of the year (1 through 366) of the receiver.
public NSTimestamp earlierTimestamp(NSTimestamp timestamp)
Returns the receiver or timestamp, whichever is earlier.
public void encodeWithCoder(NSCoder coder)
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.
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).
public NSTimestamp laterTimestamp(NSTimestamp timestamp)
Returns the receiver or timestamp, whichever is later.
public int microsecondOfSecond()
Returns the microseconds value (0 through 999,999) of the receiver.
public int minuteOfHour()
Returns the minutes value (0 through 59) of the receiver.
public int monthOfYear()
Returns a number that indicates the month of the year (1 through 12) of the receiver.
public int secondOfMinute()
Returns the seconds value (0 through 59) of the receiver. See the "Class Description" (page 283) for NSTimestamp for an alternative.
public void setDate(int date)
public void setHours(int hours)
public void setMinutes(int minutes)
public void setMonth(int month)
public void setNanos(int nanoseconds)
public void setSeconds(int seconds)
public void setTime(long milliseconds)
public void setYear(int year)
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.
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.
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.
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);
public NSTimestamp timestampByAddingTimeInterval(long timeInterval)
Returns an NSTimestamp with the specified time interval in milliseconds added to the receiver's time.
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.
public String toString()
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)