API must allow protocol extensions to add new invocation types, e. g. propfind() and search()
> -----Original Message-----
> From: Marek Potociar [mailto:marek.potociar_at_oracle.com]
> Sent: Mittwoch, 13. Juli 2011 15:30
> To: jsr339-experts_at_jax-rs-spec.java.net
> Subject: [jsr339-experts] Client API requirements
>
> Hello Experts,
>
> apparently, when looking at our EG mailing list, the last week was a
> very active one, especially when it comes to the
> client API discussions. I wish I was not on a vacation - it took me 2
> days to read through all the messages! :)
>
> Until now, I thought that having the API requirements captured in Jira
> issues is good enough. However, while reading
> those new messages it became obvious that having the requirements
> listed explicitly would be very useful so that we can
> use the requirements list to asses any new proposals.
>
> Let's now take a small step back and try to agree on the main
> requirements for the client API. I have made an attempt to
> compile all the main requirements from Jira as well as from the recent
> emails into a concise list[1]. Before we continue
> any further discussion on the Client API, please have a look at the
> list, review it and send me your feedback.
>
> Thank you,
> Marek
>
> [1]: Client API requirements
>
> - API must support creating & invoking a request and consuming a
> response
> : Create arbitrary requests using Client instance
> : Create multiple requests to a single resource (simpler, less
> verbose) using Link instance
>
> - API must support batch request processing
> : Process multiple arbitrary requests using a uniform interface with
> sync & async support
>
> - API must support sync and async invocations
> : Users must be able to send requests and retrieve responses both
> synchronously as well as asynchronously
>
> - API must provide a configuration support
> : Properties, features, filters & handlers of each request must be
> configurable
>
> - API must support configuration inheritance and scoping
> : Configuration must be supported at multiple levels - global
> (Client), resource-specific (Link), request specific
> (Invocation)
> : Configuration from the parent component is inherited by the child
> component
> : Configuration of a child component is detached from parent; once a
> child component is created, subsequent changes in
> the parent component configuration have no effect on the configuration
> of the child component and vice versa.
>
> - API must support injection of resource clients (Links)
>
> - API must support custom implementations & extensions
> : Users must be able to provide as well as choose a specific (custom)
> implementation of the Client API
>
> - API must support multiple implementation and/or implementation
> versions running in a single container at the same time
>
> - API must eliminate possibility to write illegal constructs in the
> fluent API
> : e.g. invocation.method("PATCH").get();
>
> - API must allign well with the IDE code-completion
> : the IDE code completion should be able to provide relevant hints
> for the fluent API based on the context
> : e.g. once the entity was set, the IDE would not list the entity()
> method in the fluent method invocation chain code
> completion again (this is an illustrative example, not satisfiable with
> the current API)