Looking at this pull request and the related discussion:
- the Pipe interface is the only access that endusers should have to a pipe.
- the RestAdapter is a HTTP RESTful implementation of the Pipe.
- Endusers should not be able do do
new RestAdapter(...);
Looking at the discussion of the above PR, it's clear that there exposing internal APIs and/or implementation details has PROs and CONS...
- It's BAD because it leaks API and once endusers start using it... you are lost (and need to support it ...)
- Exposing the internal API makes the library more flexible on the other hand
If someone wants to implement a bit different marshalling / unmarshalling they would have to use a slightly different (new) implementation, since the class is not exposed... So they would copy/paste the entire class and simply change the details they want to change... Of course that's a valid complain about bad design that they can't simply extend the library.
It would be good if there is an SPI on the library where customers/endusers could register their "RESTFull Pipe implementation". It would be also cool if we could offer some abstract API (AbstractPipeAdapterClient) which is flexible enough that endusers can extend from that without the need to mess around with our internal
API (e.g. RestAdapter).
We we introduce these things,we can keep our implementation details for us... but still we are giving the enduser an api to EXTEND from an abstract BASE, and they can register that for certain "transports"...
For the extensibility of the Adapters would using ServiceLoader be an option? Not sure if we have limitations on java versions here but might one way of gaining the extensibility we want. This should make it possible to simply add a new jar containing an adapter(factory) and the client just specifies it wants that new type as the adapter to be used, for example when adding a new pipe to the pipeline.