RE: Alarm API Feedback

Hello Christophe,
Thanks for getting back to me.

>> a) Section 4.2:  The error codes returned for add() and remove() are not defined.
> Yes, you are right. The error types need to be defined. I am proposing the following:

The error codes you have suggested are fine.

>> 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?

I was curious as to why it needed to be specified when there are no normative methods defined in the Alarm API spec which take advantage of it being in JSON.  I agree that particularly for JS representation that JSON is more than adequate, but allowing a DOMString would allow developers to leverage Alarm metadata in another format.

>> 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?

I think my original phrasing of the question was too narrow - I was interested in general in the uniqueness of Alarm ID's regardless of security origin.   I think there are dependencies on how applications on the target platform exchange data.  If the Alarm ID's are unique only with respect to the same security origin, then what occurs if Alarm ID's are exchanged between two applications of different security origins?

It is conceivable that Alarms defined in one security origin should not be accessible in other security origins to get around this problem (as is stated in the text currently "Alarms are application specific, so there is no way to see the alarms scheduled by other applications nor to modify them"), but this may prevent target use cases.  As an example, think of one application being a downloadable calendar app, and another application being a turn-by-turn nav app.  It could be that the nav app moves into the foreground upon a alarm event defined by the calendar app and provides a route to a destination specified in Alarm.data defined by the calendar app.

You might be best off stating that an Alarm ID is unique, regardless of security origin.  When an alarm is removed or exhausted, then the corresponding Alarm ID can be reassigned.

I view this as somewhat analogous to the watchPosition method defined in the Geolocation spec (see http://dev.w3.org/geo/api/spec-source.html#watch-position).  The returned ID is unique, without any qualification (e.g. security origin).  This may not be the way all vendors implement it, but the spec in my opinion is not ambiguous on this point.

> 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.

OK.  This is not IMO a critical issue, but other device API's that have been defined in the W3C leverage Booleans when possible.  I personally think we should avoid enums with only two entries, but it seems that there are other points-of-view.

> 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 respect/ignore time zone arguments are sufficient to clarify this issue.  Josh provided an example in another email, and I'll summarize where there is IMO ambiguity in the current spec:


1.       add(new Date(2013, 3, 10, 2, 00, 00), "ignoreTimezone");

a.       If I am in a location that respects DST on this date (e.g. California), this alarm could never go off.  This is because the clock sprung forward at 01:59 on March 10.

b.      If am in a location that does not follow DST (e.g. Arizona), then this alarm will function as normal.

c.       Since the alarm was set before the DST event, the implementation has no way of being able to determine whether the alarm can be triggered or not because the "ignoreTimezone" flag is set.  Ideally, an add() of an alarm that cannot go off would result in an error.  So how does the application know that an alarm event has been missed?

2.       Add(new Date(2013,11,3,1,10,00),"ignoreTimezone");//Josh's example

a.       In locations where DST is followed, the clock moves back at 01:59 on Nov. 3.  Does the alarm go off twice now? Or is the alarm exhausted upon the initial firing?



From: Dumez, Christophe [mailto:christophe.dumez@intel.com]
Sent: Tuesday, January 15, 2013 3:14 AM
To: public-sysapps@w3.org
Cc: Mandyam, Giridhar; Jonas Sicking
Subject: 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<mailto: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