[aerogear-dev] Pipe spec

[Summers Pittman]

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.

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.

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.

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

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.

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.


Summers