38

I have googled around quite a bit still am confused as to what each of the above exactly mean.

Here is my understanding of it:

  • jaxrs-api : contains only api. No implementation. But how is it different from JSR311
  • jsr311-api : JSR311 it is a specification request. Which means it is supposed to be a document. Why then is it a jar?
  • javax.ws.rs-api: Is it an implementation?
  • jersey-core(/jersey client): Is an implementation of JSR311.

I downloaded each jar and tried to decompile and see what is inside it, but I am only able to find interfaces in all of them and not the implementation.

I am facing these questions in the context of duplicate warnings generated by maven shade plugin, and need proper understanding of the above to figure out which ones to exclude and why.

1 Answer 1

63

I'll first get to the question

"JSR311 it is a specification request. Which means it is supposed to be a document. Why then is it a jar?"

Except the last (jersey-core), all those jars are "specification" jars. The JAX-RS (as well as many other Java) specifications define contracts (or interfaces) that implementators should implement the specified behavior for.

So basically all the classes specified in the specification should be in the jar as contracts. End users of the jars can use them for the contracts. but there is no implementation. You need to have an actually implementation to run the application, though the spec API jar is enough to compile a complete JAX-RS compliant application.

For example, if we have one of those spec API jars on the classpath, we can author an entire JAX-RS application and compile it, but in order to run it, if we don't have the actual implementation, we need to deploy to a server that has the actual implementation of that spec version, for example JBoss or Glassfish


  • jaxrs-api - This is RESTeasy's packaging of the spec. It is not the official spec jar, but it does adhere to the spec contracts. RESTeasy uses this jar for the entire spec line, i.e. 1.x - current. Though the jar does change internals to adhere to the different JAX-RS versions.

  • jsr311-api - This is the official spec jar for the JAX-RS 1.x line.

  • javax.ws.rs-api - This is the official spec jar for the JAX-RS 2.x line.

  • jersey-core - This is a partial implementation of the spec. The rest of the implementation is contained inside other Jersey jars. Note that in earlier versions of Jersey, they actually packaged the JAX-RS spec APIs into this jar. It wasn't until later that Jersey started using the official spec jars.

  • jaxrs-ri - This is the complete Jersey 2.x implementation packaged into one jar. The "ri" mean reference implementation, which is what Jersey is: the JAX-RS reference implementation. If you are not using a dependency manager like Maven, you might want to just use this single jar instead of having to use all the separate jars that Jersey comes with.

Other Resources

Also note that though different implementation adhere to the spec, each implementation has its own set of extra features. To learn more you should go through the documentation of the different implementation. The three most popular implementations are Jersey, RESTeasy, and CXF

8
  • 1
    Thanks for the reply. So JSR311 is the 'Speification Request'; its corresponding 'Specification API' is jsr311-api; And these and they form the JAX-RS 1.x line. Now, JSR339 is the next 'Specification Request'; its 'Specification API' is 'javax.ws.rs-api' and they form JAX-RS 2.x line. Am i correct? If so, is there an overlap between JAX-RS 1.x and JAX-RS 2.x lines? Would they give a 'maven shade duplicate class warning' if used together? Out of jsr311-api, javax.ws.rs-api, and jaxrs-api is there a best one to use?
    – Gadam
    Aug 20, 2015 at 16:44
  • That's pretty much the gist of it. And yes are are overlapping classes. 2.x really just adds on to 1.x. I can't think of anything off the top of my head that was removed in 2.x. Aug 20, 2015 at 16:47
  • 1
    I mean it really depends on your needs. I personally prefer to use the 2.x line, simply because I use Jersey 2, which has a bunch of features, but if you want to compares just the standard API, 2.x has filters and interceptors, async support, bean validation, and probably more things I can't think of right now Aug 20, 2015 at 16:51
  • 3
    Also note that if you are using Maven, you rarely ever have to have an explicit dependency on any of the spec jars. Whatever implementation you are using will pull it in. If you are deploying to an EE server, and you wan to stick strictly to the spec (to stay portable), then you should only need the javaee-api jar. Also note that if you are using a 2.x implementation and you have a 1.x jar on the classpath, you are likely to get NuSuchMethodErrors. The major API versions are not compatible. Aug 20, 2015 at 17:14
  • 2
    Note that the JAX-RS 2.x line has moved to jakarta.ws.rs-api, starting with 2.1.2. 3.0.0 has also been released, and no longer features Jersey as the fallback implementation. Nov 21, 2020 at 23:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.