Re: Flags for getFile/getDirectory (Re: New draft of FileSystem API posted)
On Tue, 7 Sep 2010, Darin Fisher wrote: Based on the ValidityState example, it seems that the members of Flags should be camelCase then instead of UPPERCASE? The platform convention, insofar as there is a convention, is that constants are uppercase, members are camelCase, and interfaces and constructors are TitleCase. -- Ian Hickson U+1047E)\._.,--,'``.fL http://ln.hixie.ch/ U+263A/, _.. \ _\ ;`._ ,. Things that are impossible just take longer. `._.-(,_..'--(,_..'`-.;.'
Re: Flags for getFile/getDirectory (Re: New draft of FileSystem API posted)
On Tue, Sep 7, 2010 at 11:13 PM, Ian Hickson i...@hixie.ch wrote: On Tue, 7 Sep 2010, Darin Fisher wrote: Based on the ValidityState example, it seems that the members of Flags should be camelCase then instead of UPPERCASE? The platform convention, insofar as there is a convention, is that constants are uppercase, members are camelCase, and interfaces and constructors are TitleCase. I was thinking of those as constants, but really they're members, so yes, they should be camelCase. I'll fix them. -- Ian Hickson U+1047E )\._.,--,'``. fL http://ln.hixie.ch/ U+263A /, _.. \ _\ ;`._ ,. Things that are impossible just take longer. `._.-(,_..'--(,_..'`-.;.'
Re: Flags for getFile/getDirectory (Re: New draft of FileSystem API posted)
Hi Eric,
(re-sending from the correct address)
I've been re-reading the spec and started wondering if we really want to
have a new interface / javascript object for Flags.
The Flags interface is used to specify two behavioral options (CREATE and
EXCLUSIVE) for DirectoryEntry.getFile and getDirectory and defined as
following:
4.2. The Flags Interface
http://dev.w3.org/2009/dap/file-system/file-dir-sys.html#the-flags-interface
interface Metadata {
attribute boolean
CREATEhttp://dev.w3.org/2009/dap/file-system/file-dir-sys.html#widl-Metadata-CREATE
;
attribute boolean
EXCLUSIVEhttp://dev.w3.org/2009/dap/file-system/file-dir-sys.html#widl-Metadata-EXCLUSIVE
;
};
(by the way I assumed you meant Flags but not Metadata.)
As the example code shows (4.2.2 Examples), each Flags object will likely be
used as a 'one-time' object just to specify the behavior per each
getFile/getDirectory. If that's the case, isn't it simpler/easier to use a
bitfield and use single unsigned int parameter for the flags [proposal 1]?
Or if we're not going to add more options it might be also good to simply
use two separate boolean parameters [proposal 2].
[Proposal 1]
interface DirectoryEntry {
const unsigned short CREATE = 0x01;
const unsigned short EXCLUSIVE = 0x02;
void getFile(in DOMString path, optional unsigned short options, ...);
void getDirectory(in DOMString path, optional unsigned short options,
...);
...
};
[Proposal 2]
interface DirectoryEntry {
void getFile(in DOMString path, bool create, bool exclusive, ...);
void getDirectory(in DOMString path, bool create, bool exclusive,
...);
...
};
What do you think?
Thanks,
Kinuko
On Wed, Jul 7, 2010 at 6:50 PM, Eric Uhrhane er...@google.com wrote:
I've posted a new draft of File API: Directories and System [1]. In
this draft I've rolled in quite a bit of feedback that I received
since first posting it on DAP--many apologies for the delay. This is
the first draft produced since we agreed to move this spec from DAP to
WebApps; I hope those of you who have time will give it a look and let
me know what you think.
In general I've tried to address any comment I was sent and had not
already addressed via email. The few that didn't make it in, I've
responded to below.
My thanks to Robin Berjon and Mike Clement for all their feedback.
Robin:
- data stored there by the application should not be deleted by the
UA without user intervention, UA should require permission from the
user, The application may of course delete it at will - these
sound like real conformance statements, therefore SHOULD, SHOULD NOT,
and MAY.
Those are in a non-normative section; is that language still appropriate
there?
Robin:
[discussion about speccing the URI format]
Left as an open issue.
Mike:
[discussion about multiple sandboxes per origin]
I think that would be very easy and clean to add later if desired, and
in the mean time, one can use subdirectories.
Mike:
getFile/getDirectory are a bit overloaded. How about including
methods like exists(), createFile() and createDirectory()? Though
these methods are easily implemented in terms of getFile/getDirectory,
I always prefer more direct API methods that help make the code easier
to understand. I expect, though, that you are attempting to be a low
level as possible here.
As Robin pointed out, adding extra round-trips will slow things down.
Also, it can encourage race conditions. These are easy for libraries
to implement via wrappers.
Mike:
[request for creation time in getMetadata]
It may be hard to support reliably cross-platform [2].
Robin:
[specifying a single locale everywhere]
I don't think that'll make folks very happy if it's not their locale.
If I e.g. try to force my locale on Turkish Windows users, they're
going to see some interesting errors trying to share files with apps
outside the browser, or for that matter even saving certain groups of
files from inside the browser.
Eric
[1] http://dev.w3.org/2009/dap/file-system/file-dir-sys.html
[2] http://en.wikipedia.org/wiki/MAC_times
Re: Flags for getFile/getDirectory (Re: New draft of FileSystem API posted)
On Tue, Sep 7, 2010 at 12:41 AM, Kinuko Yasuda kin...@chromium.org wrote:
Hi Eric,
(re-sending from the correct address)
I've been re-reading the spec and started wondering if we really want to
have a new interface / javascript object for Flags.
The Flags interface is used to specify two behavioral options (CREATE and
EXCLUSIVE) for DirectoryEntry.getFile and getDirectory and defined as
following:
4.2. The Flags Interface
http://dev.w3.org/2009/dap/file-system/file-dir-sys.html#the-flags-interface
interface Metadata {
attribute boolean CREATE;
attribute boolean EXCLUSIVE;
};
(by the way I assumed you meant Flags but not Metadata.)
As the example code shows (4.2.2 Examples), each Flags object will likely be
used as a 'one-time' object just to specify the behavior per each
getFile/getDirectory. If that's the case, isn't it simpler/easier to use a
bitfield and use single unsigned int parameter for the flags [proposal 1]?
That was my original proposal; see the very brief discussion at
http://lists.w3.org/Archives/Public/public-device-apis/2010Apr/0036.html.
Robin [+CC] suggested we switch to an interface object. I think the
current form is nicely explicit and easy to understand and use. The
bitflags are traditional in POSIX, but not very JavaScript-ish.
Or if we're not going to add more options it might be also good to simply
use two separate boolean parameters [proposal 2].
I don't like this. The more parameters you have, the harder the
methods get to use. This mechanism would make expanding the API quite
messy. Also, having two boolean parameters right next to each other
is error-prone.
I think that ORing together bits is better than adding more
parameters, and I think the current proposal is cleaner than that.
But I'm open to debate, of course.
[Proposal 1]
interface DirectoryEntry {
const unsigned short CREATE = 0x01;
const unsigned short EXCLUSIVE = 0x02;
void getFile(in DOMString path, optional unsigned short options, ...);
void getDirectory(in DOMString path, optional unsigned short options,
...);
...
};
[Proposal 2]
interface DirectoryEntry {
void getFile(in DOMString path, bool create, bool exclusive, ...);
void getDirectory(in DOMString path, bool create, bool exclusive, ...);
...
};
What do you think?
Thanks,
Kinuko
On Wed, Jul 7, 2010 at 6:50 PM, Eric Uhrhane er...@google.com wrote:
I've posted a new draft of File API: Directories and System [1]. In
this draft I've rolled in quite a bit of feedback that I received
since first posting it on DAP--many apologies for the delay. This is
the first draft produced since we agreed to move this spec from DAP to
WebApps; I hope those of you who have time will give it a look and let
me know what you think.
In general I've tried to address any comment I was sent and had not
already addressed via email. The few that didn't make it in, I've
responded to below.
My thanks to Robin Berjon and Mike Clement for all their feedback.
Robin:
- data stored there by the application should not be deleted by the
UA without user intervention, UA should require permission from the
user, The application may of course delete it at will - these
sound like real conformance statements, therefore SHOULD, SHOULD NOT,
and MAY.
Those are in a non-normative section; is that language still appropriate
there?
Robin:
[discussion about speccing the URI format]
Left as an open issue.
Mike:
[discussion about multiple sandboxes per origin]
I think that would be very easy and clean to add later if desired, and
in the mean time, one can use subdirectories.
Mike:
getFile/getDirectory are a bit overloaded. How about including
methods like exists(), createFile() and createDirectory()? Though
these methods are easily implemented in terms of getFile/getDirectory,
I always prefer more direct API methods that help make the code easier
to understand. I expect, though, that you are attempting to be a low
level as possible here.
As Robin pointed out, adding extra round-trips will slow things down.
Also, it can encourage race conditions. These are easy for libraries
to implement via wrappers.
Mike:
[request for creation time in getMetadata]
It may be hard to support reliably cross-platform [2].
Robin:
[specifying a single locale everywhere]
I don't think that'll make folks very happy if it's not their locale.
If I e.g. try to force my locale on Turkish Windows users, they're
going to see some interesting errors trying to share files with apps
outside the browser, or for that matter even saving certain groups of
files from inside the browser.
Eric
[1] http://dev.w3.org/2009/dap/file-system/file-dir-sys.html
[2] http://en.wikipedia.org/wiki/MAC_times
Re: Flags for getFile/getDirectory (Re: New draft of FileSystem API posted)
On Tue, Sep 7, 2010 at 6:07 PM, Eric Uhrhane er...@google.com wrote:
On Tue, Sep 7, 2010 at 12:41 AM, Kinuko Yasuda kin...@chromium.org wrote:
Hi Eric,
(re-sending from the correct address)
I've been re-reading the spec and started wondering if we really want to
have a new interface / javascript object for Flags.
The Flags interface is used to specify two behavioral options (CREATE and
EXCLUSIVE) for DirectoryEntry.getFile and getDirectory and defined as
following:
4.2. The Flags Interface
http://dev.w3.org/2009/dap/file-system/file-dir-sys.html#the-flags-interface
interface Metadata {
attribute boolean CREATE;
attribute boolean EXCLUSIVE;
};
(by the way I assumed you meant Flags but not Metadata.)
As the example code shows (4.2.2 Examples), each Flags object will likely be
used as a 'one-time' object just to specify the behavior per each
getFile/getDirectory. If that's the case, isn't it simpler/easier to use a
bitfield and use single unsigned int parameter for the flags [proposal 1]?
That was my original proposal; see the very brief discussion at
http://lists.w3.org/Archives/Public/public-device-apis/2010Apr/0036.html.
Robin [+CC] suggested we switch to an interface object. I think the
current form is nicely explicit and easy to understand and use. The
bitflags are traditional in POSIX, but not very JavaScript-ish.
Or if we're not going to add more options it might be also good to simply
use two separate boolean parameters [proposal 2].
I don't like this. The more parameters you have, the harder the
methods get to use. This mechanism would make expanding the API quite
messy. Also, having two boolean parameters right next to each other
is error-prone.
I think that ORing together bits is better than adding more
parameters, and I think the current proposal is cleaner than that.
But I'm open to debate, of course.
I think the bitfield approach is better. The current approach doesn't
work very well in strongly typed languages. Although we might think
that these APIs will be used most-often from JavaScript, these APIs
are language neutral and should work in a variety of settings (e.g.,
as part of the NPAPI). Baking in assumptions that APIs are used by
dynamically typed language isn't good for the web platform in the long
term.
Adam
Re: Flags for getFile/getDirectory (Re: New draft of FileSystem API posted)
On Tue, 7 Sep 2010, Adam Barth wrote: I think the bitfield approach is better. The current approach doesn't work very well in strongly typed languages. Although we might think that these APIs will be used most-often from JavaScript, these APIs are language neutral and should work in a variety of settings (e.g., as part of the NPAPI). Baking in assumptions that APIs are used by dynamically typed language isn't good for the web platform in the long term. The APIs don't have to be identical in each language. For example, I would expect a C++ port of ValidityState: http://www.whatwg.org/specs/web-apps/current-work/complete.html#validitystate ...to be implemented as a bitfield with constants, rather than as an object with fields. Should anyone want to implement that interface in such a language, then would be a time to provide suitable IDL for that case. -- Ian Hickson U+1047E)\._.,--,'``.fL http://ln.hixie.ch/ U+263A/, _.. \ _\ ;`._ ,. Things that are impossible just take longer. `._.-(,_..'--(,_..'`-.;.'
Re: Flags for getFile/getDirectory (Re: New draft of FileSystem API posted)
On Tue, Sep 7, 2010 at 8:41 PM, Ian Hickson i...@hixie.ch wrote: On Tue, 7 Sep 2010, Adam Barth wrote: I think the bitfield approach is better. The current approach doesn't work very well in strongly typed languages. Although we might think that these APIs will be used most-often from JavaScript, these APIs are language neutral and should work in a variety of settings (e.g., as part of the NPAPI). Baking in assumptions that APIs are used by dynamically typed language isn't good for the web platform in the long term. The APIs don't have to be identical in each language. For example, I would expect a C++ port of ValidityState: http://www.whatwg.org/specs/web-apps/current-work/complete.html#validitystate ...to be implemented as a bitfield with constants, rather than as an object with fields. Should anyone want to implement that interface in such a language, then would be a time to provide suitable IDL for that case. -- Ian Hickson U+1047E)\._.,--,'``.fL http://ln.hixie.ch/ U+263A/, _.. \ _\ ;`._ ,. Things that are impossible just take longer. `._.-(,_..'--(,_..'`-.;.' Slight tangent Based on the ValidityState example, it seems that the members of Flags should be camelCase then instead of UPPERCASE? -Darin
