Where to put demo / sample code of a maven built library?

Question

I develop a little java utility library using maven. Now I'd like to add some demo / sample code to show how to use the library.

Where is the best place to put it?

• In a sub-package with the other code. I don't like this since it means the demos will be included in the library jar file.

• In a new maven artifact. That works, but I'd prever to have the demos closer connected to the library source.

• As a sub-artifact. Haven't tried this yet. Seems to make everything a bit complex for something that should be simple.

Is there any common pattern to do this?

Answer 1

If it's some sample code snippets that run by themselves and just demonstrate how to use the library, then write them as unit tests, in the same module.

If it's more like a separate demo application (that a user might even interact with), then create a separate artifact. It's the standard way of doing it. If you really want to you could put it in the same module, but in a different source directory, but that's just making it harder on yourself.

Your library and you demo should probably share a parent module (of type "pom", not "jar" like the others), giving you a multi-module project. Then you can build both by launching maven from this parent module.

If you want to release your library and demo together (you can, but you don't have to), you can do that from the parent too.

In other words, it's not because they are separate modules, packaged in different artifacts, that they cannot be closely connected anymore. The different modules of a multi-module project still form one whole project.

Answer 2

You hadn't written what kind of utility library it is, but if it's something like apache commons, then most of the demos can be written as JUnit tests, which are placed in the same artifact. Good designed JUnit tests both tests your code and provide example how to use your utilities.