[aerogear-dev] Pipe spec

Tue Apr 23 11:15:50 EDT 2013

On Apr 23, 2013, at 9:17 AM, Summers Pittman <supittma at redhat.com> wrote:

> On Tue 23 Apr 2013 07:34:03 AM EDT, Kris Borchers wrote:
>> Summers,
>> 
>> I agree, great writeup. I just posted a line comment on one of the
>> commits but before I started doing that all over the place, I thought
>> I would ping you here first. Basically, I think there is too much
>> detail in much of this for it to be an abstract spec. At least in JS
>> land, many of the parameters passed to functions, the relationship of
>> Pipeline to Pipe and a number of other things are just very different
>> from Android. They even differ from iOS, but seem much closer there
>> than to Android.
>> 
>> If you want, I can go line by line and point out these differences, or
>> would your rather just try to make a run through it and generalize it
>> a bit more without all of the noise? I am happy to go either way.
> 
> I would prefer you call out specific instances.  I checked the 
> Javscript code and the spec describes what it does pretty closely.  
> With the exception of handler (which will be excised on my next push) 
> and the names I've chosen for certain things (what you call settings I 
> call PipeConfig) I don't find anything terribly specific/not applicable 
> to JS.

I guess that's my point though and it looks like you fixed it. As a new user, calling something PipeConfig would lead me to look for that in the API docs and when I don't see it, I would be lost. I guess I just want this to be as general as possible to avoid confusion. Saying "a configuration object" is much preferred to "PipeConfig".
> 
>> 
>> Thanks,
>> Kris
>> 
>> On Apr 23, 2013, at 4:03 AM, Matthias Wessendorf <matzew at apache.org
>> <mailto:matzew at apache.org>> wrote:
>> 
>>> 
>>> 
>>> 
>>> On Mon, Apr 22, 2013 at 6:37 PM, Summers Pittman <supittma at redhat.com
>>> <mailto:supittma at redhat.com>> wrote:
>>> 
>>>    On 04/22/2013 12:45 AM, Douglas Campos wrote:
>>>> On Fri, Apr 19, 2013 at 08:04:12AM -0400, Summers Pittman wrote:
>>>>> So I've gotten a draft of the Pipe document up.
>>>>> 
>>>>> 
>>>    https://github.com/aerogear/aerogear.org/blob/pipe_spec/docs/specs/aerogear-client-pipe/index.markdown
>>>>> 
>>>>> Some things I would like to call out and discuss include
>>>>> 
>>>>> 1 ) Pipe implementations should be thread safe.  Specifically
>>>    calls to
>>>>> read, remove, and save should not change the internal state of
>>>    a Pipe
>>>>> object.
>>>> +1
>>>> 
>>>>> 2 ) Pipeline.get is not guaranteed to always return the same
>>>    instance
>>>>> of a Pipe.  This is something that came up with Android.
>>>     Loaders are
>>>>> 1:1 on the Activity or Fragment which references the Loader.
>>>>> Therefore if a Pipe is reused between multiple Activities each
>>>    one is
>>>>> proxied  in a different Loader.
>>>> Why should we spec this? People counting on getting the same
>>>    instance on
>>>> year 2013...
>>>    I just feel like it is one of those things that if we don't say
>>>    up front
>>>    people may rely on it.
>>>> 
>>>>> 3 ) A Pipe may proxy or delegate to a handler and this handler
>>>    can be
>>>>> exposed as a property.  This is an Androidism as well.  I
>>>    think it can
>>>>> probably be dropped from the spec but I wanted to see what other
>>>>> people thought about it.
>>>> +1 on dropping, this just adds complexity, and complex specs ==
>>>    boring
>>>> read
>>>    Will do.
>>>>> Some things which we may need to flesh out to make the spec more
>>>>> complete are
>>>>> 
>>>>> 1 ) Authorization and Authentication.  This is probably another
>>>>> document
>>>> We can probably just spec the Authentication/Authorization SPIs
>>>    (very
>>>> thin API surface)
>>>    So a separate doc then?
>>>> 
>>>>> 2 ) A callback spec/definition.  I am not sure whether this is a
>>>>> separate document or not.  Either way it should be short and
>>>    sweet.
>>>> Wdym? Could you elaborate more?
>>>    We need to put down in writing Callback.onSuccess(result) and
>>>    Callback.onFailure(cause) because it is used everywhere.
>>>> 
>>>>> 3 ) Platform implementation docs.  A document with the code
>>>>> examples/comparisons and notes where they may diverge from
>>>    each other.
>>>>> For instance in Android Callback is passed instances of the
>>>    resource a
>>>>> pipe represents, but in iOS and Javascript the callback is
>>>    passed a
>>>>> map of values.  I didn't explicitly define this behavior in
>>>    the spec.
>>>> Isn't having the parallel usage examples enough? (kinda like we
>>>    did on
>>>> the paging spec)
>>>    Pretty much, I was just wondering if people were interested in
>>>    having a
>>>    Map behavior as a standard, leaving it to the implementation, or
>>>    doing
>>>    something else (like returning Headers and Body information)
>>> 
>>> 
>>> 
>>> I agree, coming from java, the map thing _is_ weird :) but that's
>>> what a lot of folks do, in iOS land.
>>> I guess... we could spec this - but also keeping it abstract, not
>>> really sure, to be honest
>>> 
>>> 
>>>> 
>>> 
>>>    _______________________________________________
>>>    aerogear-dev mailing list
>>>    aerogear-dev at lists.jboss.org <mailto:aerogear-dev at lists.jboss.org>
>>>    https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>> 
>>> 
>>> 
>>> 
>>> --
>>> Matthias Wessendorf
>>> 
>>> blog: http://matthiaswessendorf.wordpress.com/
>>> sessions: http://www.slideshare.net/mwessendorf
>>> twitter: http://twitter.com/mwessendorf
>>> _______________________________________________
>>> aerogear-dev mailing list
>>> aerogear-dev at lists.jboss.org <mailto:aerogear-dev at lists.jboss.org>
>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>> 
>> 
>> 
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
> 
> 
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev