Travelling through time & space in real-time...

How Including a Bintray Maven Repository in JCenter Works Under the Hood

The inner workings of Bintray’s Maven repositories and their inclusion into JCenter are a bit nebulous, but with a few undocumented cues the whole system is actually pretty straightforward and easy to understand.

Introduction to Bintray Packages

Bintray allows you to create multiple Maven repositories, the default repository is simply called maven. At its core, such a repository is the same as any other Maven repository, a directory tree whose structure and files follow a specific pattern specified by Maven. To manage a repository, Bintray adds an artificial and sometimes complicated layer around the files: packages to group a software module and its artifacts together, and versions that group the actual artifacts of a specific release version together. This is all pretty straightforward when uploading artifacts manually through the website, because files are uploaded into a version and therefore automatically assigned to the correct package.

The complication starts when artifacts are uploaded automatically through the API with the help of a tool like Maven itself or a Gradle plugin, which surely is the developer’s preferred way. A Maven artifact is identified by a tuple of group ID, artifact ID, and version (e.g. org.apache.commons, commons-collections4, 4.0), while a Bintray package is only identified by its name. If artifact ID and package name match, the artifact is automatically assigned to the package and its corresponding version, else a new package named after the artifact ID is created and needs to be manually merged into the package where it belongs (e.g. artifacts videoplayer-java and videoplayer-android need to be merged manually into package videoplayer). A package can contain multiple artifacts of arbitrary group and artifact IDs.

So why do packages exist at all? They are a way to logically group software artifacts that belong together and assign common metadata, e.g. a description, license information and an icon. This way software packages are represented to users on the website, and it is recommended if you want to publish software in a helpful way. The whole concept of packages can be ignored if the repository is just used as intended by Maven, because this concept does not exist in Maven as you do not access packages but only the root repository itself. Another case where dealing with packages is required is the distribution of software through the JCenter repository.

Including a Package in JCenter

To include a software package in JCenter, you need to group all its artifacts into a package and request for inclusion. If everything goes right, your software will be available in the JCenter repository a few hours later. You might now think that your package is included into JCenter, but what the Bintray documentation does not tell you is that actually only a subset, specified by an inclusion path serving as a filter, is included into JCenter. So at this point the artificial management layer in the form of packages is actually left for another concept. This filter path will usually correspond to the common group ID of the artifacts in your package. When adding artifacts outside this filter path, or renaming the group ID, they will therefore not show up in JCenter.

To include renamed artifacts into JCenter, Bintray support suggests creating a new package and requesting its inclusion. I found it to be a nice pattern create a new package as mypackage-new, and after inclusion rename the old package from mypackage to mypackage-legacy and the new one from mypackage-new to mypackage. This way, the package name and URL in the JCenter library stay the same and always point to the newest version of your software package.


There are no comments.

Leave a Reply