Skip to content

Basic usage

Markus Enax edited this page Mar 14, 2021 · 26 revisions

Bus connectivity

When using this library all communication between your application and the systemd service manager is done via D-Bus. systemd manages multiple instances to which you can connect. Normally these are

  • the system-wide "system" instance (the one you talk to when calling systemctl on the console)
  • your session-wide "user" instance (the one you talk to when calling systemctl --user on the console)

Thus at first a connection to either the system or the user instance is required. Both can be achieved via the Systemd class. The class is implemented as a singleton for each system and user instance which means that subsequent calls to the particular get() methods will return the same instance. This design is a direct consequence of the singleton implementation of the DBusConnection class which comes with dbus-java.

The following code establishes a connection to the system instance and disconnects at the end. An exception of type DBusException is thrown in case the connection can't be established.

import de.thjom.java.systemd.Systemd;

import org.freedesktop.dbus.exceptions.DBusException;

try {
    Systemd systemd = Systemd.get();
}
catch (DBusException e) {
    // ...
}
finally {
    Systemd.disconnect();
}

Calling the constructor and the disconnect() method with the Systemd.InstanceType.SYSTEM argument do the same:

import de.thjom.java.systemd.Systemd;
import de.thjom.java.systemd.Systemd.InstanceType;

import org.freedesktop.dbus.exceptions.DBusException;

try {
    Systemd systemd = Systemd.get(InstanceType.SYSTEM);
}
catch (DBusException e) {
    // ...
}
finally {
    Systemd.disconnect(InstanceType.SYSTEM);
}

Similarly it is possible to establish a connection to the user instance. Note that a connection to the user instance must be closed respectively via the correct argument, here Systemd.InstanceType.USER:

import de.thjom.java.systemd.Systemd;
import de.thjom.java.systemd.Systemd.InstanceType;

import org.freedesktop.dbus.exceptions.DBusException;

try {
    Systemd systemd = Systemd.get(InstanceType.USER);
}
catch (DBusException e) {
    // ...
}
finally {
    Systemd.disconnect(InstanceType.USER);
}

For convenience the Systemd class provides a method to disconnect all process-wide instances from the bus:

import de.thjom.java.systemd.Systemd;
import de.thjom.java.systemd.Systemd.InstanceType;

import org.freedesktop.dbus.exceptions.DBusException;

try {
    Systemd.get();
    Systemd.get(InstanceType.USER);
}
catch (DBusException e) {
    // ...
}
finally {
    Systemd.disconnectAll();
}

Manager interface

Once a connection has been established the particular service manager instance can be loaded by accessing the bus. The following code loads the manager instance via the system bus. There must be an established connection to the bus otherwise the getManager() method will throw an exception.

import de.thjom.java.systemd.Manager;
import de.thjom.java.systemd.Systemd;

import org.freedesktop.dbus.exceptions.DBusException;

try {
    Systemd systemd = Systemd.get();
    Manager manager = systemd.getManager();
}
catch (DBusException e) {
    // ...
}

With the manager instance at hand access to properties as well as methods of the "Manager" interface become available. For example the platform architecture can be fetched.

String arch = manager.getArchitecture();

For more information on how to access properties see the "Properties" section.

Unit wrappers

The manager interface can be used to instantiate adapters which each represent a single systemd unit. Unit adapters provide access to properties and methods of the particular unit interface and its specialized type interface. The following code sets up a connection and instantiates an adapter for the unit "avahi-daemon.service".

import de.thjom.java.systemd.Manager;
import de.thjom.java.systemd.Service;
import de.thjom.java.systemd.Systemd;

import org.freedesktop.dbus.exceptions.DBusException;

try {
    Systemd systemd = Systemd.get();
    Manager manager = systemd.getManager();

    Service avahi = manager.getService("avahi-daemon");
}
catch (DBusException e) {
    // ...
}

With the adapter at hand access to properties as well as methods of both the "Unit" and the special type interface (here "Service") become available. For example the PID of the service can be fetched (if running).

int pid = avahi.getMainPID();
Clone this wiki locally