How to create and publish a useful Java library

Question

I've recently worked on a Java class that generates permutations per list of objects. In any case, I would like to have this library offered to the public, so I have several questions:

• Most libraries I see have this complicated package naming, specifically including com/org. Is there a convention for these or is a permutations package enough?
• Is there a specific format to publish these? Should I include separate WARs for source code / javadoc?
• I have the files on a GitHub repository. I guess I can serve the files there, but how do I get people to find my repo?

Answer 1

• A standard way to publish (apart from the source code on GitHub) is to have formal JAR/WAR releases to Maven Central which many (Maven, Gradle, Ant/Ivy) build tools use to bring in libraries as a dependency. To do this, the best way is to go through the Nexus process.

• It's also considered friendly to host those same JAR/WARs on a code hosting repo such as Sourceforge or GitHub.

• In terms of your domain. I recommend you buy firstnamelastname.net/org/com and use that as your naming scheme (e.g. for me it's net.martijnverburg.foobar). Otherwise using the github domain as suggested by @Daniel Moura is a good one.

• To publicise it, blog about it, twitter about it, submit it to hacker news, reddit, digg, slashdot, dzone, TSS, javaworld etc

HTH!

Answer 2

If you've pushed your code to GitHub then sharing your library (jar) is easy with JitPack.

Your users will just need to add the repository to their build.gradle:

repositories {
    mavenCentral()
    maven { url "https://jitpack.io" }
}

and then your GitHub repository as a dependency:

dependencies {
    // ...
    compile 'com.github.YourUsername:Repo:Release'
}

JitPack acts as a maven repository similar to Maven Central. The nice thing is that you don't have to upload your library. Behind the scenes JitPack will check out the code from GitHub and compile it. As you publish a new release on GitHub it becomes available for others to use.

There is also a guide on how to prepare a project and examples for adding a sources jar.

It isn't required to have a domain name so your groupId becomes com.github.Username. You could also use that for package naming.

Answer 3

Most libraries I see have this complicated package naming, specifically including com/org. Is there a convention for these or is a permutations package enough?

There are recommendations from Oracle on how to name your packages. The reason for this naming convention is to minimize duplicates. If everyone simply used short, simple names, it becomes more likely that a project will include two permutation packages. If one class name was the same, there would be naming conflicts. Things can get confusing for the developer, if there are't naming conflicts that prevent resolution of the classes.

If you have a domain name, I would suggest using that. If you are hosting on a service such as GitHub or Sourceforge, using the path to your project would be sufficient as well. Regardless, be explicit to prevent conflicts or confusion.

Is there a specific format to publish these? Should I include separate WARs for source code / javadoc?

There's no specific format. At the very least, source and a convention build script (Make, Ant, Maven). It's nice to have precompiled JARs or WARs, but not essential. Some projects include the Javadoc in the library, others might produce two JARs (one with Javadoc and one without). It might also be a good idea to simply publish your Javadoc on the Internet if your project hosting solution allows for it.

I have the files on a GitHub repository. I guess I can serve the files there, but how do I get people to find my repo?

Advertise it. Start by showing it off to a few friends. Blog about it. Share a link on the Internet. Find someone who has a problem that they can solve using this library (but make sure you disclose that you made the library).