Alarm API Feedback

Hi,

Thank you for the feedback. We should indeed discuss / address the issues
you mentioned. Please find my comments inline.

On Mon, Jan 14, 2013 at 6:58 PM, Mandyam, Giridhar <mandyam@quicinc.com>wrote:

> Hello,
> Qualcomm Innovation Center, a member of the SysApps Working Group, objects
> to the publication of the Alarm API as an FPWD.
>
> Some items we would like clarified in any subsequent modifications of the
> Editor's Draft are:
>
> a) Section 4.2:  The error codes returned for add() and remove() are not
> defined.  This is not consistent with other device-level API's defined in
> the W3C that would likely be used in a SysApps deployment (e.g. see the
> Geolocation API,
> http://dev.w3.org/geo/api/spec-source.html#posittheseion_error_interface<http://dev.w3.org/geo/api/spec-source.html#position_error_interface>
> ).
>

Yes, you are right. The error types need to be defined. I am proposing the
following:
- getAll()
  * "SecurityError" if the application does not have the permission to
perform this operation.
  * "TimeoutError" if the operation could not be performed in a reasonable
time.
  * "UnknownError" in any other error case.

- add()
  * "SecurityError" if the application does not have the permission to
perform this operation.
  * "InvalidStateError" if the alarm's date is set in the past.
  * "TimeoutError" if the operation could not be performed in a reasonable
time.
  * "UnknownError" in any other error case.

- remove()
  * "SecurityError" if the application does not have the permission to
perform this operation.
  * "NotFoundError" if there is no alarm with the given identifier.
  * "TimeoutError" if the operation could not be performed in a reasonable
time.
  * "UnknownError" in any other error case.

 Please let me know if you think this is insufficient.

b) Section 4.2: The data object in add() is has to be in valid JSON format.
>  Why?   Why not another textual format?
>

I believe the idea is that this data would not need parsing if it is in
JSON format. If we use another textual format then the data will need
parsing when the alarm is fired.
Of course, it is possible to do but why do we need to support another
textual format? Did you have any particular format in mind? What is the use
case?

c) Section 4: "The returned ID is unique (within the application origin)
> and can be used to specify and remove the added alarm."  The term
> 'application origin' does not clarify whether the ID is unique for each
> instance of the application, or it is unique with respect to all instances
> of an application that are open at any given instant in time on the same
> device.
>

Several instances of the same application would be within the same security
origin. Therefore, the ID would be unique with respect to all instances of
an application.
In practice, the idea is that all instances of the same application share
the same alarms. Therefore, I do not think there is a need to distinguish
between different instances of the same application. Is there?

That said, we should apparently clarify the specification to remove
ambiguity. Would this be better?
"The returned ID is unique within the application's security origin and can
be used to specify and remove the added alarm."

Or do you have any other proposal to clarify the statement?

d) Section 4.2.  Why is TimeZoneDirective an enum (as opposed to a
> Boolean)?  If there are only two options for the method argument, I don't
> see the point in defining an enum.
>

The point was to make the resulting code more readable and less bug-prone.
My personal opinion is that:
alarmManager.add(date, "respectTimezone");
is more readable / understandable than
alarmManager.add(date, true);

I know for example that this coding style is used quite commonly in WebKit
code.
Of course, it should be discussed if we really want to adopt this style in
our SysApps APIs or not.

e) Section 4.2:  DST guidance is not apparent in the current spec.  Is DST
> always honored with respect to alarms?  I'm unclear as to what should occur
> if a DST event (e.g. moving the clock forward or backwards by an hour)
> occurs between when the alarm was set and when the alarm occurs.
>

Yes, DST needs to be honored with respect to alarms or I believe this would
lead to unexpected behavior for the user. I don't think it technically
matters if there is DST event *between* the time the alarm is added and the
time the alarm should fire. What is important is to consider the daylight
savings in effect for the timezone*** on the date that the alarm should
fire. If the alarm is set for 6am, we need to fire the alarm at 6am on the
given firing date considering the daylight savings in effect on that date
for the timezone***.

***Which timezone is considered for daylight savings depends on the
respectTimezone argument of the add() method (see example below).

Let's consider examples:
- add(new Date(2013, 0, 16, 6, 0, 0), "ignoreTimezone"); // E.g. Wake up
alarm clock on January 16, 2013 at 6am.
This should wake you up at 6am on January 16th, 2013 in whatever timezone A
you happen to be in on that day, considering the daylight savings in effect
on that date for the timezone A.

- add(new Date(2013, 0, 16, 6, 0, 0), "respectTimezone"); // e.g. Meeting
in my current timezone on January 16, 2013 at 6am.
In this case, we need to consider the timezone (A) of the Date being given
and disregard the timezone (B) the user will be in on that day. The alarm
is attached to timezone A and a DST event may occur in that timezone
between the registration time and the alarm firing time. Again, we need to
fire the alarm when it is 6am in Timezone A on January 16, 2013,
considering the daylight savings in effect for timezone A on that date.

Should I add a mention in the add() method description that the daylight
savings in effect on the alarm firing date need to be honored?
Did I correctly understand and answer your question?

kr,
-- 
Christophe Dumez, PhD
Linux Software Engineer
Intel Finland Oy - Open Source Technology Center