Should you provide dependent libraries in client jar?

We're providing a client jar for other internal apps to connect to our app's REST API. Our API depends on a few standard Jakarta libraries. Is it a best practice to include those JAR files within our client jar file? Or do you just document the dependencies and it's up to the clients to ensure they have those jars on their classpath?

You should not bundle the any third party jars into your own jar as an uber jar, but it would be good to include a copy of all the jar's that are required in your distribution say in a lib directory or what ever.

The main reason for this is that your clients may be using some form of dependency management system (maven/ivy etc) and providing packages and classes that don't actually belong to your project will invalidate these schemes.

There is one alternative and that is to use something like the maven shade plugin to relocate your dependencies into your own package namespace. This of course has the down side that you will increase the code size of your library but on the up side you can almost guarantee the versions of your dependencies with out effecting any other libraries your clients may be using.

EDIT: in response to Marcus Leon comment:

Possible solutions with out bundling/relocating:

• Documentation, make sure you document your dependencies and any known conflicts with previous versions - nobody actually reads it
• Distribute you library via a dependency managed system... like a maven or ivy repo, these allow you to document in a very specific set of bounds (including upper) what your dependencies are - can still be overridden just your clients will know that they are doing it
• Add OSGi information in the MANIFEST.MF - only useful if your clients actually use OSGi
• If your dependencies have been built using maven or have version information in there manifest files you could write some sort of checking routine that scans the classpath for these and checks there versions - a bit extreme

In the end it is extremely hard to actually ensure you have the dependencies you want as java is a late bound language it is possible to have your dependencies (even if bundled) overridden by somebody including a different version before yours on the classpath.

Note: I've recently spent a very bad day trying to find out why one of our apps failed to find a new version of log4j. the cause: somebody trying to be helpful had bundled it into a random completely unrelated jar.