Saturday, October 2, 2010

How to format the Date and Time in an Ant Script

Configuration Nightmare

On the current project I am working on, we have people in three different timezones working on the same code and environments.  We have a fairly normal testing environments set up of: Unit, Integration, System, Acceptance, and Regression levels.  Our current deployment strategy calls for each WebService to have everything it needs in one package, meaning that if WebService A and B both use the same Data Access jar, then both WebService packages will have their own versions of the jar.  As you may have guess this works fine for the most part if that Data Access jar is not changing, but if it does change then both WebServices will have to be redeployed if they both want to use any changes to the Data Access jar.

This strategy can lead to the following issues (shown in this UML Deployment Diagram):

If you look closely you will see that in GetAccount WebService in the Integration level we have version 1 of the DataAccess jar, if all our testing validates that this service works but we want the new functionality of version 2 of the DataAccess jar, we will have to retest with version 2 to validate that the new jar does not cause issues.  This issue is easy enough for the Environment Manager, all they have to do is deploy the GetAccount WebService with version 2 of the DataAccess jar.  The Environment Manager will just have to go to the CMS and get version 2 of the jar, unfortantly the CMS is designed to be accessed by dates of atrifacts and has a totally different concept of versions.  To make matters worst the Environment Manager is in a different timezone than the developers and the CMS they use.

This was the kind of position I found myself in recently.  The MAINIFEST.MF in the jar was using a date and time format that was in the European style (day/month/year) with a time without a timezone.  The Ant script was creating a MAINIFEST.MF file with attributes for the data and time that confused everyone, so I went in and changed the script.  That is when I found out there was no single document that covered the Ant TStamp task in full.  I hope the rest of this blog will solve that issue.

Ant TStamp Task

TStamp Task has the following format:

propertyThe property to receive the date/time string in the given pattern.Yes
patternThe date/time pattern to be used. The values are as defined by the Java SimpleDateFormat class.Yes
timezoneThe timezone to use for displaying time. The values are as defined by the Java TimeZone class.No
offsetThe numeric offset to the current timeNo
unitThe unit of the offset to be applied to the current time. Valid Values are
  • millisecond
  • second
  • minute
  • hour
  • day
  • week
  • month
  • year
localeThe locale used to create date/time string. The general form is "language, country, variant" but either variant or variant and country may be omitted. For more information please refer to documentation for the Locale class.No

An example would be:
  <format property="datetime" pattern="MM/dd/yyyy hh:mm"/>

I find this pattern for the format of the date and time to be a bit elitist.  Meaning people use to the European style of dates might get confuse, plus there is no timezone on the time which could lead to even more confusion.  Instead I think that the month should be spelled out and the time should have a timezone.  We are lucky since the pattern that Ant's TStamp Task uses is the same pattern used for Java's SimpleDateFormat class.

Java SimpleDateFormat Pattern

Java's SimpleDateFormat uses the follow pattern:

LetterDate or Time ComponentPresentationExamples
GEra designatorTextAD
MMonth in yearMonthJulyJul07
wWeek in yearNumber27
WWeek in monthNumber2
DDay in yearNumber189
dDay in monthNumber10
FDay of week in monthNumber2
EDay in weekTextTuesdayTue
aAm/pm markerTextPM
HHour in day (0-23)Number0
kHour in day (1-24)Number24
KHour in am/pm (0-11)Number0
hHour in am/pm (1-12)Number12
mMinute in hourNumber30
sSecond in minuteNumber55
zTime zoneGeneral time zonePacific Standard TimePSTGMT-08:00
ZTime zoneRFC 822 time zone-0800

Look at the table above we see that M can be used to show the month and z can be used to show the timezone.  Looking at the examples given in the Java doc we see the following:

Date and Time PatternResult
"yyyy.MM.dd G 'at' HH:mm:ss z"2001.07.04 AD at 12:08:56 PDT
"EEE, MMM d, ''yy"Wed, Jul 4, '01
"h:mm a"12:08 PM
"hh 'o''clock' a, zzzz"12 o'clock PM, Pacific Daylight Time
"K:mm a, z"0:08 PM, PDT
"yyyyy.MMMMM.dd GGG hh:mm aaa"02001.July.04 AD 12:08 PM
"EEE, d MMM yyyy HH:mm:ss Z"Wed, 4 Jul 2001 12:08:56 -0700

When M is used three or more times, we get a text representation of the month, which is what we want.  Further, with a z we get the timezone and also with an a we get the AM/PM marker (which is good since we have options for 24 hour days starting with either 0 or 1, so we'll do the easy thing and use AM/PM).

TStamp Task Solution

I changed the date and time MANIFEST attribute to be:
  <format property="datetime" 
pattern="EEE, MMM dd, yyyy hh:mm:ss a z"/>

which gives the follow:

Wed, Jul 04, 2001 12:08:56 PM PDT

Which I find much more readable and understandable to people across the world.