Using Signals

What is Signal?

A signal in DBus terms is something like a callback which is invoked when something specific happens on the bus.

The best example for this is the PropertiesChangedSignal. This signal is emitted when a property of an object was changed using a DBus call.

For example, you have 2 applications both listening to NetworkManager interfaces. The first application asks NetworkManager to disconnect a network device. The NetworkManager will disconnect the device and emit a signal to all recipients listening for signals (Application 2 in this case). This allow application 2 to do whatever needed when knowing that a device disconnects.

Receiving signals

To receive signals, you first have to create a public interface class which extends DBusInterface. Inside this interface you create a inner class which extends DBusSignal class.

This inner class must have a public constructor which takes the object path as first parameter and all additional required parameters after that. This constructor must call the super constructor providing all arguments which are part of this signal.

Example:

public interface MySignal extends DBusInterface {

    class MySignalClass extends DBusSignal {
        private final String someValue;
        private final int someIntValue;
        
        public MySignalClass(String _objectPath, String _someValue, int _someInt) {
            super(_objectPath, _someValue, _someInt);
            someValue = _someValue;
            someIntValue = _someInt;
        }
        
        public String getSomeValue() {
            return someValue;
        }
        
        public int getSomeIntValue() {
            return someIntValue;
        }
    }
}

To get notified when the signal arrives you have to register a signal handler on you connection to DBus. A signal handler must implements DBusSigHandler<?> interface and can be registered the current connection.

There are different addSigHandler methods depending on the use case. If you only want to listen for specific signals of a specific remote object, you should use something like:

MySignal remoteSignal connection.getRemoteObject("some.bus.name", "/some/object/path", MySignal.class);
connection.addSigHandler(MySignalClass.class, remoteSignal, new MySignalClassHandler());

If you want to listen to all object paths of an exported object you can use: connection.addSigHandler(MySignalClass.class, new MySignalClassHandler()).

It is also possible to express a signal handler as Lambda e.g.: connection.addSigHandler(MySignalClass.class, signal -> System.out.println("Got signal: " + signal))

To remove a handler you can either call close() on the object returned by the addSigHandler calls or use the appropriate removeSigHandler call. You don't have to remove your signal handler when you want to close the connection anyway. All registered signal handlers will automatically be unregistered when connection is closed.

connection.addSigHandler(DBusMatchRuleBuilder.create()
    .withPath("/org/test/Introduction")
    .withSender("org.my.Sender")
    .build(), 
    new MyCustomSignalHandler());

Signals and constructors

A signal class can have multiple constructors. The actual constructor used for signal creation depends on the signature of the signal received on the bus.

Every object and also every signal has as signature which defines what kind of data has to be expected in the received DBus message.

When dbus-java receives a signal, it uses DBus interface name as package name and the signal name as class name. It checks for presents of a proper signal class using these parameters. If a signal class could be found, all public constructors are read and put in a cache (so no need to re-scan every time).

Then the signature of the received signal is used to find a matching constructor previously fetched from the signal class. If no suitable constructor is found, a warning is logged and the signal is ignored.

Starting from dbus-java 5.1.1, you can add a unknownSignalHandler using the DBusConnectionBuilder. This callback will than always be called when dbus-java is unable to de-serialize a signal.

If a suitable constructor is found, a instance of the signal class is created and all registered handlers will be notified.

class MySignal extends DBusSignal {
    public MySignal(String _objPath, int[] _arr, String _text) {
       super(_objectPath, _arr, _text);
    }
    
    public MySignal(String _objPath, List<Integer> _arr, String _text) {
       super(_objectPath, _arr, _text);
    }
}

class MySignal extends DBusSignal {
    public MySignal(String _objPath, int[] _arr, String _text) {
       this(_objectPath, Arrays.asList(_arr), _text);
    }
    
    public MySignal(String _objPath, List<Integer> _arr, String _text) {
       super(_objectPath, _arr, _text);
    }
}