Version Migration

Each new major version (3.x, 4.x, 5.x..) may contain breaking changes. Therefore major updates can never be considered to be a drop-in replacement for any previous major release.

Migration from 2.7.x to 3.x

DBus-Java 3.x requires Java 1.8 (aka Java 8).

Code changes between 2.7.x and 3.x are only requiring a correction in the imported classes/packages. All classes are still compatible but were moved to different sub packages. In most modern IDEs it should be suitable to let the IDE correct the imports ("Organize Imports" in Eclipse).

Starting with dbus-java 3.2.1 support for file descriptor passing over DBus was added. To use file descriptors you have to add version 1.x of dbus-java-nativefd to your classpath.

Migration from 3.x to 4.x

DBus-Java 4.x requires Java 11.

In version 4.x dbus-java was transformed in a multi-module project. There is no longer a single dbus-java artifact. Instead there is dbus-java-core and different transport artifacts.

Transports are the way dbus-java talks to DBus. In previous versions this was built-in and supported unixsockets and TCP.

With version 4.x there are two different unixsocket implementations:

• dbus-java-transport-jnr-unixsocket which uses jnr-unixsocket and jnr-posix 3rd party library
• dbus-java-transport-native-unixsocket which uses the unixsocket implementation available since Java 16 (therefore a JRE/JDK 16 is required)

Both can be combined with dbus-java-transport-tcp to support TCP as well. Attention: You cannot include BOTH unixsocket implementations, you have to choose ONE of them. Abstract unixsockets and file descriptor support is only possible with the jnr-unixsocket implementation.

For migration you have to include dbus-java-core and a suitable transport to your project. If you need file descriptor support, you have to add version 2.x of dbus-java-nativefd to your classpath.

Due to refactorings in 4.x you may have to update the imported classes (packages) like in the migration from 2.7 to 3.x. If you use TransportFactory, you have to replace this with TransportBuilder.

Note to SPI providers

If you have used the SPI to extend the MessageReader/Writer of dbus-java, you have to update your code. Old providers will not work with dbus-java 4.x because of changed SPI interfaces (sorry!).

The changes were required due to the support of native-unixsocket which is using java.nio, while the old dbus-java code uses the old java.io socket API.

With dbus-java 4.x, java.nio is used for all transports and therefore required changes on the SPI. ISocketProvider will now use SocketChannel instead of Socket in the exported methods.

Migration from 4.x to 5.x

(currently under development, see branch 5x-develop)

DBus-Java 4.x requires Java 17.

All classes, methods and members which were deprecated in 4.x and were marked for removal have been removed. Due to changes required for supported endianess per connection, some classes were moved to other packages.

All sub classes of Message super class now only have protected constructors. Creation of any kind of Message should be done by the MessageFactory instance provided in each connection. The MessageFactory class has been improved to create various Message derived object.

Using server side connections now requires to call connection.listen() on the created connection object. The connection object will be created by either DirectConnectionBuilder or DBusConnectionBuilder like before. The difference is that server-side connections (listening connections) will no longer automatically call accept() on the created listening socket. This was a necessary improvement to allow proper bootstrapping of a server side (e.g. export objects and do stuff before the first client can connect). The listen() call will return the current client TransportConnection.