org.thales.punch.libraries.punchlang.operator

Class DateOperator

java.lang.Object

org.thales.punch.libraries.punchlang.operator.DateOperator

public class DateOperator
extends Object

Basics

The date operator lets you generate or transform dates using standard formats. A first basic usage of the date operator is to generate timestamp. For example :

 [timestamp] = date(\"yyyy.MM.dd\").get();
 

produces

 { "timestamp" : "2015.09.23" }
 

Another use of the date operator is to convert a date from one format to another. You can specify timezones, years or any part of the date. Here is an example.

 // this date has no year set. We want to add the current year
 // and change its format to "yyyy-MM-dd'T'HH:mm:ssZ"
 String oldDate =  "Sep 10 15:43:11";

 // Here is how you do this with the date operator

 String newDate = date("yyyy-MM-dd'T'HH:mm:ssZ", "MMM dd HH:mm:ss").on(olddate).get();

 // newDate is "2015-09-10T15:43:11+0200"
 

Timezones

The date operator allows to play with timezones. When changing a date into another one you can set the timezone of the source date and/or the timezone of the target date. Use timezone or timezoneRetainFields

 // We receive a date without zone indication. We first want to change it
 // timezone to Europe/London, then to convert it to the iso standard time format.
 String oldDate = "1999-09-23 18:18:30";

 // Note that the timezone call will change the filed of the date from your current time zone
 // to Europe/London
 String newDate =  date("iso", "yyyy-MM-dd HH:mm:ss").timezone("Europe/London").on(oldDate).get();

 // You get "1999-09-23T18:18:30.000+01:00"
 

You may want to only add the timezone, not change the time fields. Do as follows:

 String newDate =  date("iso", "yyyy-MM-dd HH:mm:ss").timezoneRetainFields("Europe/London").on(oldDate).get();
 

Say you want to change the timezone of the source to some timezone and generate the target date to another. For example: you receive a date, you change it to "Pacific/Honolulu", retaining fields (because say you know that the timestamp comes from honolulu), but you want to generate it to your timezone (say Europe/London). Here is how to write that in a way you keep understanding your code:

 String newDate =  date("iso", "yyyy-MM-dd HH:mm:ss").timezoneRetainFields().timezone("Pacific/Honolulu")
     .totimezone("Europe/London").on(oldDate).get();
 

Timestamps

You can also deal with timestamp, in milliseconds since 1970. The following example shows how to convert a timestamp into a date:

 Tuple result;
 date("yyyy-MM-dd HH:mm:ss").on("1432219877720").into(result);
 // result contains "2015-05-21 16:51:17"
 

The following does the same but directly return a String result:

 String result = date("yyyy-MM-dd HH:mm:ss").on("1432219877720").get();
 // result contains "2015-05-21 16:51:17"
 

Daylight Saving Time

The Punch runtime use the java joda-time library, which only allows the key classes to store valid date-times. For example, 31st February is not a valid date so it can't be stored (except in Partial).
The same principle of valid date-times applies to daylight savings time (DST). In many places DST is used, where the local clock moves forward by an hour in spring and back by an hour in autumn/fall. This means that in spring, there is a "gap" where a local time does not exist.
The error "Illegal instant due to time zone offset transition" refers to this gap. It means that your punchlet tried to create a date-time inside the gap - a time that did not exist. Since Joda-Time objects must be valid, this is not allowed. As an example here is a piece of code that will fail.

 date(\"iso\", \"MMM dd HH:mm:ss\").on("Mar 29 02:00:00").into(/timestamp);
        

If you encounter this, format your input date to UTC timezone first, so that you will get a

 date(\"iso\", \"MMM dd HH:mm:ss\").timezone(\"UTC\").on("Mar 29 02:00:00").into(/timestamp);
        

.timezone(\"UTC\").

Constructor Summary

Constructors

Constructor and Description
DateOperator() Create a date operator with no destination or source date format.
DateOperator(org.joda.time.format.DateTimeFormatter dstDateFormat) create a date operator with a destination date format.
DateOperator(org.joda.time.format.DateTimeFormatter dstDateFormat, org.joda.time.format.DateTimeFormatter srcDateFormat) create a date operator with a destination and source date format.

Method Summary

Modifier and Type	Method and Description
String	get() Fire and get the result of this operator.
String	into(Tuple tuple) Fire and put the result of this operator into a destination tuple.
DateOperator	localzone(String timezone) Set the local timezone
DateOperator	on(String s) Take the input date from a Tuple.
DateOperator	on(Tuple tuple) Take the input date from a Tuple.
DateOperator	retainFields() Make the timezone change not alter the date fields.
DateOperator	timezone(String timezone) Set the source date timezone.
Long	toMillis() Convert the date to a long timestamp, in milliseconds.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DateOperator

public DateOperator()

Create a date operator with no destination or source date format.

DateOperator

public DateOperator(org.joda.time.format.DateTimeFormatter dstDateFormat)

create a date operator with a destination date format.

Parameters:

dstDateFormat - the destination time format

DateOperator

public DateOperator(org.joda.time.format.DateTimeFormatter dstDateFormat,
                    org.joda.time.format.DateTimeFormatter srcDateFormat)

create a date operator with a destination and source date format.

Parameters:

dstDateFormat - the destination time format

srcDateFormat - the source time format

Method Detail

on

public DateOperator on(Tuple tuple)

Take the input date from a Tuple.

Parameters:

tuple - the input tuple

Returns:

this operator

on

public DateOperator on(String s)

Take the input date from a Tuple.

Parameters:

s - the input date

Returns:

this operator

localzone

public DateOperator localzone(String timezone)

Set the local timezone

Parameters:

timezone - the timezone

Returns:

this operator

timezone

public DateOperator timezone(String timezone)

Set the source date timezone. This timezone will be applied to the input date.

Parameters:

timezone - a valid timezone.

Returns:

this operator

retainFields

public DateOperator retainFields()

Make the timezone change not alter the date fields.

Returns:

this operator

get

public String get()

Fire and get the result of this operator.

Returns:

the resulting date, an empty String if the operator

toMillis

public Long toMillis()

Convert the date to a long timestamp, in milliseconds.

Returns:

the timestamp

into

public String into(Tuple tuple)

Fire and put the result of this operator into a destination tuple.

Parameters:

tuple - a destination tuple

Returns:

the resulting date, this is the same value than the one stored in the tuple