designations.adoc

Designations of Hibernate contracts

This document aims to classify the Hibernate contracts (classes, interfaces, methods, etc) into a number of designations meant to indicate the level of "stability" of the contract. Stability here means the expectation applications should have with regard to that contract’s binary signature compatibility moving forward. To that end, we designate a contract within a number of categories as described below.

The designations

internal

Contracts deemed internal carry no guarantees with regard to stability. They are considered contracts internal to Hibernate and their signatures may change at any time. + Unless otherwise designated, contracts are considered "internal"

api

Contracts designated as api (API) have strong stability guarantees. An API is a contract we fully expect application code to bind to in the binary sense (e.g. the Session). + API contracts are guaranteed to be stable for 1 major release (e.g. all 5.x releases). API contracts are changed only in rare cases + API contracts can be removed after 1 major release of deprecation

spi

Contracts designated as spi supply a service of some kind to Hibernate. SPI contracts fall into a number of "groups" based on the type of service performed:

• caching - RegionFactory (second-level caching) implementation

• connections - ConnectionProvider implementation

• dialect - Dialect implementation

• container - Support for running inside WildFly and OSGi containers

• transaction - TransactionCoordinatorBuilder implementation

• jta - JtaPlatform implementation

• beans - BeanContainer implementation

• bytecode - BytecodeProvider implementation

• query - QueryTranslator implementation

• jndi - JndiService implementation

• jmx - JmxService implementation

• id - IdentifierGenerator implementation

• …​ + SPI contracts are guaranteed to be stable within a release family. Every effort possible is made to try to make an SPI just as stable as API, but sometimes the design of an SPI itself might be the bug or implementation of new features might require an SPI change. + SPI contracts can be removed after 1 major release of deprecation

provided

Contracts designated as provided are specialized SPI contracts in that they are provided by Hibernate to the service being implemented. In other words, Hibernate is the one implementing the specific SPI contract and is free to add methods to that contract. Other than adding methods, the stability guarantees are the same as for spi contracts + Provided contracts can be removed after 1 major release of deprecation

Lifecycle

incubating

"Tech preview" - use with the knowledge that this feature is still being actively developed and designed - its signatures may change at any time, although we try to stick to the spi stability guarantees.

stable

A feature/contract that is considered evolved beyond incubation. Its stability guarantee is defined solely by its designation

deprecated

A feature/contract that is deprecated and scheduled for removal at some point. The minimum span of deprecation → removal is 1 major release. It does not effect the stability guarantee of its "designation".