Examples of hirondelle.date4j.DateTime$MissingItem

hirondelle.date4j.DateTime

st precision is nanosecond, not millisecond: DateTime dateAndTime = new DateTime("2010-01-19 23:59:59.123456789"); DateTime dateOnly = new DateTime("2010-01-19"); DateTime timeOnly = new DateTime("23:59:59"); DateTime dateOnly = DateTime.forDateOnly(2010,01,19); DateTime timeOnly = DateTime.forTimeOnly(23,59,59,0); DateTime dt = new DateTime("2010-01-15 13:59:15"); boolean leap = dt.isLeapYear(); //false dt.getNumDaysInMonth(); //31 dt.getStartOfMonth(); //2010-01-01, 00:00:00 dt.getEndOfDay(); //2010-01-15, 23:59:59 dt.format("YYYY-MM-DD"); //formats as '2010-01-15' dt.plusDays(30); //30 days after Jan 15 dt.numDaysFrom(someDate); //returns an int dueDate.lt(someDate); //less-than dueDate.lteq(someDate); //less-than-or-equal-to DateTime.now(aTimeZone); DateTime.today(aTimeZone); DateTime fromMilliseconds = DateTime.forInstant(31313121L, aTimeZone); birthday.isInFuture(aTimeZone);

Justification For This Class

The fundamental reasons why this class exists are :

to avoid the embarrassing number of distasteful inadequacies in the JDK's date classes
to oppose the very "mental model" of the JDK's date-time classes with something significantly simpler

There are 2 distinct mental models for date-times, and they don't play well together :

timeline - an instant on the timeline, as a physicist would picture it, representing the number of seconds from some epoch. In this picture, such a date-time can have many, many different representations according to calendar and time zone. That is, the date-time, as seen and understood by the end user, can change according to "who's looking at it". It's important to understand that a timeline instant, before being presented to the user, must always have an associated time zone - even in the case of a date only, with no time.
everyday - a date-time in the Gregorian calendar, such as '2009-05-25 18:25:00', which never changes according to "who's looking at it". Here, the time zone is always both implicit and immutable.

The problem is that java.util. {@link java.util.Date} uses only the timeline style, while most users, most of the time, think in terms of the other mental model - the 'everday' style. In particular, there are a large number of applications which experience problems with time zones, because the timeline model is used instead of the everday model. Such problems are often seen by end users as serious bugs, because telling people the wrong date or time is often a serious issue. These problems make you look stupid.

Date Classes in the JDK are Mediocre

The JDK's classes related to dates are widely regarded as frustrating to work with, for various reasons:

mistakes regarding time zones are very common
month indexes are 0-based, leading to off-by-one errors
difficulty of calculating simple time intervals
java.util.Date is mutable, but 'building block' classes should be immutable
numerous other minor nuisances

Joda Time Has Drawbacks As Well

The Joda Time library is used by some programmers as an alternative to the JDK classes. Joda Time has the following drawbacks :

it limits precision to milliseconds. Database timestamp values almost always have a precision of microseconds or even nanoseconds. This is a serious defect: a library should never truncate your data, for any reason.
it's large, with well over 100 items in its javadoc
in order to stay current, it needs to be manually updated occasionally with fresh time zone data
it has mutable versions of classes
it always coerces March 31 + 1 Month to April 30 (for example), without giving you any choice in the matter
some databases allow invalid date values such as '0000-00-00', but Joda Time doesn't seem to be able to handle them

Dates and Times in General

Civil Timekeeping Is Complex

Civil timekeeping is a byzantine hodge-podge of arcane and arbitrary rules. Consider the following :

months have varying numbers of days
one month (February) has a length which depends on the year
not all years have the same number of days
time zone rules spring forth arbitrarily from the fecund imaginations of legislators
summer hours mean that an hour is 'lost' in the spring, while another hour must repeat itself in the autumn, during the switch back to normal time
summer hour logic varies widely across various jurisdictions
the cutover from the Julian calendar to the Gregorian calendar happened at different times in different places, which causes a varying number of days to be 'lost' during the cutover
occasional insertion of leap seconds are used to ensure synchronization with the rotating Earth (whose speed of rotation is gradually slowing down, in an irregular way)
there is no year 0 (1 BC is followed by 1 AD), except in the reckoning used by astronomers

How Databases Treat Dates

Most databases model dates and times using the Gregorian Calendar in an aggressively simplified form, in which :

the Gregorian calendar is extended back in time as if it was in use previous to its inception (the 'proleptic' Gregorian calendar)
the transition between Julian and Gregorian calendars is entirely ignored
leap seconds are entirely ignored
summer hours are entirely ignored
often, even time zones are ignored, in the sense that the underlying database column doesn't usually explicitly store any time zone information.

The final point requires elaboration. Some may doubt its veracity, since they have seen date-time information "change time zone" when retrieved from a database. But this sort of change is usually applied using logic which is external to the data stored in the particular column.

For example, the following items might be used in the calculation of a time zone difference :

time zone setting for the client (or JDBC driver)
time zone setting for the client's connection to the database server
time zone setting of the database server
time zone setting of the host where the database server resides

(Note as well what's missing from the above list: your own application's logic, and the user's time zone preference.)

When an end user sees such changes to a date-time, all they will say to you is "Why did you change it? That's not what I entered" - and this is a completely valid question. Why did you change it? Because you're using the timeline model instead of the everyday model. Perhaps you're using a inappropriate abstraction for what the user really wants.

The Approach Used By This Class

This class takes the following design approach :

it models time in the "everyday" style, not in the "timeline" style (see above)
its precision matches the highest precision used by databases (nanosecond)
it uses only the proleptic Gregorian Calendar, over the years 1..9999
it ignores all non-linearities: summer-hours, leap seconds, and the cutover from Julian to Gregorian calendars
it ignores time zones. Most date-times are stored in columns whose type does not include time zone information (see note above).
it has (very basic) support for wonky dates, such as the magic value 0000-00-00 used by MySQL
it's immutable
it lets you choose among 4 policies for 'day overflow' conditions during calculations

Even though the above list may appear restrictive, it's very likely true that DateTime can handle the dates and times you're currently storing in your database.

Two Sets Of Operations

This class allows for 2 sets of operations: a few "basic" operations, and many "computational" ones.

Basic operations model the date-time as a simple, dumb String, with absolutely no parsing or substructure. This will always allow your application to reflect exactly what is in a ResultSet, with absolutely no modification for time zone, locale, or for anything else.

This is meant as a back-up, to ensure that your application will always be able to, at the very least, display a date-time exactly as it appears in your ResultSet from the database. This style is particularly useful for handling invalid dates such as 2009-00-00, which can in fact be stored by some databases (MySQL, for example). It can also be used to handle unusual items, such as MySQL's TIME datatype.

The basic operations are represented by {@link #DateTime(String)}, {@link #toString()}, and {@link #getRawDateString()}.

Computational operations allow for calculations and formatting. If a computational operation is performed by this class (for example, if the caller asks for the month), then any underlying date-time String must be parseable by this class into its components - year, month, day, and so on. Computational operations require such parsing, while the basic operations do not. Almost all methods in this class are categorized as computational operations.

Parsing DateTime - Accepted Formats

The {@link #DateTime(String)} constructor accepts a String representation of a date-time.The format of the String can take a number of forms. When retrieving date-times from a database, the majority of cases will have little problem in conforming to these formats. If necessary, your SQL statements can almost always use database formatting functions to generate a String whose format conforms to one of the many formats accepted by the {@link #DateTime(String)} constructor.

The {@link #isParseable(String)} method lets you explicitly test if a given String is in a form that can be parsed by this class.

Mini-Language for Formatting

This class defines a simple mini-language for formatting a DateTime, used by the various format methods.

The following table defines the symbols used by this mini-language, and the corresponding text they would generate given the date:

1958-04-09 Wednesday, 03:05:06.123456789 AM

in an English Locale. (Items related to date are in upper case, and items related to time are in lower case.)

Format	Output	Description	Needs Locale?
YYYY	1958	Year	...
YY	58	Year without century	...
M	4	Month 1..12	...
MM	04	Month 01..12	...
MMM	Apr	Month Jan..Dec	Yes
MMMM	April	Month January..December	Yes
DD	09	Day 01..31	...
D	9	Day 1..31	...
WWWW	Wednesday	Weekday Sunday..Saturday	Yes
WWW	Wed	Weekday Sun..Sat	Yes
hh	03	Hour 01..23	...
h	3	Hour 1..23	...
hh12	03	Hour 01..12	...
h12	3	Hour 1..12	...
a	AM	AM/PM Indicator	Yes
mm	05	Minutes 01..59	...
m	5	Minutes 1..59	...
ss	06	Seconds 01..59	...
s	6	Seconds 1..59	...
f	1	Fractional Seconds, 1 decimal	...
ff	12	Fractional Seconds, 2 decimals	...
fff	123	Fractional Seconds, 3 decimals	...
ffff	1234	Fractional Seconds, 4 decimals	...
fffff	12345	Fractional Seconds, 5 decimals	...
ffffff	123456	Fractional Seconds, 6 decimals	...
fffffff	1234567	Fractional Seconds, 7 decimals	...
ffffffff	12345678	Fractional Seconds, 8 decimals	...
fffffffff	123456789	Fractional Seconds, 9 decimals	...
\|	(no example)	Escape characters	...

As indicated above, some of these symbols can only be used with an accompanying Locale. In general, if the output is text, not a number, then a Locale will be needed. For example, 'September' is localizable text, while '09' is a numeric representation, which doesn't require a Locale. Thus, the symbol 'MM' can be used without a Locale, while 'MMMM' and 'MMM' both require a Locale, since they generate text, not a number.

The fractional seconds 'f' doesn't perform any rounding.

The escape character '|' allows you to insert arbitrary text. The escape character always appears in pairs; these pairs define a range of characters over which the text will not be interpreted using the special format symbols defined above.

Here are some practical examples of using the above formatting symbols:

Format	Output
YYYY-MM-DD hh:mm:ss.fffffffff a	1958-04-09 03:05:06.123456789 AM
YYYY-MM-DD hh:mm:ss.fff a	1958-04-09 03:05:06.123 AM
YYYY-MM-DD	1958-04-09
hh:mm:ss.fffffffff	03:05:06.123456789
hh:mm:ss	03:05:06
YYYY-M-D h:m:s	1958-4-9 3:5:6
WWWW, MMMM D, YYYY	Wednesday, April 9, 1958
WWWW, MMMM D, YYYY \|at\| D a	Wednesday, April 9, 1958 at 3 AM

In the last example, the escape characters are needed only because 'a', the formating symbol for am/pm, appears in the text.

Passing DateTime Objects to the Database

When a DateTime is passed as a parameter to an SQL statement, the DateTime can always be formatted into a String of a form accepted by the database, using one of the format methods.


    /**
     * What is the current date-time in the JRE's default time zone?
     */
    public static void currentDateTime () {
        DateTime now = DateTime.now( TimeZone.getDefault() );
        String result = now.format( "YYYY-MM-DD hh:mm:ss" );
        log( "Current date-time in default time zone : " + result );
    }

View Full Code Here


    /**
     * What is the current date-time in Cairo (include weekday)?
     */
    public static void currentDateTimeInCairo () {
        DateTime now = DateTime.now( TimeZone.getTimeZone( "Africa/Cairo" ) );
        String result = now.format( "YYYY-MM-DD hh:mm:ss (WWWW)", Locale.getDefault() );
        log( "Current date-time in Cairo : " + result );
    }

View Full Code Here


    /**
     * What's the age of someone born May 16, 1995?
     */
    public static void ageIfBornOnCertainDate () {
        DateTime today = DateTime.today( TimeZone.getDefault() );
        DateTime birthdate = DateTime.forDateOnly( 1995, 5, 16 );
        int age = today.getYear() - birthdate.getYear();
        if ( today.getDayOfYear() < birthdate.getDayOfYear() ) {
            age = age - 1;
        }
        log( "Age of someone born May 16, 1995 is : " + age );
    }

View Full Code Here


    /**
     * Stock options expire on the 3rd Friday of this month. What day of the month is that?
     */
    public static void optionsExpiry () {
        DateTime today = DateTime.today( TimeZone.getDefault() );
        DateTime firstOfMonth = today.getStartOfMonth();
        int result = 0;
        if ( firstOfMonth.getWeekDay() == 7 ) {
            result = 21;
        } else {
            result = 21 - firstOfMonth.getWeekDay();
        }
        DateTime thirdFriday = DateTime.forDateOnly( firstOfMonth.getYear(), firstOfMonth.getMonth(), result );
        log( "The 3rd Friday of this month is : " + thirdFriday.format( "YYYY-MM-DD" ) );
    }

View Full Code Here


    /**
     * How many days till the next December 25?
     */
    public static void daysTillChristmas () {
        DateTime today = DateTime.today( TimeZone.getDefault() );
        DateTime christmas = DateTime.forDateOnly( today.getYear(), 12, 25 );
        int result = 0;
        if ( today.isSameDayAs( christmas ) ) {
            // do nothing
        } else if ( today.lt( christmas ) ) {
            result = today.numDaysFrom( christmas );
        } else if ( today.gt( christmas ) ) {
            DateTime christmasNextYear = DateTime.forDateOnly( today.getYear() + 1, 12, 25 );
            result = today.numDaysFrom( christmasNextYear );
        }
        log( "Number of days till Christmas : " + result );
    }

View Full Code Here


    /**
     * What day is 90 days from today?
     */
    public static void whenIs90DaysFromToday () {
        DateTime today = DateTime.today( TimeZone.getDefault() );
        log( "90 days from today is : " + today.plusDays( 90 ).format( "YYYY-MM-DD" ) );
    }

View Full Code Here


    /**
     * What day is 3 months and 5 days from today?
     */
    public static void whenIs3Months5DaysFromToday () {
        DateTime today = DateTime.today( TimeZone.getDefault() );
        DateTime result = today.plus( 0, 3, 5, 0, 0, 0, 0, DateTime.DayOverflow.FirstDay );
        log( "3 months and 5 days from today is : " + result.format( "YYYY-MM-DD" ) );
    }

View Full Code Here

    /**
     * Current number of hours difference between Paris, France and Perth, Australia.
     */
    public static void hoursDifferenceBetweenParisAndPerth () {
        //this assumes the time diff is a whole number of hours; other styles are possible
        DateTime paris = DateTime.now( TimeZone.getTimeZone( "Europe/Paris" ) );
        DateTime perth = DateTime.now( TimeZone.getTimeZone( "Australia/Perth" ) );
        int result = perth.getHour() - paris.getHour();
        if ( result < 0 ) {
            result = result + 24;
        }
        log( "Numbers of hours difference between Paris and Perth : " + result );
    }

View Full Code Here


    /**
     * How many weeks is it since Sep 6, 2010?
     */
    public static void weeksSinceStart () {
        DateTime today = DateTime.today( TimeZone.getDefault() );
        DateTime startOfProject = DateTime.forDateOnly( 2010, 9, 6 );
        int result = today.getWeekIndex() - startOfProject.getWeekIndex();
        log( "The number of weeks since Sep 6, 2010 : " + result );
    }

View Full Code Here


    /**
     * How much time till midnight?
     */
    public static void timeTillMidnight () {
        DateTime now = DateTime.now( TimeZone.getDefault() );
        DateTime midnight = now.plusDays( 1 ).getStartOfDay();
        long result = now.numSecondsFrom( midnight );
        log( "This many seconds till midnight : " + result );
    }

View Full Code Here

0 1 2

TOP

Related Classes of hirondelle.date4j.DateTime$MissingItem

com.dotmarketing.osgi.external.Examples

Controlador.AlquilerControlador

Controlador.ArticuloControlador

Controlador.UsuarioControlador

java.util.GregorianCalendar

java.util.Calendar

All source code are property of their respective owners. Java is a trademark of Sun Microsystems, Inc and owned by ORACLE Inc. Contact coftware#gmail.com.