- Legacy 4.x:
- Javadoc 4.x:
- Current 5.x:
- Javadoc 5.x:
- Site: Maven Site
Improved version of Java-DBus library provided by freedesktop.org with support for Java 17+.
The new major is no drop-in replacement for earlier versions! It requires code changes and at least Java 17.
When migrating from 4.x to 5.x you have to fix/replace all usages of deprecated method calls and class usages. Everything deprecated in a previous major version (4.x/3.x) and marked "forRemoval" is gone in 5.x.
When migrating from 3.x, the main difference is the separation of dbus-java into multi module project. The base artifact is dbus-java-core and requires at least one additional transport artifact. A transport provides the code to connect to DBus daemon on various ways (e.g. unix socket or TCP).
When updating to 4.x you have to add at least one transport to your project. If you add a unix socket transport, you have to choose between jnr-unixsocket and native-unixsocket. The jnr implementation will pull in jnr-unixsocket, jnr-posix etc. to your project. It will also provide support for abstract unixsockets and is required if you want to use file descriptor passing. If you need file descriptors as well you also have to add a proper implementation for that (see below).
If you don't know what abstract unixsockets are and you don't need file descriptors you'll probably you can use native-unixsockets.
Upgrading to 5.1.0 should be no problem in most cases.
Beginning with 5.1.0 the behavior of Variant<?>
has been altered to get a more consistent behavior.
More about that can be found here .
If you used DBusMap
before, you should use LinkedHashMap
instead.
All methods previously returned instances of DBusMap
will now return LinkedHashMap
.
This is transparent if you didn't use DBusMap
directly but using Map
interface instead.
In this version the broken hashCode()
implementation has been fixed in DBusPath
allowing proper usage
of DBusPath
as Map
key. Before equal objects did not create the same hashCode()
breaking the contract of hashCode()
and equals()
.
If you have used the SPI to extend the MessageReader/Writer of dbus-java before dbus-java 4.x, you have to update your code. Old providers will not work with dbus-java 4.x/5.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 (and 5.x as well), 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.
If you previously used a custom transport you have to update your code when switching to dbus-java 5.x.
The AbstractTransport
base class has been changed and now provides different methods to separate client and listening
(server) connections.
Additionally there is a new method called closeTransport()
which must be implemented to ensure all used resources
(e.g. SocketChannel
or ServerSocketChannel
instance) are properly closed.
Previously a transport should have overridden close()
and call super.close()
after closing the transport.
This is now longer needed (close()
is now final and cannot be overriden) and is replaced by closeTransport()
.
The connectImpl()
was previously existing and will now only be called for client side connections.
The new methods bindImpl()
, acceptImpl()
and isBound()
are used for server connections and has been added in dbus-java 5.x.
The reason to provide separate methods was to allow bootstrapping server connections before accepting connections.
In the old implementation accept()
was usually called in connectImpl()
and therefore blocked the method until
a client was connected. This blocked setting up the server side before the first client was connecting.
This forced the user to use some random sleep times to wait for the server setup after first client connects.
With the separation no more sleep waits are required.
With the new methods, everything related to setup the server socket should be done in bindImpl()
including the binding
of the listening socket (calling bind()
on the server socket). Everything done in this method should not block.
You mustn't call accept()
on your server socket in bindImpl()
!
In acceptImpl()
it is expected that the transport calls accept()
on its server socket and therefore this method will block.
It must return the SocketChannel
for each client connected (like connectImpl()
does).
The isBound()
method must return the bind status of the server socket. This means for example
server socket is not null
and server socket is opened.
This method is used by AbstractTransport
to determine if bindImpl()
was called before and if the server socket is ready to accept
connections.
In DBus-Java version below < 4.3.1 file descriptor usage was not supported out of the box and required a third party libary (see below). Starting with version 4.3.1 file descriptors are supported when using junixsocket-transport.
When trying to use file descriptors in dbus-java 3.x and not providing a implementation for this feature, you may see weird NullPointerExceptions thrown in Message class. In dbus-java < 4.3.1 you should see error messages indicating that file descriptors are not supported.
To use file descriptors with dbus-java version 4.x before 4.3.1 you have to do the following:
- Add dbus-java-transport-jnr-unixsocket dependency to your project
- Remove dbus-java-transport-native-unixsocket if you have used it before
- Add dependency com.rm5248:dbus-java-nativefd to your classpath
When using dbus-java-nativefd, you have to use version 2.x when using dbus-java 4.x/5.x and 1.x if you use dbus-java 3.x. DBus-java will automatically detect dbus-java-nativefd and will then provide access to file descriptors.
If you are using version 4.3.1 or higher, you may simple switch to dbus-java-transport-junixsocket
(instead of dbus-java-transport-jnr-unixsocket
or dbus-java-transport-native-unixsocket
).
You do this by adding dbus-java-transport-junixsocket
to your classpath.
Remember to remove the other unixsocket implementations because you are not allowed to have multiple implementations of the same protocol at once.
When adding dbus-java-transport-junixsocket
to your classpath, you will also pull-in some artifacts of junixsocket project.
It is also possible that junixsocket will not work on your platform (depends on which platform and architecture you are using).
They provide a lot of ready-to-use artifacts for different platforms and architectures, but certainly not for all possible combinations out there.
In case your platform is not supported, you may try dbus-java-transport-jnr-unixsocket
with com.rm5248:dbus-java-nativefd, compile
junixsocket yourself or open a ticket at junixsocket asking for help.
See the list in our Wiki
This project receives code contributions and donations from LogonBox.
However LogonBox is not responsible for this project and does not take influence in the development.
The library will remain open source and MIT licensed and can still be used, forked or modified for free.
- Added new Helper class
VariantBuilder
to allow creating Variants which contain Maps or Collections without messing with the required DBus type arguments - Fixed wrong/missing increment when resolving nested structs or deeply nested objects in
Marshalling.getDBusType
(#265) - Fixed wrong import when generating Tuple containing Struct (#264)
- Added support for argument prefix for methods and constructors in
InterfaceCodeGenerator
(to e. g. allow generating code using similar code style like dbus-java with prefixing every argument with_
) - Fixed printed version information in
InterfaceCodeGenerator
was alwaysnull
- Smaller code cleanup in
InterfaceCodeGenerator
to prevent creating multiple empty lines - Dependency updates
- Added support for
EmitsChangedSignal
(PR#267), thanks to GeVa2072 - Tighten PMD rules to disallow usage of
var
keyword - Updated Maven plugins
- Use Junit BOM thanks to spannm (PR#248)
- More Java 17 syntactic sugar, thanks to spannm (PR#249)
- Added support for custom ClassLoader/ModuleLayer when configuring Transport (allows usage of third party transports when e.g. using JPMS) (#251)
- Improved handling of
@DBusBoundProperty
annotation (#253), (PR#252) - Improved InterfaceCodeGenerator to handle generated struct class names properly (#254)
- Improved InterfaceCodeGenerator to add parameter/argument name to created struct class name (e.g. MyMethod(something) => MyMethodSomethingStruct)
- Added dbus-java-transport-junixsocket to BOM (#255)
- Fixed issues in InterfaceCodeGenerator regarding missing imports or wrong annotation content (#257)
- Fixed issues with
GetAll
on Properites using Annotations (#258) - Changed behavior of de-serialization on Variants containing Collections (Lists). Collections which contained a object which also has a primitive representation the collection was always converted to an array of primitives (e.g. Variant<List> got Variant<int[]> on de-serialization). This is usually not expected. When defining a Variant<List> it is expected to return that same type when de-serialized. The wrong behavior also caused issues when using
GetAll
method inProperties
interface. More information - Deprecated
DBusMap
- all methods previously used or returnedDBusMap
will now return aLinkedHashMap
- Fixed
hashCode()
andequals()
method inDBusPath
(hashCode()
was completely wrong and violating thehashCode()
contract when e.g. used as key in maps) - Added possibility to use
WeakHashMap
for imported objects (configurable byDBusConnectionBuilder
), default behavior of using aConcurrentHashMap
is not changed (yet) (#261)
- Updated minimum required Java version to 17
- Removed all classes and methods marked as deprecated in 4.x
- Updated dependencies and maven plugins
- Improved handling of listening connections to allow proper bootstrapping the connection before actually starting accepting new connections (thanks to brett-smith (#213))
- Updated export-object documentation (#236)
- Fixed issues with autoConnect option, added method to register to bus by 'Hello' message manually, thanks to brett-smith (#238)
- Added feature which allows to annotate setter or getter methods in exported objects to use the DBus Properties interface behind the scenes, thanks to brett-smith (PR#235)
ExportedObject.isExcluded(Method)
now returns true for bridge, default and synthetic methods, reported by brett-smith (#240)- DBusViewer: Remove DOCTYPE definition in introspection data using a regex which handles line breaks properly
- Applied changes found by Sonarcloud static code analysis
- Fixed issue with shared connections did not work when underlying transport was disconnected due to end-point (daemon) was stopped/restarted (#244)
- Fixed class cast exception in LoggingHelper (#247), reported by AsamK
- Provide classloader to ServiceLoader in TransportBuilder (for loading actual transports) and AbstractTransport (for loading IMessageReader/Writer implementations), thanks to cthbleachbit (#210, PR#211)
- Added missing
connect()
method toAbstractTransport
to allow connecting the underlying transport manually, thanks to brett-smith (#212) - Fixed issue with SASL DATA command when no actual data is sent, thanks to Prototik (#214)
- Fixed SASL AUTH did not read enough data when COOKIE was used, thanks to Prototik (#215)
- Fixed several other issues when using SASL anonymous authentication, thanks to Prototik (PR#216)
- Updated documentation (#218)
- Fixed possible issue with used serial numbers in messages because signals may manually incremented the serial without updating global serial (#220)
- Updated module-info exports, thanks to brett-smith (#221)
- Ensure that DBusDaemonThread is terminated when close() is called, thanks to brett-smith (#222)
- Fixed configured authentication mechanism was always ignored when connecting, thanks to brett-smith (#223)
- Improved logging and handling of disconnected transports in
DBusDaemon
, thanks to brett-smith (#225) - Added additional transport (dbus-java-junixsocket), thanks to Prototik (#227) for providing the implementation
- Smaller refactorings to avoid code duplication for new transport
- Use daemon threads in
ExecutorService
for DBus-Sender-Threads (#234)
- Fixed thread priority settings were never passed to thread factory, thanks to DaveJarvis (#190)
- Fixed possible NullPointer dereference in ReceivingService, thanks to DaveJarvis (#191)
- Make ReceivingServiceConfig final in builder, thanks to DaveJarvis (#192)
- Fixed issues with code generator, creating tuple classes without proper imports and having issues creating nested structs (struct in struct) (#195)
- Updated dependencies
- Applied checkstyle suggestions
- Fixed 'type' was not passed when creating dynamic proxy, thanks to drivera73 (PR#198)
- Fixed some possible NullPointerExceptions (#201, #202, #204)
- Improved encapsulation in BusAddress (and subclasses), deprecated
getParameter(String)
method (#202) - Fixed potentially leaking streams in
SASL
addCookie()
/findCookie()
methods (#205) - Replaced old school
PrintStream
file writing withFiles.write
(#205) - Replaced usages of calls to
System.currentMillis()
for locking and waiting due to possible issues when NTP changes time during lock/wait (#206) - Reduced duplicated code (#206)
- Updated PMD rules / enabled build failing when PMD/Checkstyle rules are violated
- Replaced most usages of
System.out.print
and friends in unit tests (use a proper logger instead) - Improved logging (changed usage of LoggingHelper, added a better deepToString)
- Support DBUS_TEST_HOME_DIR system property
- Fixed issue with broken MethodReturn messages when running as server (#207)
- Changed SASL to read responses bytewise to prevent reading to much (and break the following message)
- Added option to change authentication mode used in DBusDaemon (--auth-mode/-m)
- Improved handling of broken connections in DBusDaemon
- Fixed leaking threads in DBusDaemon
- Fixed
EmbeddedDBusDaemon.startInBackgroundAndWait(long)
did not properly wait for the sender thread to be started (#208) - Fixed DBusDaemon never used
MessageWriter
/MessageReader
provided on classpath (always used the default implementation) - Some refactorings in DBusDaemon/EmbeddedDBusDaemon
- Improved
AbstractTransport
to support listener connections properly (you have to uselisten()
method now, this allows proper usage of detectedMessageReader
/MessageWriter
implementation) - New option in TransportBuilder to enforce Dbus-Keyring directory permissions (like adviced in DBus Spec). The default is not to check permissions, so the behavior is the same as before (dbus-java didn't care about permissions before)
- Fixed OSGi packaging
- Updated dependencies
- Compare bus type names using US locale (#185)
- Smaller cleanup/redesign in DBusDaemon
- Fixed regression: Signals could not be created when using
@DBusInterfaceName("XX")
on signal interface classes (#186)
- Deprecated
TransportBuilder.isListening(boolean)
as method name signals that aboolean
is returned butTransportBuilder
is returned. Please useTransportBuilder.listening(boolean)
instead. Old method will be removed in 4.3.0 - Applied more PMD/CPD suggestions
- Deprecated
DBusConnectionBuilder.getSystemEndianness()
andDirectConnectionBuilder.getSystemEndianness()
, useBaseConnectionBuilder.getSystemEndianness()
instead - Refactoring of
DBusConnectionBuilder
andDirectConnectionBuilder
to use same base classBaseConnectionBuilder
to reduce duplicated code - Moved receiving thread configuration stuff from
BaseConnectionBuilder
toReceivingServiceConfigBuilder
to configure receiving thread-pools e.g. useDBusConnectionBuilder.forSessionBus().receivingThreadConfig().withXXX
and continue either with.buildConnection()
to get the connection object or.connectionConfig()
to get back to the chosen connection builder - Added methods
withXXXThreadPriority
methods toReceivingServiceConfigBuilder
to allow changing the thread priority set forReceivingService
thread pool threads (#173) - Improved handling with different transports and address (e.g. fail early if no transport is provided for given address)
- Added possibility to add custom retry-handler to
ReceivingService
using the builder ReceivingService
will now throwIllegalThreadPoolStateException
(subclass ofIllegalStateException
) instead ofIllegalStateException
directly- Use
BusAddress
internally instead of Strings - Use subclasses of
BusAddress
in Tcp/UnixTransport - Added method
isBusType(String)
toBusAddress
class which allows checking which kind of transport is used case-insensitive and null-safe - Support a custom callback on transports right before connecting (preConnectCallback) (#174)
- Reorganized
TransportBuilder
, this will also deprecate a lot of methods (withXXX
) which were moved toconfigure()
(which returns aTransportConfigBuilder
) - Transport configuration is now accessible using the
DBusConnectionBuilder
orDirectConnectionBuilder
(by using e.g.DBusConnectionBuilder.forSession().transportConfig()
) - New
TransportConfig
supports additional configuration by providing aMap<String,Object>
which allows passing arbitrary values to the transport - Updated SPI
ITransportProvider
which now takes aTransportConfig
object instead of the timeout int. For compatibility the old method is still present (and will be delegated), but should be considered deprecated and will be removed in the future - Improved handling of remaining messages to send when disconnection is happening due to
IOException
. In case the disconnect is forced by an exception the remaining messages will be omitted. Otherwise connection may block because of waiting for a replies forMethodCall
s. It is assumed that a disconnection caused by an exception might have closed the transport already so no further messages may be send or received. - Allow setting the SASL user ID manually, thanks to brett-smith (PR#178)
- Moved all SASL related configuration to SaslConfig bean, deprecated methods in AbstractTransport directly related to that change
- Removed usage of
AbstractConnection.TCP_ADDRESS_PROPERTY
as this was a special behavior for using/testingDBusDaemon
EmbeddedDBusDaemon
will no longer setAbstractConnection.TCP_ADDRESS_PROPERTY
, instead you have to handle the address you used for construction ofEmbeddedDBusDaemon
yourselfDBusConnectionBuilder.forSessionBus()
will use the same validation applied to system addresses- Replaced calls to expensive method calls when logging with call which only gets executed if log level is enabled
- Changed signal handling to use a matching method instead of relying on having a suitable map-key for every possible signal (causes high memory usage / lots of temporary objects, see #182)
- Removed usage of
SignalTuple
class - Improved
InputMessageStreamReader
to use a final socket channel and some more final member variables for constant size buffers (#183) - Improved
Message
class to not create superflousVariant
objects to populate message header (#184)
- Fixed regression not allowing to use classes directly implementing
DBusInterface
to be exported on the bus (#157) - Throw AuthenticationException when SASL command was unreadable during logon handshake, thanks to brett-smith (PR#158)
- Fixed issue with handling signals in wrong order (#159)
- Applied changes found by PMD/IntelliJ static code analyzers
- Deprecated
DBusConnection.newConnection
/DBusConnection.getConnection
, please use DBusConnectionBuilder - Deprecated public constructors of
DirectConnection
, please use DirectConnectionBuilder - Added dbus-java-example module which contains samples and demonstration code on how to use dbus-java
- Fixed issue when exporting nested objects (#163)
- Added bom ("Bill of Material") project module, thanks to mk868 (PR#167)
- Fixed missing value in deprecated annotation; Removed duplicated code, thanks to mk868 (PR#168)
- Requires at least Java 11
- Added transport which uses native unix sockets provided by Java 16+ (see: #145)
- Splitted dbus-java to multiple modules:
- dbus-java-core: Core dbus-java functions (always required)
- dbus-java-transport-jnr-unixsocket: Unix socket support based on jnr-unixsocket
- dbus-java-transport-native-unixsocket: Unix socket support based on native unix sockets (Java 16+ required)
- dbus-java-transport-tcp: TCP based DBus messaging
- dbus-java-utils: utilities which may help during development
- Updated dependencies