[DISCUSSION] standard layer to exec : regCommandProxy

[Jesse <pu...@gmail.com>]

I have been giving this some thought, and posted a gist for discussion.

https://gist.github.com/1891465

I have not included any of the require/define wrapper api's, as I wanted
the API to be the talking point.  Ideally this would be implemented on ALL
platforms and allow us 100% consistency in APIs calling exec.

Dividing responsibilities, we would end up with something like the
following:

PluginCode ( concrete example compass.js )
- exposes consistent API for ALL platforms
- performs parameter checking

ProxyCode
- performs device specific implementation where native calls are not needed.

CordovaJS
- de-couples API specific differences across devices, exec is focused on
being a device specific bridge ( or a bridge with an on-ramp ).

An added benefit to this aproach is that it will provide us a stub point
where we can simulate/hook tests, as currently it is difficult to test
failing cases ( especially cases that typically should not fail )

Some additional questions that this may bring up:
1. do we need lesser/greater granularity of the APIs we want to proxy? ie
should we be able to hook all of Compass with one call, or individually for
each method?
2. do we need to provide an un-register method?
3. is there a more descriptive name for this?

Thoughts?...

Cheers,
  Jesse

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Filip Maj <fi...@adobe.com>]

Two ways so far that I have employed.

1. If you need to override an entire module, you can do so in the platform
definition file under platform/, like android does for the File and
FileError objects: 
https://github.com/apache/incubator-cordova-js/blob/master/lib/platform/and
roid.js#L120-L125

2. If you need to override one or a few methods on a prototype of a common
module, I do so in the "initialize" method of the platform definition
file. For example, BlackBerry needs to override only a couple of methods
on some File API modules:
https://github.com/apache/incubator-cordova-js/blob/master/lib/platform/bla
ckberry.js#L27-L39

Let me know if more clarification is needed.

P.S. Obviously neither of these approaches is "pretty" - there are better
approaches that can probably save us a few bytes in the js files - the
comments say as much. Something definitely that we should work on once we
land it!

On 12-02-23 9:57 AM, "Drew Walters" <de...@gmail.com> wrote:

>+1, but can we settle on what the currently recommended way of
>providing platform specific overrides is.  Ugly code is ugly code, but
>it should at least be homogeneously ugly.
>
>On Thu, Feb 23, 2012 at 11:51 AM, Filip Maj <fi...@adobe.com> wrote:
>>
>>>I think we can all agree that both of these are not the ideal solution
>>>but
>>>both work fine for now.
>>
>> This, in my mind, sums up this thread.
>>
>> Yes, there are problems and ugliness in cordova-js. However I think we
>>can
>> all see the benefit in moving to a unified JS approach where JavaScript
>> modules are king.
>>
>> Initially, yes, there are going to be some platform-specific overrides.
>> Are they ugly? Certainly. But let's first get the current fugly
>> implementation of cordova-js on all platforms, and then start iterating
>> and improving and removing/refactoring platform-specific stuff in the
>>next
>> few releases before 2.0.
>>
>> Once we got it incorporated into Android, we were passing more tests in
>> mobile-spec than the previous per-platform JS file implementation. Let's
>> make this happen on other platforms, get all of the maintainers and
>> committers comfortable with how the project works and is structured,
>>let's
>> all use it a little bit, and *then* start reasoning about what the
>> problems with it are how to solve them.
>>

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Drew Walters <de...@gmail.com>]

+1, but can we settle on what the currently recommended way of
providing platform specific overrides is.  Ugly code is ugly code, but
it should at least be homogeneously ugly.

On Thu, Feb 23, 2012 at 11:51 AM, Filip Maj <fi...@adobe.com> wrote:
>
>>I think we can all agree that both of these are not the ideal solution but
>>both work fine for now.
>
> This, in my mind, sums up this thread.
>
> Yes, there are problems and ugliness in cordova-js. However I think we can
> all see the benefit in moving to a unified JS approach where JavaScript
> modules are king.
>
> Initially, yes, there are going to be some platform-specific overrides.
> Are they ugly? Certainly. But let's first get the current fugly
> implementation of cordova-js on all platforms, and then start iterating
> and improving and removing/refactoring platform-specific stuff in the next
> few releases before 2.0.
>
> Once we got it incorporated into Android, we were passing more tests in
> mobile-spec than the previous per-platform JS file implementation. Let's
> make this happen on other platforms, get all of the maintainers and
> committers comfortable with how the project works and is structured, let's
> all use it a little bit, and *then* start reasoning about what the
> problems with it are how to solve them.
>

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[gt...@gmail.com]

+1
Sent on the TELUS Mobility network with BlackBerry

-----Original Message-----
From: Filip Maj <fi...@adobe.com>
Date: Thu, 23 Feb 2012 09:51:21 
To: callback-dev@incubator.apache.org<ca...@incubator.apache.org>
Reply-To: callback-dev@incubator.apache.org
Subject: Re: [DISCUSSION] standard layer to exec : regCommandProxy


>I think we can all agree that both of these are not the ideal solution but
>both work fine for now.

This, in my mind, sums up this thread.

Yes, there are problems and ugliness in cordova-js. However I think we can
all see the benefit in moving to a unified JS approach where JavaScript
modules are king.

Initially, yes, there are going to be some platform-specific overrides.
Are they ugly? Certainly. But let's first get the current fugly
implementation of cordova-js on all platforms, and then start iterating
and improving and removing/refactoring platform-specific stuff in the next
few releases before 2.0.

Once we got it incorporated into Android, we were passing more tests in
mobile-spec than the previous per-platform JS file implementation. Let's
make this happen on other platforms, get all of the maintainers and
committers comfortable with how the project works and is structured, let's
all use it a little bit, and *then* start reasoning about what the
problems with it are how to solve them.

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Filip Maj <fi...@adobe.com>]

>I think we can all agree that both of these are not the ideal solution but
>both work fine for now.

This, in my mind, sums up this thread.

Yes, there are problems and ugliness in cordova-js. However I think we can
all see the benefit in moving to a unified JS approach where JavaScript
modules are king.

Initially, yes, there are going to be some platform-specific overrides.
Are they ugly? Certainly. But let's first get the current fugly
implementation of cordova-js on all platforms, and then start iterating
and improving and removing/refactoring platform-specific stuff in the next
few releases before 2.0.

Once we got it incorporated into Android, we were passing more tests in
mobile-spec than the previous per-platform JS file implementation. Let's
make this happen on other platforms, get all of the maintainers and
committers comfortable with how the project works and is structured, let's
all use it a little bit, and *then* start reasoning about what the
problems with it are how to solve them.

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Gord Tanner <go...@tinyhippos.com>]

1. Exactly.  I would think we should aim to have all javascript above the
exec call to be standard on every platform.  Currently it is at the API
level (which will be how we ship 1.5 due to time / YAGNI).   I would think
our end goal should be to have zero platform overrides (ideally) and for
those that we do have they should be small and surgical.

2. Currently we don't have a good method to test platform specific
overrides, so I would like to limit this code as much as possible.

3.  Exactly.  We have two examples of this at the moment:  A "mixin" type
approch for BlackBerry:
https://github.com/callback/callback-js/blob/master/lib/platform/blackberry.js#L10-22

This is ok but you end up with the end resulting API object spread over a
few files that is combined via black magic and builder trickery.

Next we have what I did in my pull request:
https://github.com/apache/incubator-cordova-js/pull/1

Where I just slam a whole new object on top.

I think we can all agree that both of these are not the ideal solution but
both work fine for now.


On Thu, Feb 23, 2012 at 11:43 AM, Brian LeRoux <b...@brian.io> wrote:

> Can we back up a little? I want to understand, precisely, the problem
> we're looking to solve.
>
> So far the only reasoning I'm inferring is:
>
> 1. separation of concerns not at a high enough level
> 2. testability of cordova-js not atomic enough
> 3. platform specific overrides are too brute force
>
> Am I on the right track?
>
> (Not trying to belay the discussion but I'm seeing a whole lot of
> solution without much clarity on the problems they solve.)
>
>
>
> On Thu, Feb 23, 2012 at 7:18 AM, Gord Tanner <go...@tinyhippos.com> wrote:
> > I am wondering if we should build proxying directly into the exec module.
> >  This would require a generic exec module we would mix in from that would
> > do this for us but I am thinking:
> >
> > var exec = require('cordova/exec');
> >
> > exec.proxy("service", "action", function (success, fail, args) {});
> >
> > I would expect the platform init code to have some way of linking up
> these
> > proxies.  I would prefer it to be handled via convention over
> > configuration, for example via folder structure or file name.
> >
> > so:
> >
> > lib/exec/blackberry/proxy/contacts.search.js
> >
> > On Thu, Feb 23, 2012 at 9:38 AM, Drew Walters <de...@gmail.com>
> wrote:
> >
> >> I'm on the fence as to whether we should provide the higher level
> >> granularity (Service level).  I'm leaning towards only providing
> >> action level granularity because it is more explicit.  I mocked up a
> >> way of defining these in the platform file which follows the pattern
> >> set by the platform objects and would allow for both Service level and
> >> Action level proxies:
> >>
> >> https://gist.github.com/1893077
> >>
> >> The exec would then simply check for Cordova.commandProxies[service]
> >> first and then if not found Cordova.commandProxies[service + action].
> >>
> >> I envision bootstrap taking care of registering the platform proxies.
> >> I don't see a need to unregister.
> >>
> >> On Thu, Feb 23, 2012 at 2:51 AM, Jesse <pu...@gmail.com> wrote:
> >> > I have been giving this some thought, and posted a gist for
> discussion.
> >> >
> >> > https://gist.github.com/1891465
> >> >
> >> > I have not included any of the require/define wrapper api's, as I
> wanted
> >> > the API to be the talking point.  Ideally this would be implemented on
> >> ALL
> >> > platforms and allow us 100% consistency in APIs calling exec.
> >> >
> >> > Dividing responsibilities, we would end up with something like the
> >> > following:
> >> >
> >> > PluginCode ( concrete example compass.js )
> >> > - exposes consistent API for ALL platforms
> >> > - performs parameter checking
> >> >
> >> > ProxyCode
> >> > - performs device specific implementation where native calls are not
> >> needed.
> >> >
> >> > CordovaJS
> >> > - de-couples API specific differences across devices, exec is focused
> on
> >> > being a device specific bridge ( or a bridge with an on-ramp ).
> >> >
> >> > An added benefit to this aproach is that it will provide us a stub
> point
> >> > where we can simulate/hook tests, as currently it is difficult to test
> >> > failing cases ( especially cases that typically should not fail )
> >> >
> >> > Some additional questions that this may bring up:
> >> > 1. do we need lesser/greater granularity of the APIs we want to
> proxy? ie
> >> > should we be able to hook all of Compass with one call, or
> individually
> >> for
> >> > each method?
> >> > 2. do we need to provide an un-register method?
> >> > 3. is there a more descriptive name for this?
> >> >
> >> > Thoughts?...
> >> >
> >> > Cheers,
> >> >  Jesse
> >>
> >
> >
> >
> > --
> > Gord Tanner
> > Senior Developer / Code Poet
> > tinyHippos Inc.
> > @tinyhippos
>



-- 
Gord Tanner
Senior Developer / Code Poet
tinyHippos Inc.
@tinyhippos

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Brian LeRoux <b...@brian.io>]

Can we back up a little? I want to understand, precisely, the problem
we're looking to solve.

So far the only reasoning I'm inferring is:

1. separation of concerns not at a high enough level
2. testability of cordova-js not atomic enough
3. platform specific overrides are too brute force

Am I on the right track?

(Not trying to belay the discussion but I'm seeing a whole lot of
solution without much clarity on the problems they solve.)



On Thu, Feb 23, 2012 at 7:18 AM, Gord Tanner <go...@tinyhippos.com> wrote:
> I am wondering if we should build proxying directly into the exec module.
>  This would require a generic exec module we would mix in from that would
> do this for us but I am thinking:
>
> var exec = require('cordova/exec');
>
> exec.proxy("service", "action", function (success, fail, args) {});
>
> I would expect the platform init code to have some way of linking up these
> proxies.  I would prefer it to be handled via convention over
> configuration, for example via folder structure or file name.
>
> so:
>
> lib/exec/blackberry/proxy/contacts.search.js
>
> On Thu, Feb 23, 2012 at 9:38 AM, Drew Walters <de...@gmail.com> wrote:
>
>> I'm on the fence as to whether we should provide the higher level
>> granularity (Service level).  I'm leaning towards only providing
>> action level granularity because it is more explicit.  I mocked up a
>> way of defining these in the platform file which follows the pattern
>> set by the platform objects and would allow for both Service level and
>> Action level proxies:
>>
>> https://gist.github.com/1893077
>>
>> The exec would then simply check for Cordova.commandProxies[service]
>> first and then if not found Cordova.commandProxies[service + action].
>>
>> I envision bootstrap taking care of registering the platform proxies.
>> I don't see a need to unregister.
>>
>> On Thu, Feb 23, 2012 at 2:51 AM, Jesse <pu...@gmail.com> wrote:
>> > I have been giving this some thought, and posted a gist for discussion.
>> >
>> > https://gist.github.com/1891465
>> >
>> > I have not included any of the require/define wrapper api's, as I wanted
>> > the API to be the talking point.  Ideally this would be implemented on
>> ALL
>> > platforms and allow us 100% consistency in APIs calling exec.
>> >
>> > Dividing responsibilities, we would end up with something like the
>> > following:
>> >
>> > PluginCode ( concrete example compass.js )
>> > - exposes consistent API for ALL platforms
>> > - performs parameter checking
>> >
>> > ProxyCode
>> > - performs device specific implementation where native calls are not
>> needed.
>> >
>> > CordovaJS
>> > - de-couples API specific differences across devices, exec is focused on
>> > being a device specific bridge ( or a bridge with an on-ramp ).
>> >
>> > An added benefit to this aproach is that it will provide us a stub point
>> > where we can simulate/hook tests, as currently it is difficult to test
>> > failing cases ( especially cases that typically should not fail )
>> >
>> > Some additional questions that this may bring up:
>> > 1. do we need lesser/greater granularity of the APIs we want to proxy? ie
>> > should we be able to hook all of Compass with one call, or individually
>> for
>> > each method?
>> > 2. do we need to provide an un-register method?
>> > 3. is there a more descriptive name for this?
>> >
>> > Thoughts?...
>> >
>> > Cheers,
>> >  Jesse
>>
>
>
>
> --
> Gord Tanner
> Senior Developer / Code Poet
> tinyHippos Inc.
> @tinyhippos

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Gord Tanner <go...@tinyhippos.com>]

<self_promotion>

   I may have written a javascript aspecting library before ;)

   https://github.com/gtanner/twill

</self_promotion>

On Thu, Feb 23, 2012 at 11:56 AM, Patrick Mueller <pm...@gmail.com> wrote:

> On Thu, Feb 23, 2012 at 10:18, Gord Tanner <go...@tinyhippos.com> wrote:
>
> > I am wondering if we should build proxying directly into the exec module.
> >  This would require a generic exec module we would mix in from that would
> > do this for us but I am thinking:
> >
> > var exec = require('cordova/exec');
> >
> > exec.proxy("service", "action", function (success, fail, args) {});
> >
>
> I think all the styles currently mentioned allow you to override an exec()
> call, but don't actually allow you to "augment" an exec() call.  Maybe
> that's just not needed.  But the idea is, what if I need to do a little
> something special before/after/both an exec() call?  How do I invoke the
> original exec()?  eg, a "super" call.  Or aspect-y before/after advice.
>
>
> > I would expect the platform init code to have some way of linking up
> these
> > proxies.  I would prefer it to be handled via convention over
> > configuration, for example via folder structure or file name.
> >
>
> Yes, convention over configuration. Convention that is interpreted by the
> stack and executes against an "API".  Not public API (yet).  Most uses
> would just use the convention, but the API is there if you need it, for
> some reason.
>
>
> > lib/exec/blackberry/proxy/contacts.search.js
>
>
> Drew mentioned whether we should hook at the service or service/action
> level.  I assume this example is service/action.  I think for "convention",
> this will be unwieldy if I have a bunch of actions in a service.  Seems
> like "service" is a better fit for "files/modules".
>
> And if those proxies are modules (of course), then the proxy module can
> just export each action as a property/value (function) on the module.
>
> --
> Patrick Mueller
> http://muellerware.org
>



-- 
Gord Tanner
Senior Developer / Code Poet
tinyHippos Inc.
@tinyhippos

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Patrick Mueller <pm...@gmail.com>]

On Thu, Feb 23, 2012 at 10:18, Gord Tanner <go...@tinyhippos.com> wrote:

> I am wondering if we should build proxying directly into the exec module.
>  This would require a generic exec module we would mix in from that would
> do this for us but I am thinking:
>
> var exec = require('cordova/exec');
>
> exec.proxy("service", "action", function (success, fail, args) {});
>

I think all the styles currently mentioned allow you to override an exec()
call, but don't actually allow you to "augment" an exec() call.  Maybe
that's just not needed.  But the idea is, what if I need to do a little
something special before/after/both an exec() call?  How do I invoke the
original exec()?  eg, a "super" call.  Or aspect-y before/after advice.


> I would expect the platform init code to have some way of linking up these
> proxies.  I would prefer it to be handled via convention over
> configuration, for example via folder structure or file name.
>

Yes, convention over configuration. Convention that is interpreted by the
stack and executes against an "API".  Not public API (yet).  Most uses
would just use the convention, but the API is there if you need it, for
some reason.


> lib/exec/blackberry/proxy/contacts.search.js


Drew mentioned whether we should hook at the service or service/action
level.  I assume this example is service/action.  I think for "convention",
this will be unwieldy if I have a bunch of actions in a service.  Seems
like "service" is a better fit for "files/modules".

And if those proxies are modules (of course), then the proxy module can
just export each action as a property/value (function) on the module.

-- 
Patrick Mueller
http://muellerware.org

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Gord Tanner <go...@tinyhippos.com>]

I am wondering if we should build proxying directly into the exec module.
 This would require a generic exec module we would mix in from that would
do this for us but I am thinking:

var exec = require('cordova/exec');

exec.proxy("service", "action", function (success, fail, args) {});

I would expect the platform init code to have some way of linking up these
proxies.  I would prefer it to be handled via convention over
configuration, for example via folder structure or file name.

so:

lib/exec/blackberry/proxy/contacts.search.js

On Thu, Feb 23, 2012 at 9:38 AM, Drew Walters <de...@gmail.com> wrote:

> I'm on the fence as to whether we should provide the higher level
> granularity (Service level).  I'm leaning towards only providing
> action level granularity because it is more explicit.  I mocked up a
> way of defining these in the platform file which follows the pattern
> set by the platform objects and would allow for both Service level and
> Action level proxies:
>
> https://gist.github.com/1893077
>
> The exec would then simply check for Cordova.commandProxies[service]
> first and then if not found Cordova.commandProxies[service + action].
>
> I envision bootstrap taking care of registering the platform proxies.
> I don't see a need to unregister.
>
> On Thu, Feb 23, 2012 at 2:51 AM, Jesse <pu...@gmail.com> wrote:
> > I have been giving this some thought, and posted a gist for discussion.
> >
> > https://gist.github.com/1891465
> >
> > I have not included any of the require/define wrapper api's, as I wanted
> > the API to be the talking point.  Ideally this would be implemented on
> ALL
> > platforms and allow us 100% consistency in APIs calling exec.
> >
> > Dividing responsibilities, we would end up with something like the
> > following:
> >
> > PluginCode ( concrete example compass.js )
> > - exposes consistent API for ALL platforms
> > - performs parameter checking
> >
> > ProxyCode
> > - performs device specific implementation where native calls are not
> needed.
> >
> > CordovaJS
> > - de-couples API specific differences across devices, exec is focused on
> > being a device specific bridge ( or a bridge with an on-ramp ).
> >
> > An added benefit to this aproach is that it will provide us a stub point
> > where we can simulate/hook tests, as currently it is difficult to test
> > failing cases ( especially cases that typically should not fail )
> >
> > Some additional questions that this may bring up:
> > 1. do we need lesser/greater granularity of the APIs we want to proxy? ie
> > should we be able to hook all of Compass with one call, or individually
> for
> > each method?
> > 2. do we need to provide an un-register method?
> > 3. is there a more descriptive name for this?
> >
> > Thoughts?...
> >
> > Cheers,
> >  Jesse
>



-- 
Gord Tanner
Senior Developer / Code Poet
tinyHippos Inc.
@tinyhippos

Re: [DISCUSSION] standard layer to exec : regCommandProxy

[Drew Walters <de...@gmail.com>]

I'm on the fence as to whether we should provide the higher level
granularity (Service level).  I'm leaning towards only providing
action level granularity because it is more explicit.  I mocked up a
way of defining these in the platform file which follows the pattern
set by the platform objects and would allow for both Service level and
Action level proxies:

https://gist.github.com/1893077

The exec would then simply check for Cordova.commandProxies[service]
first and then if not found Cordova.commandProxies[service + action].

I envision bootstrap taking care of registering the platform proxies.
I don't see a need to unregister.

On Thu, Feb 23, 2012 at 2:51 AM, Jesse <pu...@gmail.com> wrote:
> I have been giving this some thought, and posted a gist for discussion.
>
> https://gist.github.com/1891465
>
> I have not included any of the require/define wrapper api's, as I wanted
> the API to be the talking point.  Ideally this would be implemented on ALL
> platforms and allow us 100% consistency in APIs calling exec.
>
> Dividing responsibilities, we would end up with something like the
> following:
>
> PluginCode ( concrete example compass.js )
> - exposes consistent API for ALL platforms
> - performs parameter checking
>
> ProxyCode
> - performs device specific implementation where native calls are not needed.
>
> CordovaJS
> - de-couples API specific differences across devices, exec is focused on
> being a device specific bridge ( or a bridge with an on-ramp ).
>
> An added benefit to this aproach is that it will provide us a stub point
> where we can simulate/hook tests, as currently it is difficult to test
> failing cases ( especially cases that typically should not fail )
>
> Some additional questions that this may bring up:
> 1. do we need lesser/greater granularity of the APIs we want to proxy? ie
> should we be able to hook all of Compass with one call, or individually for
> each method?
> 2. do we need to provide an un-register method?
> 3. is there a more descriptive name for this?
>
> Thoughts?...
>
> Cheers,
>  Jesse