3 DBusInterface

To call methods or expose methods on D-Bus you need to define them with their exact signature in a Java interface. The full name of this interface must be the same as the D-Bus interface they represent. In addition, D-Bus interface names must contain at least one period. This means that DBusInterfaces cannot be declared without being in a package.

For example, if I want to expose methods on the interface “org.freedesktop.DBus” I would define a Java interface in the package org.freedesktop called DBus. This would be in the file org/freedesktop/DBus.java as normal. Any object wanting to export these methods would implement org.freedesktop.DBus.

Any interfaces which can be exported over D-Bus must extend DBusInterface7 . A class may implement more than one exportable interface, all public methods declared in an interface which extend DBusInterface will be exported.

A sample interface definition is given in figure 2, and a class which implements it in figure 3. More complicated definitions can be seen in the test classes8 .

All method calls by other programs on objects you export over D-Bus are executed in their own thread.

DBusInterface itself specifies one method boolean isRemote(). If this is executed on a remote object it will always return true. Local objects implementing a remote interface must implement this method to return false.


package org.freedesktop;  
import org.freedesktop.dbus.UInt32;  
import org.freedesktop.dbus.DBusInterface;  
 
public interface DBus extends DBusInterface  
{  
   public boolean NameHasOwner(String name);  
   public UInt32 RequestName(String name, UInt32 flags);  
}


Figure 2: An interface which exposes two methods


package my.real.implementation;  
import org.freedesktop.dbus.DBus;  
import org.freedesktop.dbus.UInt32;  
 
public class DBusImpl implements DBus  
{  
   Vector<String> names;  
   public boolean NameHasOwner(String name)  
   {  
      if (names.contains(name)) return true;  
      else return false;  
   }  
   public UInt32 RequestName(String name, UInt32 flags)  
   {  
      names.add(name);  
      return new UInt32(0);  
   }  
   public boolean isRemote() { return false; }  
}


Figure 3: A class providing a real implementation which can be exported

3.1 Interface name overriding

It is highly recommended that the Java interface and package name match the D-Bus interface. However, if, for some reason, this is not possible then the name can be overridden by use of an Annotation.

To override the Java interface name you should add an annotation to the interface of DBusInterfaceName9 with a value of the desired D-Bus interface name. An example of this can be seen in figure 4.


package my.package;  
import org.freedesktop.dbus.DBusInterface;  
import org.freedesktop.dbus.DBusInterfaceName;  
 
@DBusInterfaceName("my.otherpackage.Remote")  
public interface Remote extends DBusInterface  
{  
   ...  
}


Figure 4: Overloading the name of an interface.

If you have signals which are declared in a renamed interface (see below for signals) then when adding a signal handler you must use an addSigHandler method which takes a class object corresponding to that signal. If you do not then receiving the signal will fail.