eclipse-ee4j / eclipse-ee4j/jersey

Document thread-safety.

Open
#3,366 5 comments 4 reactions 0 assignees View on GitHub
Component: core Component: docs Component: examples Priority: Major Type: Improvement
Dominant language
Java
Stars
730
Forks
382
PR merge metrics
No merged PRs in 30d

Description

[Jersey 2.0's user guide](http://repo1.maven.org/maven2/org/glassfish/jersey/jersey-documentation/2.0/jersey-documentation-2.0-user-guide.pdf), section "7.4.1\. Configuring a Client and WebResource", had this to say:

> Client instances are expensive resources. It is recommended a configured instance is reused for the creation of Web resources. The creation of Web resources, the building of requests and receiving of responses are guaranteed to be thread safe. Thus a Client instance and WebResource instances may be shared between multiple threads.

Since [user guide of 2.1](http://repo1.maven.org/maven2/org/glassfish/jersey/jersey-documentation/2.1/jersey-documentation-2.1-user-guide.pdf), this notion of thread-safety has been removed. Confirmed to be missing in version [2.22.2](http://repo1.maven.org/maven2/org/glassfish/jersey/jersey-documentation/2.22.2/jersey-documentation-2.22.2-user-guide.pdf) as well.

Thread-safety is not documented by JAX-RS either, whether that be [JavaDoc](https://jersey.java.net/apidocs/2.22.2/jersey/javax/ws/rs/client/Client.html) or [specification](https://jcp.org/en/jsr/detail?id=339). But me personally, I am not too surprised and I am all out of tears.

I think that all "serious" programmers can vouch for the extreme importance not to disregard thread-safety. Or alternatively, we can let developers all over the world waste time by possibly re-invent the wheel if Jersey is thread-safe, or we can let developers all over the world use Jersey in an inefficient manner by not cache Jersey artifacts other than as local variables ([example](https://github.com/jimmoores/quandl4j/blob/master/src/main/java/com/jimmoores/quandl/QuandlSession.java#L148) from a real-world financial app that obviously is a lot slower than what it needs to be), or, this issue can be fixed =) I don't see any other option?

Please note that not documenting one of the most fundamental questions a library user will get is cause for real-life drama as evident by googling the topic, for example this [Stackoverflow tread](http://stackoverflow.com/q/18078666/1268003).

Finally, thank you for your hard and much appreciated work.
#### Environment
Environment independent.
#### Affected Versions
[2.1, 2.22.2]

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.