Skip to content

Open Liberty naming guidelines

Jump to bottom
Chuck Bridgham edited this page May 31, 2022 · 43 revisions

ALL NEW Open Liberty artifacts MUST follow the same naming conventions

API - io.openliberty.xxx

SPI - io.openliberty.xxx.spi

Internal - io.openliberty.xxx.internal

Exceptions and Clarifications

Within reason, this applies to everything. e.g.

  • Java packages
  • Project names
  • OSGi Bundle names
  • FATs
  • API/SPI jar names
  • Feature names (long)
  • Liberty Configuration PIDs
  • System properties
  • Maven artifact IDs

xxx is a short component name. It may be composed of multiple elements (xxx.yyy).

Ideally, xxx is the short name for the external feature, including its version. Project, bundle and jar names should include the that feature version but use a dot rather than a dash (example-1.0 -> example.1.0). A Java package name would normally omit the version as package versioning is done by other means.

These guidelines are most important for user visible elements such as API/SPI Java Packages and Jars. There is flexibility when it comes to internals but it is important to maintain consistency.

Private API Features

Many of the API jars shipped in Liberty are included in private Liberty features. This allows other Liberty features to require the API as needed while still keeping the API packages as an internal implementation detail. Only when a public or protected feature is enabled that specifies the package is API or SPI is the package available at runtime to applications and/or product extensions. Private feature names are not as important as the public or protected feature names because they can be freely change without breaking Liberty externals but consistency should be used to make it less confusing. New private API features should use a name that follows the scheme:

io.openliberty.<tech name>.api-<version>

For example the feature that includes the Jakarta EE Servlet version 5.0 packages would be io.openliberty.servlet.api-5.0. The issue #13703 is tracking the work to rename our existing private API features to use this naming scheme.

Examples

It is difficult to cover all the possible variations but here some examples.

A brand new Open Liberty feature called example-1.0 would have the following;

Features

  • Public & Protected
    • Short name = example-1.0
    • Long name = io.openliberty.example-1.0
  • Private
    • API feature = io.openliberty.example.api-1.0
    • Internal feature = io.openliberty.example.internal-1.0
  • Auto Features
    • Version specific = io.openliberty.exampleOne1.0-exampleTwo5.0
    • Multi-version = io.openliberty.exampleOne-exampleTwo

Java Packages

  • API = io.openliberty.example
  • SPI = io.openliberty.example.spi
  • Internal = io.openliberty.example.internal

Projects & Bundles

Where possible, the OSGi bundle symbolic names should be the same as the project name on disk.

  • Open Liberty API = io.openliberty.example.1.0
    • Maven Coordinates = io.openliberty.api:io.openliberty.example:1.0.40 (40 is the release minor version)
  • Open Liberty SPI = io.openliberty.example.1.0.spi
    • Maven Coordinates = io.openliberty.spi:io.openliberty.example.spi:1.0.40 (40 is the release minor version)
  • Internal = io.openliberty.example.1.0.internal
  • Internal = io.openliberty.example.1.0.internal.subname
  • Internal common component = io.openliberty.mycomponent.internal
    • The name of the common component is mycomponent.
    • It is used internally by multiple features.

Third party projects & (re)bundles

  • Spec API = io.openliberty.jakarta.newspec.2.0
  • Rebundling of an open source library = io.openliberty.org.acme.widget
    • Does not have a version in the name. This makes it easier to upgrade the library later on.
    • It should not contain additional integration code.
    • It should be re-useable by multiple components.
  • Third Party API = io.openliberty.example.1.0.thirdparty
    • This is a rebundling of a third party API as part of the example-1.0 feature. Ends up in wlp/dev/api/third-party.
    • It should only contain the API classes we wish to expose. It should not contain implementation classes. May be a sub-set of the classes provided by the original open source library.
    • Does not contain the actual name or version of the third party API, only that of the feature. Again, this makes it easier to upgrade in the future.

FATs

In general, FAT names should follow the bundle name with a suffix of _fat added. So if the bundle name is io.openliberty.example.1.0.internal, then the preferred FAT name would be io.openliberty.example.1.0.internal_fat.

  • Exceptions can be made if there are already others that follow the old convention.
    • e.g. if you already have com.ibm.ws.xyz.part1_fat then it might make sense to stick to com.ibm.ws.xyz.part2_fat rather than switching to io.openliberty.xyz.internal.part2_fat.
    • Please ask for clarification if you are uncertain which naming convention to use.

Exceptions and Clarifications

To be clear, these guidelines are for "new" versions of bundles and features where appropriate. If adding a new config property to an existing bundle where "com.ibm.ws" was used - for consistency, the old naming convention would be used. If something is not clear or you believe that an exception should be made, please ask before delivery. Contact either the Release Architect (Michal Broz) or one of the Development Leads (Chuck Bridgham and Tom Evans).

MicroProfile Example

  • Feature short name = mpNewSpec-2.0
  • Feature long name = io.openliberty.mpNewSpec-2.0
  • MicroProfile API project/bundle = io.openliberty.org.eclipse.microprofile.newspec.2.0
  • Internal implementation project/bundle = io.openliberty.microprofile.newspec.2.0.internal
  • External OSS library project/bundle = io.openliberty.io.smallrye.acme

An example project for an API bundle & jar might look like this;

dev/io.openliberty.example.1.0/
   src/io/openliberty/example/Example.java

An example SPI;

dev/io.openliberty.example.1.0.spi/
   src/io/openliberty/example/spi/ExampleSPI.java

An implementation bundle;

dev/io.openliberty.example.1.0.internal/
   src/io/openliberty/example/internal/ExampleImpl.java
   test/io/openliberty/example/internal/test/ExampleTest.java

Another implementation bundle;

dev/io.openliberty.example.1.0.internal.subname/
   src/io/openliberty/example/internal/subname/ExampleImpl.java
   test/io/openliberty/example/internal/subname/test/ExampleTest.java
Clone this wiki locally