superwaba.ext.xplat.util.datergf
Class DateTime

java.lang.Object
  |
  +--superwaba.ext.xplat.util.datergf.DateTime

public class DateTime
extends Object

DateTime implements a class consisting of a Date and Time.

This class has a Waba and a Java version, due to the following methods, which are implemented depending on the runtime environment:

Implemented?    
Java Waba Method name Short Description
yes yes public static void update(Object obj) Updates a DateTime object, a Date object or a Time object to the local time of the machine.


This version was created with Waba (e.g. http://www.SuperWaba.org) family of Java-compatible mobile systems (PDAs, Handies, etc.) in mind. Hence this package does not use threads or exceptions. The Waba version does not use the datatypes double and long.
(Though there are two methods in this class employing long, meant for running under virtual machines offering that datatype: toLong(int epoch) and valueOf(int epoch, long millis).) The original Waba as well as many other Java VMs for small devices do not support datatype long.

Some of the available operations are:


Examples:

      DateTime dt1, dt2;
      dt1=new DateTime(2001,1,1,0,0,0);      // yields: 2001-01-01 00:00:00
      dt2=new DateTime(2005,12,31,11,59,59); // yields: 2005-12-31 11:59:59

      float  diff1=dt2.subtract(dt1);           // yields: "1825.5" (1825 and 1/2 days)
      double diff2=dt2.subtractDouble(dt1);     // yields: "1825.499988436699"

                     // if running under Waba yields actual date and time:
      dt2.update();
      diff1=dt2.subtract(dt1);       // yields: number of days and time since the
                                     //         beginning of the new millenium
 
 Temporary dev-infos:

    version  date            remark

    0.91.0   2003-04-07      - rgf; changed equals() to match the signature of Object.equals();
                               documents explicitly that the interface Comparable is implemented in this class

    0.9.2    2001-03-21      - catering for changes in TimeRGF
                             - deleted float/double subtract(), and their add()-counterparts
                             - new subtract (and add()) working on a two-element int-array) under
                               Waba exact to the millisecond (now using int only)!
                             - corrected a bug with toLong()

                             - added the Serializable interface; Date(), Time() have
                               in addition readObject() and writeObject() implemented

             2001-04-02      - introduced variant "JAVA" and "WABA"
 


Field Summary
 Date date
          Date field to store the date portion.
 Time time
          Time field to store the time portion.
 
Constructor Summary
DateTime()
          Creates a DateTime object set to "0001-01-01 00:00:00.000".
DateTime(Date date, Time time)
          Creates a DateTime object set to the arguments date and time.
DateTime(int year, int month, int day, int hour, int minute, int second)
          Creates a DateTime object set to the values from the arguments.
DateTime(int year, int month, int day, int hour, int minute, int second, int millis)
          Creates a DateTime object set to the values from the arguments.
 
Method Summary
 DateTime add(int days, int millis)
          Adds the number of days to the date field and the number of milliseconds to the time field of this DateTime object.
 DateTime assign(DateTime otherDateTime)
          Assigns otherDateTime to this DateTime.
 int compareTo(Object otherDateTime)
           
 Object copy()
          Implements the "Clonable" interface.
 boolean equals(Object otherDateTime)
          Implements the "Comparator.equals(Object obj)" interface.
 int[] subtract(DateTime other)
          Subtracts a DateTime object from this one.
 int toInt(int epoch)
          Renders the DateTime object into an int, encoded as seconds since/until the given epoch.
 long toLong(int epoch)
          Renders the DateTime object into a long, encoded as milliseconds since/until the given epoch.
 String toString()
          Render the DateTime object to a string.
 DateTime update()
          Updates the DateTime object to the actual local date and time of the machine.
static DateTime valueOf(int epoch, int unsigned_seconds)
          Creates a DateTime from the unsigned int relative to the given epoch.
static DateTime valueOf(int epoch, long millis)
          Creates a DateTime object from the number of milliseconds since/to the given epoch.
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, wait, wait
 

Field Detail

date

public Date date
Date field to store the date portion.

time

public Time time
Time field to store the time portion.
Constructor Detail

DateTime

public DateTime()
Creates a DateTime object set to "0001-01-01 00:00:00.000".

DateTime

public DateTime(Date date,
                Time time)
Creates a DateTime object set to the arguments date and time.

DateTime

public DateTime(int year,
                int month,
                int day,
                int hour,
                int minute,
                int second)
Creates a DateTime object set to the values from the arguments.
Parameters:
year - a value between 1 and 9999.
month - a value between 1 and 12.
day - a value between 1 and the maximum number of days of the appropriate month.
hour - a value between 0 and 23.
minute - a value between 0 and 59.
second - a value between 0 and 59.

DateTime

public DateTime(int year,
                int month,
                int day,
                int hour,
                int minute,
                int second,
                int millis)
Creates a DateTime object set to the values from the arguments.
Parameters:
year - a value between 1 and 9999.
month - a value between 1 and 12.
day - a value between 1 and the maximum number of days of the appropriate month.
hour - a value between 0 and 23.
minute - a value between 0 and 59.
second - a value between 0 and 59.
millis - a value between 0 and 999.
Method Detail

add

public DateTime add(int days,
                    int millis)
Adds the number of days to the date field and the number of milliseconds to the time field of this DateTime object.

Works on any Java-VM, even ones with no implementations of the long or double datatype, like some for for PDAs (like the classic Waba); therefore there may be rounding errors, if the integer part (representing whole days) is too large.

                             // create a DateTime object with a
                             // value of: "2010-01-12 14:05:47.123"
      DateTime dt=new DateTime(2010,01,12,14,05,47,123);

      dt.add(1, 64800000);    // add 1 3/4 days == 1 day, 18 hours (= 64800000 millis)
                             // "dt" now: "2010-01-14 08:05:47.123"
 
Parameters:
days - number of days to add to DateTime.
millis - number of milliseconds to add to DateTime.

subtract

public int[] subtract(DateTime other)
Subtracts a DateTime object from this one.

Works on any Java-VM, even ones with no implementations of the double datatype, like some for for PDAs (like the classic Waba); therefore there may be rounding errors, if the integer part (representing whole days) is too large.

Example:

                             // create a DateTime object with a
                             // value of: "2010-01-12 14:05:47"
      DateTime dt1=new DateTime(2010,01,12,14,05,47);

                             // create a DateTime object with a
                             // value of: "2010-01-14 08:05:47"
      DateTime dt2=new DateTime(2010,01,14,8,05,47);

      int []      diff=dt2.subtract(dt1);    // yields: {1, 64800000};

 
Parameters:
other - the DateTime object to subtract.
Returns:
an int array with two elements
  • at index '0': the difference in number of days,
  • at index '1': the difference in milliseconds.

assign

public DateTime assign(DateTime otherDateTime)
Assigns otherDateTime to this DateTime.

compareTo

public int compareTo(Object otherDateTime)
Parameters:
otherDateTime - a DateTime
Returns:
-1 if this DateTime is earlier (smaller) than otherDateTime, 0 if both times are equal, +1 if this DateTime is later (greater) than otherDateTime

copy

public Object copy()
Implements the "Clonable" interface.
Returns:
a newly created DateTime object with all fields set to this DateTime object.

equals

public boolean equals(Object otherDateTime)
Implements the "Comparator.equals(Object obj)" interface.
Overrides:
equals in class Object
Parameters:
otherDateTime - a DateTime
Returns:
true if DateTimes are equal (have both the same value in the fields date and time), false else.

toString

public String toString()
Render the DateTime object to a string.
Overrides:
toString in class Object

toLong

public long toLong(int epoch)
Renders the DateTime object into a long, encoded as milliseconds since/until the given epoch. The 'epoch' is the basedate (at midnight) used to calculate the number of seconds from/to this DateTime object.

Does not Work on Java-VMs with no implementation of the long datatype (e.g. early versions of Waba for PDAs).

Remark: If your system is using seconds, then you need to mulitply the second value by 1000 in order to arrive at the needed millisecond value.

      DateTime dt=new DateTime(2010,1,12, 14,5,47);
                     // "dt" is now: "2010-01-12 14:05:47"

      long secs_long=dt.toLong(DTC.EPOCH_PALM);
                     // "secs_long" is now: "3.346.149.947" seconds
                     //                     since Date.EPOCH_PALM
 
Parameters:
epoch - one of: DTC.EPOCH_MACINTOSH, DTC.EPOCH_PALM, DTC.EPOCH_JAVA, DTC.EPOCH_DOS, DTC.EPOCH_WIN32, DTC.EPOCH_MJD.

It is possible to use an integer encoded date (a positive number in the form of: year*10000+month*100+day) as the epoch. In such a case that date (starting at midnight) is used as the epoch. If an illegal epoch is given, the default epoch of Date.getDefaultEpochDate() is used.


valueOf

public static DateTime valueOf(int epoch,
                               long millis)
Creates a DateTime object from the number of milliseconds since/to the given epoch.

Does not Work on Java-VMs with no implementation of the long datatype (e.g. early versions of Waba for PDAs).

Remark: If your system is using seconds, then you need to mulitply the second value by 1000 in order to arrive at the needed millisecond value.

                     // 3.346.149.947 seconds since Date.EPOCH_PALM,
                     // which is exactly: "2010-01-12 14:05:47"
      long secs_long=3346149947l;

      DateTime dt=valueOf(DTC.EPOCH_PALM, secs_long);
                     // "dt" is now: "2010-01-12 14:05:47"

 
Parameters:
epoch - one of: DTC.EPOCH_MACINTOSH, DTC.EPOCH_PALM, DTC.EPOCH_JAVA, DTC.EPOCH_DOS, DTC.EPOCH_WIN32, DTC.EPOCH_MJD. If an illegal epoch is given, the default epoch of Date.getDefaultEpochDate() is used.
millis - number of milliseconds since/to the epoch date (midnight).

toInt

public int toInt(int epoch)
Renders the DateTime object into an int, encoded as seconds since/until the given epoch. The 'epoch' is the basedate used to calculate the number of seconds from/to this DateTime object.

Use this returned unsigned int as a parameter for valueOf(int unsigned_int, int epoch).

Remark: An int - if regarded as an unsigned int - can store at most 49710 days and 23295 secs (or a value range between 0 and 4.294.967.295). Therefore, one can only cover the date/time-range between the epoch date (midnight) and a little bit more than 135 years after it. E.g. for the DTC.EPOCH_PALM the maximum date/time value storable is exactly: '2040-02-06 06:28:15' (an unsigned integer with all bits set is represented as -1 if interpreted as a signed integer).

This was written to support the Palm operating system which uses an unsigned int representing the seconds elapsed since its epoch (1904-01-01, midnight), cf. DTC.EPOCH_PALM.

           // create "dt" and set it to: "2010-01-12 14:05:47"
      DateTime dt=new DateTime(2010,1,12, 14,5,47);

      int secs_int=dt.toInt(DTC.EPOCH_PALM);
           // "secs_int" is now: "-948.817.349", which is equivelant to
           // an unsigned int with a value of '3.346.149.947'
           // (seconds elapsed since Date.EPOCH_PALM)
 
Parameters:
epoch - one of: DTC.EPOCH_MACINTOSH, DTC.EPOCH_PALM, DTC.EPOCH_JAVA, DTC.EPOCH_DOS, DTC.EPOCH_WIN32, DTC.EPOCH_MJD.

It is possible to use an integer encoded date (a positive number in the form of: year*10000+month*100+day) as the epoch. In such a case that date (starting at midnight) is used as the epoch. If an illegal epoch is given, the default epoch of Date.getDefaultEpochDate() is used.

Returns:
an (unsigned!) int representing the seconds to add to the epoch in order to arrive at this DateTime; if this DateTime is before the epoch or after epoch+49710days+23295secs then 0 is returned.

valueOf

public static DateTime valueOf(int epoch,
                               int unsigned_seconds)
Creates a DateTime from the unsigned int relative to the given epoch.

This was written to support the Palm operating system which uses an unsigned int representing the seconds elapsed since its epoch (1904-01-01, midnight), cf. DTC.EPOCH_PALM.

The algorithm uses (signed) int only, such that this method can be used on Java-bytecode systems, which do not support long (or double), e.g. PDA's.

                     // The date and time "2010-01-12 14:05:47" lies
                     // 3.346.149.947 seconds after Date.EPOCH_PALM;
                     // if stored as an 'unsigned int' but referred to as
                     // a 'signed int', one needs to use the value
                     // '-948.817.349' in order to set the appropriate
                     // bits.
      int secs_int=-948817349;

      DateTime dt=valueOf(DTC.EPOCH_PALM, secs_int);
                     // "dt" is now: "2010-01-12 14:05:47"
 
Parameters:
epoch - one of: DTC.EPOCH_MACINTOSH, DTC.EPOCH_PALM, DTC.EPOCH_JAVA, DTC.EPOCH_DOS, DTC.EPOCH_WIN32, DTC.EPOCH_MJD.
unsigned_seconds - an int which gets interpreted as an unsigned int (cf. toInt(int epoch)).

It is possible to use an integer encoded date (a positive number in the form of: year*10000+month*100+day) as the epoch. In such a case that date (starting at midnight) is used as the epoch. If an illegal epoch is given, the default epoch of Date.getDefaultEpochDate() is used.

Returns:
a DateTime object set according to the given epoch.

update

public DateTime update()
Updates the DateTime object to the actual local date and time of the machine. This method guarantees, that for both, the Date and the Time object the same timestamp is used. Otherwise it is thinkable, that while the Time object is updated the day rolls over and the update of the DateRGF object reflects a different day (and vice versa).

Examples:

     DateTime dt=new DateTime();     // yields: '0001-01-01 00:00:00.000'

           // if run on "2010-09-22" at "17:49:01.987", then
     dt.update();  // yields: '2010-09-22 17:49:01.987'