Basic usage

Bus connectivity

When using this library all communication between your application and the systemd service manager is done via D-Bus. Thus at first a connection via either the system or the user (session) bus is required. Both can be achieved via the 'Systemd' class.

The following code establishes a connection via the system bus 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;

Systemd systemd = new Systemd();

try {
    systemd.connect();
}
catch (DBusException e) {
    // ...
}

systemd.disconnect();

Calling the constructor method with the DBusConnection.SYSTEM argument does the same:

import de.thjom.java.systemd.Systemd;
import org.freedesktop.dbus.DBusConnection;
import org.freedesktop.dbus.exceptions.DBusException;

Systemd systemd = new Systemd(DBusConnection.SYSTEM);

try {
    systemd.connect();
}
catch (DBusException e) {
    // ...
}

systemd.disconnect();

Similarly it is possible to establish a connection via the user (session) bus:

import de.thjom.java.systemd.Systemd;
import org.freedesktop.dbus.DBusConnection;
import org.freedesktop.dbus.exceptions.DBusException;

Systemd systemd = new Systemd(DBusConnection.SESSION);

try {
    systemd.connect();
}
catch (DBusException e) {
    // ...
}

systemd.disconnect();

try-with-resource variant

The 'Systemd' class implements the 'AutoClosable' interface hence it allows the try-with-resource pattern like shown below which omits the explicit call to disconnect from the bus.

Connection via system bus:

import de.thjom.java.systemd.Systemd;
import org.freedesktop.dbus.exceptions.DBusException;

try (Systemd systemd = Systemd.createAndConnect()) {
    // ...
}
catch (DBusException e) {
    // ...
}

Connection via user (session) bus:

import de.thjom.java.systemd.Systemd;
import org.freedesktop.dbus.DBusConnection;
import org.freedesktop.dbus.exceptions.DBusException;

try (Systemd systemd = Systemd.createAndConnect(DBusConnection.SESSION)) {
    // ...
}
catch (DBusException e) {
    // ...
}

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 a bus first 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;

Systemd systemd = new Systemd();
Manager manager = null;

try {
    systemd.connect();
    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;

Systemd systemd = new Systemd();

try {
    systemd.connect();
    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();