com.hunnysoft.jmime.Node
com.hunnysoft.jmime.FieldBody
com.hunnysoft.jmime.DateTime
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
Class that represents an RFC 2822 date-time.
DateTime represents an Internet date-time
string as described in RFC 2822.
The parse operation for DateTime parses the string
representation to extract the year, month, day, hour, minute, second,
and time zone. DateTime provides methods to set or get the
individual elements of the date-time.
The use of DateTime is best explained by considering
the following use cases.
DateTime parses Internet date-time strings. When a
MIME message is received, perhaps from a remote source, you may call the
inherited method Node.setString(com.hunnysoft.jmime.ByteString), or the DateTime(ByteString) constructor, to set the string representation of
the DateTime object. Then call the parse()
method to parse the string representation. Finally, call the accessor
methods year(), month(), and so on, to
access the parsed elements of the date-time string.
DateTime generates Internet date-time strings. Use
the default constructor to create a new DateTime object
with a null date-time. Call one of the methods setValuesLocal(int, int, int, int, int, int)
or setValuesLiteral(int, int, int, int, int, int, int) to set the year, month, day, hour,
minute, second, and zone with the desired values. Alternatively, you
can set the values for the date-time from a system time, using the
fromSystemTime(long, boolean) method. Then call the assemble()
method to create the string representation. Finally, call the inherited
method Node.string() to get the string representation.
DateTime converts to and from a scalar date and
time. Call the fromSystemTime(long, boolean) method or the
asSystemTime() method to convert from or to a "system
time," defined as the number of milliseconds elapsed since
1 Jan 1970 00:00:00 UTC. The system time is used by the
standard Java library; for example, it is returned by the method
System.currentTimeMillis(). By converting to a scalar
representation of the date and time, Hunny JMIME makes it easy for you
to compare two different dates.
Note: It is possible that DateTime will encounter an
error while parsing a date-time string. When this happens, throwing an
exception is not a wise way to proceed, since in most cases higher level
operations would also have to terminate before the library user's code
could deal with the exception. What actually happens, is that
DateTime "recovers" from the error by setting the date and
time to 1 Jan 1970 00:00:00 UTC. To easily check whether a
parse operation completed successfully, you can call
asSystemTime() and examine the return value. A value of
zero indicates that the parsing operation failed; any other value
indicates it succeeded.
| Field Summary |
| Fields inherited from class com.hunnysoft.jmime.FieldBody |
mText |
| Fields inherited from class com.hunnysoft.jmime.Node |
mIsModified, mParent, mString |
| Constructor Summary | |
DateTime()
Default constructor. |
|
DateTime(ByteString bstr)
Constructor that takes an initial byte string argument. |
|
DateTime(DateTime other)
Copy constructor. |
|
| Method Summary | |
void |
assemble()
Assembles the string representation. |
long |
asSystemTime()
Gets the date and time as a system time. |
java.lang.Object |
clone()
Creates a copy of this object. |
int |
day()
Gets the day of the month. |
int |
dayOfTheWeek()
Gets the day of the week. |
void |
fromSystemTime(long time,
boolean convertToLocal)
Sets the date and time from a system time. |
int |
hour()
Gets the hour. |
int |
minute()
Gets the minute. |
int |
month()
Gets the month. |
void |
parse()
Parses the string representation. |
int |
second()
Gets the second. |
void |
setValuesLiteral(int year,
int month,
int day,
int hour,
int minute,
int second,
int zoneOffset)
Sets the date-time value as specified. |
void |
setValuesLocal(int year,
int month,
int day,
int hour,
int minute,
int second)
Sets the date-time value as specified, assuming local time. |
int |
year()
Gets the year. |
int |
zone()
Gets the zone. |
| Methods inherited from class com.hunnysoft.jmime.FieldBody |
fold, isFoldingEnabled, maybeFold, setFoldingEnabled, setText, text, unfold |
| Methods inherited from class com.hunnysoft.jmime.Node |
_setString, isModified, parent, setModified, setParent, setString, string, toString |
| Methods inherited from class java.lang.Object |
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Constructor Detail |
public DateTime()
This constructor sets the DateTime object's string
representation to the empty string and sets its parent node to
null. The date-time value is set to the null
value, defined as the date 1 Jan 1970 00:00:00 UTC.
public DateTime(DateTime other)
This constructor performs a deep copy of its argument. The
parent node of the new DateTime object is set to
null.
other - DateTime instance to copypublic DateTime(ByteString bstr)
This constructor sets the DateTime object's string
representation to bstr and sets its parent node to
null. The date-time value is set to the null
value, defined as the date 1 Jan 1970 00:00:00 UTC.
Normally, you call the parse() method immediately
after this constructor to parse the date and time information from
the string representation.
bstr - initial value for the string representation| Method Detail |
public java.lang.Object clone()
This method, inherited from Object, creates a new
DateTime object that has the same value as this
DateTime object. The parent node of the new
DateTime object is set to null.
clone in class FieldBodypublic void parse()
This method, inherited from Node, executes the
parse operation for DateTime objects. The parse
operation creates or updates the broken-down representation from the
string representation. For DateTime objects, the parse
method parses the string representation to get the values of the
year, month, day, hour, minute, second, and time zone.
You should call this method after you set or modify the string representation, and before you retrieve the year, month, day, hour, minute second, and zone.
This method clears the is-modified flag.
parse in class FieldBodypublic void assemble()
This method, inherited from Node, executes the assemble
operation for DateTime objects. The assemble operation
creates or updates the string representation from the broken-down
representation. For DateTime objects, the assemble
operation builds the string representation from the year, month,
day, hour, minute, second, and zone.
You should call this method after you set or modify the year, month, day, hour, minute, second, or zone, and before you retrieve the string representation.
This method clears the is-modified flag.
assemble in class FieldBodypublic long asSystemTime()
The system time is defined as the number of milliseconds elapsed
since 1 Jan 1970 00:00:00 UTC. This is the same date and
time representation that is returned by the
System.currentTimeMillis() method in the Java
library.
public void fromSystemTime(long time,
boolean convertToLocal)
The system time is defined as the number of milliseconds elapsed
since 1 Jan 1970 00:00:00 UTC. This is the same date and
time representation that is returned by the
System.currentTimeMillis() method in the Java
library.
If convertToLocal is true, then the DateTime
object creates the internal representation in local time; otherwise,
it creates the internal representation in UTC time.
time - a scalar time value, indicating the number of
milliseconds elapsed since 1 Jan 1970 00:00:00 UTCconvertToLocal - if true, the internal representation will be
in local time; if false, the internal representation will be in UTC
public void setValuesLocal(int year,
int month,
int day,
int hour,
int minute,
int second)
Use this method to create the internal date-time representation in local time. Time zone information is obtained from the local system, based on the values specified.
Note that when the local system is set up to recognize daylight
time, there is an ambiguity during the overlap time period that
occurs when the local time clock is set back. During this overlap
period, it is impossible to determine whether the time zone offset
should be the standard zone offset or the daylight time zone offset.
This ambiguity is probably not a problem for most applications. If
it is a problem, then the work around is to use
setValuesLiteral(int, int, int, int, int, int, int) to specify the precise time zone
offset.
year - four digit year (e.g. 2001)month - month (1 <= month <= 12)day - day of month (1 <= day <= 31)hour - hour (0 <= hour <= 23)minute - minute (0 <= minute <= 59)second - second (0 <= second <= 60)setValuesLiteral(int, int, int, int, int, int, int)
public void setValuesLiteral(int year,
int month,
int day,
int hour,
int minute,
int second,
int zoneOffset)
Use this method to create the internal date-time representation in any time zone. The values are used "as is" without any additional interpretation.
zoneOffset is the offset in minutes from Coordinated Universal Time (UTC). For example, the correct value for US Eastern Standard Time (e.g. New York City) is -300, since 12:00 UTC equals 7:00 EST, a difference of 300 minutes.
year - four digit year (e.g. 2001)month - month (1 <= month <= 12)day - day of month (1 <= day <= 31)hour - hour (0 <= hour <= 23)minute - minute (0 <= minute <= 59)second - second (0 <= second <= 60)zoneOffset - difference in minutes between local time and UTC
(-720 <= zoneOffset <= 720), e.g. zoneOffset=-300 for
US Eastern Standard Time (New York City)setValuesLocal(int, int, int, int, int, int)public int year()
public int month()
The month is in the range 1 <= month <= 12, with 1 = January.
public int day()
The day is in the range 1 <= day <= 31.
public int hour()
The hour is in the range 0 <= hour <= 23.
public int minute()
The minute is in the range 0 <= minute <= 59.
public int second()
In accordance with RFC 2822, the second is in the range 0 <= second <= 60.
public int zone()
The zone is in the range -720 <= zone <= 720, and represents the difference in minutes between local time and UTC. For example, for US Eastern Standard Time (New York City), the zone offset is -300.
public int dayOfTheWeek()
The returned value is in the range (0 <= dayOfWeek <= 6), with 0 = Sunday. This value is always computed from the other values. The day of the week is a read-only value that cannot be set.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||