WebSocket client API

[Andrej Golovnin]

Hi Pavel,

the JavaDocs for the method
HttpClient.Builder#proxy(java.net.ProxySelector selector) say:

Sets a ProxySelector for this client. If no selector is set, then no
proxies are used. If a null parameter is supplied then the system wide
default proxy selector is used.

Really? For me it means that nearly every application which would like
to use the new HttpClient/WebSocket must call this method with null
value. Just think about Java WebStart applications and applets: you
never know if there is a proxy or not.

IMHO the JavaDocs for this method should look like this:

Sets a ProxySelector for this client. If no proxy selector is set,
then the system wide default proxy selector is used.

@throws IllegalArgumentException if selector is null.

I'm sure the most developers out there should be able to provide their
own implementation of the java.net.ProxySelector class which just
returns Collections.singletonList(Proxy.NO_PROXY) in the method
ProxySelector#select(URI uri) if they need direct access to a server.
And if you would like to simplify the life of the developers which
need a direct access to a server, then you could add a new method to
the builder:

HttpClient.Builder#noProxy()

I think it is better than to add a special meaning to the null value.

And I think that the phrase with "If no proxy selector is set, then
the system wide default proxy selector is used." should be a part of
the JavaDocs of the class HttpClient.Builder and the method
HttpClient.getDefault() to make clear the behaviour of the
created/returned HttpClient.

Best regards,
Andrej Golovnin