Re: Alarm API Draft

Hi,

Thanks for taking the time to review the proposal.

Could you please state your name and affiliation for the sake of clarity?

On Mon, Nov 19, 2012 at 10:54 PM, timeless <timeless@gmail.com> wrote:

> Chritophe wrote:
> > We have uploaded an initial draft proposal of the Alarm API to:
> > http://sysapps.github.com/sysapps/proposals/alarm/Overview.html
>
>
> > The AlarmManager interface exposes methods to get, set or remove alarms.
> Alarms are application specific, so there is no way to see the alarms
> scheduled by other applications nor to modify them.
>
> I wonder how the system defines an "application"?
>

Execution and Security models will be defined in Phase 1 of SysApps WG.
This should clarify things.


>
> If I uninstall an application and reinstall it, are the alarms persisted?
>
> If I install version 2 of an application and I had alarms in version
> 1, are the alarms persisted?
>
> Please note that this API doesn't match how the proposed Contacts API
> works at all. Contacts aren't Application specific.
>

Yes, this was done on purpose. While it makes sense for applications to
share the same contacts, alarms are another matter. We don't think an
application should be allowed to mess with another application's alarms.
An alarm is really specific to a given application since it will spawn this
application when triggered.


>
> > enum TimezoneDirective { "honorTimezone", "ignoreTimezone" };
>
> Please avoid using words where the spelling in en-us and en-gb differ.
> "honor" v. "honour". The odds of someone trying to use
> "honourTimezone" are unfortunately quite high.
>

Good point. I think "respectTimezone" would be less error-prone.


>
> > The add(alarm, respectTimezone[, data]) method is used to register a an
> alarm.
>
> "a an" [sic]
>

Ok.


>
> >  AlarmRequest add(Date date, TimezoneDirective respectTimezone, optional
> Object data);
> > The add(alarm, respectTimezone[, data]) method is used to register a an
> alarm.
>
> These do not agree.
>

Ok. I'll fix the typo. This is indeed confusing.


>
> > 1.The first argument date can be passed by a Date object.
>
> This statement is confusing on its own, but the confusion stems from
> the previous confusion.
>

Ok. I'll try to clarify.


>
> > 2.The second argument respectTimezone can be passed by either
> "honorTimezone" or "ignoreTimezone"
> > to specify if we need to ignore the timezone information of that Date
> object.
> > When "honorTimezone" is passed, we will alert that application when that
> time happens in that timezone.
> > I.e. if someone passes a Date object which has the timezone set to US
> Pacific Time and time set to 7am,
> > we will alert the application when the time is 7am in the US Pacific
> timezone, even if the user is in New York
> > and thus in US Eastern Time and it's 10am for the user. When
> "ignoreTimezone" is passed, we will ignore the
> > timezone part of the passed in Date object. I.e. if someone passes a
> Date object which has the timezone set
> > to US Pacific Time and time set to 7am, we will alert the application
> when the time is 7am in whatever
> > timezone the user happens to be in. So if the user is in New York, we
> will alert the user when it's 7am in that timezone.
>
> Assuming that the user is in a timezone which has DST and assuming the
> alarm recurs across a DST border, you haven't defined what happens
> there.
>

This API does not support recurring alarms in itself. This can be handled
on application side.


>
> Labeling something as "US Pacific Time" or "US Eastern Time" should be
> your first clue that your API is broken as neither such time exists.
>
> There's Pacific Daylight Time and Pacific Standard Time, there is no
> "Pacific Time" nor is there an "Eastern Time" (although there *is* an
> Easter Time, and that does move around some).
>

I'll rename to Pacific Standard Time (PST) and Eastern Standard Time (EST)
to avoid confusion.
I'm not sure how this relates to the API in itself being broken though.


>
> > 3.The third argument data can be optionally specified to pass the
> customized JSON object data for that alarm. Note that an unique ID will be
> returned to refer to the added alarm.
>
> Oddly, it should be "a unique" as it's really "a youtube" not "an ootube"
>

Ok.

> The id attribute must return an identifier for the given Alarm object
> that is unique within the origin. An implementation must maintain this
> identifier when a Alarm is added.
>
> Origin should be linked to something. Note that "origin" conflicts
> with the earlier statement that it was "per application", if the
> answer to my previous question is "per origin" then the previous text
> should be adjusted to say "per origin" instead of "per application".
>

The security model is going to be in Phase 1 of SysApps WG. This can be
clarified afterwards.
My current assumption is that there is only one application allowed per
origin (though an application may load assets and code from other origins).


>
> > The alarm event is fired when an alarm goes off.
>
> Where does an alarm go off? ("not bubble; not cancelable" isn't a
> place, nor is "at an alarm manager", does the system / UA manage it?
> Does it apply to multiple instances of an application? Does a
> suspended instance get an alarm?)
>

The system needs to manage it. The other questions need to be discussed
after the execution model has been defined (Phase 1 of SysApps WG) I
believe.
In practice, I believe the alarm should be able to actively wake up the
system from sleeping and the application should get the alarm even if
suspended.


>
> > When this happens, the user agent must queue a task to fire an event
> with the name alarm, which does not bubble and is not cancelable, and which
> uses the AlarmEvent interface, at each AlarmManager object that is affected.
>
> How many AlarmManagers can there be, and why?
>

The AlarmManager is exposed via the window.navigator object. If an
application opens several windows, each window has a window.AlarmManager
object that might be affected by the change.
It is therefore important that events are fired for each instance of the
AlarmManager that is affected.

> References
>
> If most of your API is stolen from Boot-to-Gecko then you should at
> least have a non-normative reference to that origin. Lack of
> references especially for source material is really inappropriate,
> just because stuff is "open source" doesn't mean you're free to skip
> attribution.
>

The API is not "stolen", it is for the most part identical to the B2G Alarm
API though.
The original authors *are* clearly mentioned in the Acknowledgment section.
Maybe you didn't see it.
We have also asked several people from Mozilla for review before uploading
the proposal.

You are right though that the original B2G API should also be part of the
references section and we will fix this. The references section is clearly
incomplete at this point.

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