Package org.ggf.drmaa

Class PartialTimestamp

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<java.util.Calendar>

    public class PartialTimestamp
    extends java.util.Calendar
    The PartialTimestamp is a subclass of java.util.Calendar that allows for a partially specified time that is resolved to the soonest matching time that is in the future at the time of resolution. That is to say that if one creates a PartialTimestamp instance and sets the hour to 10am and the minute to 0, and one resolves the time, i.e. PartialTimestamp.getTime(), at 11:01am on November 24th, the PartialTimestamp will resolve to 10:00am on November 25th, as that time is the soonest time which matches the specified fields and is in the future. If one later resolves that same PartialTimestamp instance at 9:34am on December 1st, it will resolve to 10:00am on December 1st.

    There are only two ways to resolve the time: getTime() and getTimeInMillis(). All other means of accessing field values will return unresolved values. If the PartialTimestamp class is unable to resolve a field because of other unset fields, it will simply leave the field unresolved. For example, if the DAY_OF_MONTH is set to 42, and the MONTH is unset, the DAY_OF_MONTH will remain as 42. If later the MONTH is set, the DAY_OF_MONTH may be resolved to an in-range value. ("May," because if the MONTH is FEBRUARY, the YEAR and CENTURY are also needed to be able to resolve the DAY_OF_MONTH.)

    Whereever possible and sensible, the PartialTimestamp class mimics the functionality of the GregorianCalendar class.

    Since the PartialTimestamp only supports dates within the epoch, the ERA field is always AD, and hence is not used. The DRMAA specification, requires that the year be handled as two separate fields, one for the first n-2 digits (century) and one for the last two digits. Because of the symantics of extending the Calendar class, the CENTURY field is just an alias for the ERA field, and the ERA contains the century data. When using the PartialTimestmap class, the ERA field should not be used.

    When rolling a date field, if the PartialTimestamp doesn't have enough information to determine the field's valid value range, e.g. when rolling the DAY_OF_MONTH while MONTH is unset, an assumption will be made. The assumptions a PartialTimestamp instance may make are: a year is 365 days or 53 weeks, and a month is 31 days or 5 weeks.

    The PartialTimestamp class adds the idea of field modifiers to the Calendar class. Field modifiers are accessed via the setModifier() and getModifier() methods. A modifier represents a number that will be added to the value of the field. This is useful because in a PartialTimestamp instance, it may necessary to add to an unset field, for example to indicate the concept of "tomorrow." If an add() method or out of range set() method attempts to modify an unset field, the resulting modifier will be stored as the modifier for that field. For example, if the MONTH is set to DECEMBER, and the YEAR is unset, and 1 is added to the MONTH, the result will be that the MONTH is set to JANUARY, the year is still unset, and the YEAR modifier is set to 1. If later the YEAR is set to 97, the modifier will be applied, resulting in a year of 98. To avoid unwanted modifiers, use the roll() method instead of the add() method.

    The roll() method in the PartialTimestamp class is very simple. It does not take into account Daylight Savings Time or other complications, as does the roll() method of the GregorianCalendar.

    Example:

    public static void main (String[] args) {
       SessionFactory factory = SessionFactory.getFactory ();
       Session session = factory.getSession ();
    
       try {
          session.init (null);
          JobTemplate jt = session.createJobTemplate ();
          jt.setRemoteCommand ("sleeper.sh");
          jt.setArgs (new String[] {"5"});
    
          PartialTimestamp date = new PartialTimestamp ();
    
          // Run the job on the first of the month at 11:30
          date.set (PartialTimestamp.DATE, 1);
          date.set (PartialTimestamp.HOUR_OF_DAY, 11);
          date.set (PartialTimestamp.MINUTE, 30);
    
          jt.setStartTime (date);
    
          String id = session.runJob (jt);
    
          session.deleteJobTemplate (jt);
          session.exit ();
       }
       catch (DrmaaException e) {
          System.out.println ("Error: " + e.getMessage ());
       }
     }
     
    Since:
    0.5
    Version:
    1.0
    See Also:
    Serialized Form
    • Nested Class Summary

      • Nested classes/interfaces inherited from class java.util.Calendar

        java.util.Calendar.Builder
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int CENTURY
      CENTURY is a field required by the DRMAA timestamp.
      static int UNSET
      UNSET is the value assigned to fields which have not yet been set.
      • Fields inherited from class java.util.Calendar

        ALL_STYLES, AM, AM_PM, APRIL, AUGUST, DATE, DAY_OF_MONTH, DAY_OF_WEEK, DAY_OF_WEEK_IN_MONTH, DAY_OF_YEAR, DECEMBER, DST_OFFSET, ERA, FEBRUARY, FIELD_COUNT, FRIDAY, HOUR, HOUR_OF_DAY, JANUARY, JULY, JUNE, LONG, LONG_FORMAT, LONG_STANDALONE, MARCH, MAY, MILLISECOND, MINUTE, MONDAY, MONTH, NARROW_FORMAT, NARROW_STANDALONE, NOVEMBER, OCTOBER, PM, SATURDAY, SECOND, SEPTEMBER, SHORT, SHORT_FORMAT, SHORT_STANDALONE, SUNDAY, THURSDAY, TUESDAY, UNDECIMBER, WEDNESDAY, WEEK_OF_MONTH, WEEK_OF_YEAR, YEAR, ZONE_OFFSET
    • Constructor Summary

      Constructors 
      Constructor Description
      PartialTimestamp()
      Constructs a default PartialTimestamp instance using the current time in the default time zone with the default locale.
      PartialTimestamp​(int hour, int minute, int second)
      Constructs a PartialTimestamp instance with the given date and time set for the default time zone with the default locale.
      PartialTimestamp​(int year, int month, int date, int hour, int minute)
      Constructs a PartialTimestamp instance with the given date and time set for the default time zone with the default locale.
      PartialTimestamp​(int year, int month, int date, int hour, int minute, int second)
      Constructs a PartialTimestamp instance with the given date and time set for the default time zone with the default locale.
      PartialTimestamp​(java.util.Locale aLocale)
      Constructs a PartialTimestamp instance based on the current time in the default time zone with the given locale.
      PartialTimestamp​(java.util.TimeZone zone)
      Constructs a PartialTimestamp instance based on the current time in the given time zone with the default locale.
      PartialTimestamp​(java.util.TimeZone zone, java.util.Locale aLocale)
      Constructs a PartialTimestamp instance based on the current time in the given time zone with the given locale.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(int field, int amount)
      Adds the given value to the given field.
      java.lang.Object clone()
      Makes a complete copy of this object.
      boolean equals​(java.lang.Object obj)
      Compares two PartialTimestamp objects.
      int get​(int field)
      Get the value of the given field.
      int getActualMaximum​(int field)
      Returns the actual maximum value for the field, based on the current field values.
      int getActualMinimum​(int field)
      Returns the actual minimum value for the field, based on the current field values.
      int getGreatestMinimum​(int field)
      Gets the greatest minimum value that the field may ever have.
      int getLeastMaximum​(int field)
      Gets the least maximum value that the field may ever have.
      int getMaximum​(int field)
      Gets the greatest maximum value that the field may ever have.
      int getMinimum​(int field)
      Gets the least minimum value that the field may ever have.
      int getModifier​(int field)
      Returns the value of the modifier for the given field.
      void roll​(int field, boolean up)
      This method naively rolls the value of the given field by 1, either up or down.
      void roll​(int field, int amount)
      This method naively rolls the value of the given field up by the given amount.
      void set​(int field, int value)
      Sets the value of the given field.
      void setModifier​(int field, int value)
      Sets the value of the modifier for the given field.
      • Methods inherited from class java.util.Calendar

        after, before, clear, clear, compareTo, getAvailableCalendarTypes, getAvailableLocales, getCalendarType, getDisplayName, getDisplayNames, getFirstDayOfWeek, getInstance, getInstance, getInstance, getInstance, getMinimalDaysInFirstWeek, getTime, getTimeInMillis, getTimeZone, getWeeksInWeekYear, getWeekYear, hashCode, isLenient, isSet, isWeekDateSupported, set, set, set, setFirstDayOfWeek, setLenient, setMinimalDaysInFirstWeek, setTime, setTimeInMillis, setTimeZone, setWeekDate, toInstant, toString
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • CENTURY

        public static final int CENTURY
        CENTURY is a field required by the DRMAA timestamp.
        See Also:
        Constant Field Values
      • UNSET

        public static final int UNSET
        UNSET is the value assigned to fields which have not yet been set.
        See Also:
        Constant Field Values
    • Constructor Detail

      • PartialTimestamp

        public PartialTimestamp()
        Constructs a default PartialTimestamp instance using the current time in the default time zone with the default locale.
      • PartialTimestamp

        public PartialTimestamp​(java.util.TimeZone zone)
        Constructs a PartialTimestamp instance based on the current time in the given time zone with the default locale.
        Parameters:
        zone - the given time zone.
      • PartialTimestamp

        public PartialTimestamp​(java.util.Locale aLocale)
        Constructs a PartialTimestamp instance based on the current time in the default time zone with the given locale.
        Parameters:
        aLocale - the given locale.
      • PartialTimestamp

        public PartialTimestamp​(java.util.TimeZone zone,
                                java.util.Locale aLocale)
        Constructs a PartialTimestamp instance based on the current time in the given time zone with the given locale.
        Parameters:
        zone - the given time zone.
        aLocale - the given locale.
      • PartialTimestamp

        public PartialTimestamp​(int year,
                                int month,
                                int date,
                                int hour,
                                int minute)
        Constructs a PartialTimestamp instance with the given date and time set for the default time zone with the default locale.
        Parameters:
        year - the value used to set the YEAR time field in the calendar.
        month - the value used to set the MONTH time field in the calendar. Month value is 0-based. e.g., 0 for January.
        date - the value used to set the DATE time field in the calendar.
        hour - the value used to set the HOUR_OF_DAY time field in the calendar.
        minute - the value used to set the MINUTE time field in the calendar.
      • PartialTimestamp

        public PartialTimestamp​(int hour,
                                int minute,
                                int second)
        Constructs a PartialTimestamp instance with the given date and time set for the default time zone with the default locale.
        Parameters:
        hour - the value used to set the HOUR_OF_DAY time field in the calendar.
        minute - the value used to set the MINUTE time field in the calendar.
        second - the value used to set the SECOND time field in the calendar.
      • PartialTimestamp

        public PartialTimestamp​(int year,
                                int month,
                                int date,
                                int hour,
                                int minute,
                                int second)
        Constructs a PartialTimestamp instance with the given date and time set for the default time zone with the default locale.
        Parameters:
        year - the value used to set the YEAR time field in the calendar.
        month - the value used to set the MONTH time field in the calendar. Month value is 0-based. e.g., 0 for January.
        date - the value used to set the DATE time field in the calendar.
        hour - the value used to set the HOUR_OF_DAY time field in the calendar.
        minute - the value used to set the MINUTE time field in the calendar.
        second - the value used to set the SECOND time field in the calendar.
    • Method Detail

      • getModifier

        public int getModifier​(int field)
        Returns the value of the modifier for the given field.
        Parameters:
        field - the field whose modifier will be returned
        Returns:
        the value of the field's modifier
      • setModifier

        public void setModifier​(int field,
                                int value)
        Sets the value of the modifier for the given field.
        Parameters:
        field - the field whose modifier will be set
        value - the value to which to set the field's modifier
      • add

        public void add​(int field,
                        int amount)
        Adds the given value to the given field. If the field is unset, the amount will be added to the field's modifier instead. If the field is set, but the addition causes changes to another field, which is unset, the unset field will receive the change as a modifier.
        Specified by:
        add in class java.util.Calendar
        Parameters:
        field - the field to which to add the amount
        amount - the amount to add
      • set

        public void set​(int field,
                        int value)
        Sets the value of the given field. After a call to set, the field is considered set. There is no way to unset a field that has been previously set. If the value is out of range for the field, it will be adjusted to be within range, if possible. If, because of other unset fields, there is not enough information to adjust the field, the field will remain as set.
        Overrides:
        set in class java.util.Calendar
        Parameters:
        field - the field to set
        value - the value to which to set the field
      • get

        public int get​(int field)
        Get the value of the given field. If the field is unset, this method will return UNSET.
        Overrides:
        get in class java.util.Calendar
        Parameters:
        field - which field's value to get
        Returns:
        The value of the field.
      • getGreatestMinimum

        public int getGreatestMinimum​(int field)
        Gets the greatest minimum value that the field may ever have.
        Specified by:
        getGreatestMinimum in class java.util.Calendar
        Parameters:
        field - the field of interest
        Returns:
        the greatest minimum value that the field may ever have
      • getLeastMaximum

        public int getLeastMaximum​(int field)
        Gets the least maximum value that the field may ever have.
        Specified by:
        getLeastMaximum in class java.util.Calendar
        Parameters:
        field - the field of interest
        Returns:
        the least maximum value that the field may ever have
      • getMaximum

        public int getMaximum​(int field)
        Gets the greatest maximum value that the field may ever have.
        Specified by:
        getMaximum in class java.util.Calendar
        Parameters:
        field - the field of interest
        Returns:
        the greatest maximum value that the field may ever have
      • getMinimum

        public int getMinimum​(int field)
        Gets the least minimum value that the field may ever have.
        Specified by:
        getMinimum in class java.util.Calendar
        Parameters:
        field - the field of interest
        Returns:
        the least minimum value that the field may ever have
      • roll

        public void roll​(int field,
                         boolean up)
        This method naively rolls the value of the given field by 1, either up or down. If the resulting value is out of range for the field, the value will roll over without affecting other fields.
        Specified by:
        roll in class java.util.Calendar
        Parameters:
        field - the field to roll
        up - whether to roll up
      • roll

        public void roll​(int field,
                         int amount)
        This method naively rolls the value of the given field up by the given amount. To roll down, use a negative amount. If the resulting value is out of range for the field, the value will roll over without affecting other fields.
        Overrides:
        roll in class java.util.Calendar
        Parameters:
        field - the field to roll
        amount - the amount to roll up
      • getActualMinimum

        public int getActualMinimum​(int field)
        Returns the actual minimum value for the field, based on the current field values.
        Overrides:
        getActualMinimum in class java.util.Calendar
        Parameters:
        field - the field of interest
        Returns:
        the actual minimum value for the field
      • getActualMaximum

        public int getActualMaximum​(int field)
        Returns the actual maximum value for the field, based on the current field values.
        Overrides:
        getActualMaximum in class java.util.Calendar
        Parameters:
        field - the field of interest
        Returns:
        the actual maximum value for the field
      • equals

        public boolean equals​(java.lang.Object obj)
        Compares two PartialTimestamp objects. They are equal if they both have all of the same field values and field modifier values.
        Overrides:
        equals in class java.util.Calendar
        Parameters:
        obj - the object against which to compare
        Returns:
        whether the given object equals this object
      • clone

        public java.lang.Object clone()
        Makes a complete copy of this object.
        Overrides:
        clone in class java.util.Calendar
        Returns:
        a complete copy of this object