I'm going to share what I've learned from building my own calendar
application. Some of this will seem obvious or common-knowledge, but I
want to make sure the subject is covered thoroughly and I also want to
make sure that everyone who is interested in the subject will be on the
same page.
My goal: to develop what I call a "movable calendar" - a set of date/time
services that will operate correctly no matter what time zone or locale
the user is in.
*** The concept -
OFBiz uses java.sql.Timestamp for storing/retrieving date/time values.
Timestamp is a long data type that contains milliseconds elapsed since Jan
1, 1970. The time is referenced to UTC. A particular moment in time that
is represented by a Timestamp value can be thought of as a constant, or
that the
value is immutable. The user's timezone or locale does not alter the
Timestamp's value.
In order for a user to interact with a Timezone value in a way that
reflects their timezone and locale, the Timezone value must be converted
to a user-friendly data type - typically a String. Java supplies a good
set of classes that manage Timestamp-to-String and String-to-Timestamp
conversions.
Those classes do all the work of basing the conversions on timezones and
locales - the programmer doesn't have to bother with any of those details.
As long as the services that handle date/time values always utilize the
user's timezone and locale in conversions, then the goal will be achieved
- a calendar that moves with the user. It helps to look at it this way:
Entity --> Conversion to String using the user's time zone and locale -->
UI
UI --> Conversion to Timestamp using the user's time zone and locale -->
Entity
It is very important to understand that all conversions must be run
through the same services, otherwise the date/time value presented to the
user (or stored in an entity) will be unpredictable.
*** The implementation -
I created two conversion methods:
public static String timeStampToString(Timestamp stamp, TimeZone tz,
Locale locale);
public static Timestamp stringToTimeStamp(String dateTimeString,
TimeZone tz, Locale locale);
and I made sure that all date/time data in my calendar application is
routed through those two methods. The implementation was successful. A
date/time value I create in one timezone appears in the correct time when
I switch timezones. In addition, since the conversions utilize the user's
locale, the
date/time values are displayed/edited in the format I expect to see them
(dd mmm yyyy if I'm in Europe).
*** Building out the basic implementation -
When I first mentioned I was working on a calendar application, a few
developers suggested I just use the WorkEffort component. I took a close
look at it and decided against that approach because it had one major flaw
- all date/time values are based on the server's timezone and locale. So,
any
calendar based on WorkEffort will not be movable. Plus, it would be much
faster for me to develop one from scratch instead of reverse engineering
WorkEffort and fixing its flaws. I'll describe my approach here in order
to share the lessons I learned - I am NOT trying to push my calendar
application
on the community. My hope is the lessons I learned can be applied to the
existing code base.
I looked at the various existing entities and came up with a very
fundamental data structure that many of them share. The field names that
the existing entities use may be different, but they all have the same
purpose. I called the basic structure a Timed Event:
<entity entity-name="TimedEvent" package-name="org.ofbiz.calendar"
title="Timed Event">
<field name="eventId" type="id-ne"></field>
<field name="parentEventId" type="id"></field>
<field name="eventType" type="id-ne"></field>
<field name="eventStatus" type="id"></field>
<field name="description" type="description"></field>
<field name="startDateTime" type="date-time"></field>
<field name="endDateTime" type="date-time"></field>
<field name="recurringId" type="id"></field>
<prim-key field="eventId"/>
<relation type="one" rel-entity-name="Enumeration">
<key-map field-name="eventType" rel-field-name="enumId"/>
</relation>
</entity>
Then I built a set of CRUD services around it. All of the services accept
a time zone ID and locale as parameters and they run all conversions
through the two conversion methods I created. Here's where I ran into my
first problem - I took the shortcut approach in my services.xml file:
<service name="createTimedEvent" engine="java"
location="org.ofbiz.calendar.EventCalendarServices"
invoke="createTimedEvent">
<description>Create a Timed Event</description>
<auto-attributes entity-name="TimedEvent" include="nonpk" mode="IN"
optional="true"/>
<attribute name="tzId" type="String" mode="IN" optional="true"/>
<attribute name="eventId" type="String" mode="OUT" optional="true"/>
</service>
When the createTimedEvent service is invoked with String data types,
startDateTime and endDateTime arrive in the Java code as Timestamp data
types. How nice - the service engine converted the strings to Timestamps
for me. Normally I would be appreciative, but the problem is, the service
engine did
the conversions based upon the server's timezone and locale - not the
user's. That is not acceptable. So, I had to remove the auto-attributes
entry and list the startDateTime and endDateTime attributes as Strings.
Next, I created my Calendar Event entity by specifying a few additional
event properties and relating that entity to TimedEvent.
On to the user interface. I prefer to develop with the bsh/ftl combo -
it's flexible and intuitive for me. That's where I ran into my next
problem. Ftl transforms like ${timedEvent.startDateTime} - if
startDateTime is a Timestamp data type - are converted to Strings by
Freemarker using the server's
timezone and locale. So, every date/time value that appears on the screen
had to be converted to Strings BEFORE hitting the template. One Freemarker
transform is okay to use: ${timedEvent.startDateTime?string("#")} - which
converts the Timestamp object to its milliseconds value. As I mentioned
previously, that value is a constant that isn't altered by timezone or
locale.
Having jumped those hurdles, I had a working "movable" calendar. If I
switch timezones, the calendar events move to the correct slots. If I
switch to a French locale, the week starts on Monday. Date/time values are
displayed and editied in locale-appropriate formats. It all works
flawlessly.
*** Applying this information to OFBiz -
There have been a number of Jira issues submitted that revolve around
date/time issues. My hope is those issues can be revisited with this
information and possibly find solutions to the problems.
The UtilDateTime class was created before the new Calendar and Timezone
Java classes, so many of its methods are based on the server's timezone
and locale. An updated UtilDateTime class has been submitted to Jira
(https://issues.apache.org/jira/browse/OFBIZ-2) and I am in the process of
testing it now.
By the way, I am in no way suggesting that EVERY date/time piece of data
needs to be converted. Some date/time values make better sense if they are
referenced to the server's timezone and locale. Each application needs to
be evaluated to determine which style of date/time data to use - the
server's
or the user's.
-Adrian
