<html xmlns="http://www.w3.org/1999/xhtml" lang="">

<head>

<meta charset="UTF-8" />

<meta name="viewport" content="width=device-width, initial-scale=1" />

<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />

<title>Properties – dbus-java</title>

<link rel="stylesheet" href="./css/apache-maven-fluido-2.1.0.min.css" />

<link rel="stylesheet" href="./css/site.css" />

<link rel="stylesheet" href="./css/print.css" media="print" />

<script src="./js/apache-maven-fluido-2.1.0.min.js"></script>

</head>

<body class="topBarDisabled">

<div class="container-fluid">

<header>

<div id="banner">

<div class="pull-left"></div>

<div class="pull-right"></div>

<div class="clear"><hr/></div>

</div>

<div id="breadcrumbs">

<ul class="breadcrumb">

<li id="publishDate">Last Published: 2025-12-21</li>

<li id="projectVersion" class="pull-right">Version: 5.2.1-SNAPSHOT</li>

<li class="pull-right"><span class="divider">|</span>

<a href="https://search.maven.org/search?q=g:com.github.hypfvieh%20dbus-java">Maven Central</a></li>

<li class="pull-right"><span class="divider">|</span>

<a href="https://www.github.com/hypfvieh/dbus-java/wiki">GitHub Wiki</a></li>

<li class="pull-right"><a href="https://www.github.com/hypfvieh/dbus-java">GitHub Repository</a></li>

</ul>

</div>

</header>

<div class="row-fluid">

<header id="leftColumn" class="span2">

<nav class="well sidebar-nav">

<ul class="nav nav-list">

<li class="nav-header">Overview</li>

<li><a href="index.html">Home</a></li>

<li><a href="quick-start.html">Quickstart</a></li>

<li><a href="code-generation.html">Code Generation</a></li>

<li><a href="exporting-objects.html">Exporting Objects</a></li>

<li><a href="remote-objects.html">Calling Remote Objects</a></li>

<li class="active"><a>Properties</a></li>

<li><a href="variant-handling.html">Variant</a></li>

<li><a href="using-signals.html">Signals</a></li>

<li><a href="howto.html">Howto...</a></li>

<li class="nav-header">Project Documentation</li>

<li><a href="project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>

<li><a href="project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>

<li class="nav-header">Modules</li>

<li><a href="dbus-java-core/index.html">dbus-java-core</a></li>

<li><a href="dbus-java-osgi/index.html">dbus-java-osgi</a></li>

<li><a href="dbus-java-utils/index.html">dbus-java-utils</a></li>

<li><a href="dbus-java-transport-jnr-unixsocket/index.html">dbus-java-transport-jnr-unixsocket</a></li>

<li><a href="dbus-java-transport-junixsocket/index.html">dbus-java-transport-junixsocket</a></li>

<li><a href="dbus-java-transport-native-unixsocket/index.html">dbus-java-transport-native-unixsocket</a></li>

<li><a href="dbus-java-transport-tcp/index.html">dbus-java-transport-tcp</a></li>

<li><a href="dbus-java-bom/index.html">dbus-java-bom</a></li>

<li><a href="dbus-java-tests/index.html">dbus-java-tests</a></li>

<li><a href="dbus-java-examples/index.html">dbus-java-examples</a></li>

</ul>

</nav>

<div class="well sidebar-nav">

<hr />

<div id="poweredBy">

<div class="clear"></div>

<div class="clear"></div>

<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>

</div>

</div>

</header>

<main id="bodyColumn" class="span10">

<section><a id="Properties"></a>

<h1>Properties</h1>

<p><a href="https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties" class="externalLink">DBus Properties</a> can be accessed

and exported using one of two methods.</p>

<li><a href="#using-the-exported-object">Directly Bound To Setters And Getters</a>.</li>

<li><a href="#implementing-the-properties-interface">Implementing the Properties Interface</a>.</li>

</ul><section><a id="Directly_Bound_To_Setters_And_Getters"></a>

<h2>Directly Bound To Setters And Getters</h2>

<p>Since version 5 of <code>dbus-java</code>, it has been possible to directly map DBus properties to Java

methods. By convention this is done using a JavaBeans like pattern.</p>

<p>This method is likely preferable in most cases, as it has a number of advantages over the

legacy method described below.</p>

<li>Simpler code when exporting services, no need to implement <code>Get()</code>, <code>Set()</code> and <code>GetAll()</code> from <code>org.freedesktop.DBus.Properties</code>.

In fact, you do not need to implement this interface at all.</li>

<li>Simpler code when accessing properties on services, no casting or accessing properties by string names.</li>

<li>More natural. Java programmers are familiar with this pattern.</li>

<li>Makes it much easier to share interfaces between client and server code.</li>

<p>This feature is activated by the <code>@DBusBoundProperty</code> annotation.</p><section><a id="The_Interface"></a>

<h3>The Interface</h3>

<p>Consider the following interface.</p>

<pre class="prettyprint"><code class="language-java">package com.acme;

import org.freedesktop.dbus.interfaces.DBusInterface;

import org.freedesktop.dbus.annotations.DBusProperty.Access;

import org.freedesktop.dbus.annotations.DBusBoundProperty;

public interface MyInterface extends DBusInterface {

String sayHello();

@DBusBoundProperty(access = Access.READ, name = &quot;MyProperty&quot;)

String getMyProperty();

@DBusBoundProperty(access = Access.WRITE, name = &quot;MyProperty&quot;)

void setMyProperty(String _property);

@DBusBoundProperty(access = Access.READ, name = &quot;ZZZZZZZ&quot;)

long getMyAltProperty();

@DBusBoundProperty(access = Access.WRITE, name = &quot;ZZZZZZZ&quot;)

void setMyAltProperty(long _property);

@DBusBoundProperty

boolean isMyOtherProperty();

@DBusBoundProperty

void setMyOtherProperty(boolean _property);

}

<p>When instances of the interface are exported, just a single method call will be visible.

All other attributes of the interface will be exported as properties instead.</p>

<p>Every DBus property has 3 optional attributes. It's <code>name</code>, it's <code>type</code> and it's <code>access</code> mode.

All 3 of these attributes may optionally be supplied to the annotation, but for most cases it

is sufficient to omit all attributes and for dbus-java to infer these from the method

signature.</p>

<li>The name of the property will be derived from the method name, with the leading <code>get</code>,

<code>set</code> or <code>is</code> removed (case insensitively).</li>

<li>The access mode of the property will be determined by whether the method is a <code>set</code> or

and <code>get</code> or <code>is</code>.</li>

<li>The type of the property will be derived from either the return value or the first (and only) parameter.</li>

<p><em>All getters should have zero arguments and a return value, and all setters should have

a single argument, and no return value</em></p>

<p>If you are just interested in using a 3rd party service that exports your target object, you then

can just skip the next section and go straight to <a href="#using-the-exported-object">Using The Exported Object</a> below.</p>

<p>However if you wish to export your own service that uses properties, then read on.</p></section><section><a id="The_Implementation"></a>

<h3>The Implementation</h3>

<p>Expanding on the above example, we will now provide the implementation of this interface

and export it for clients to use.</p>

<pre class="prettyprint"><code class="language-java">package com.acme;

public class MyObject implements MyInterface {

private String myProperty = &quot;Initial value&quot;;

private boolean myOtherProperty;

private long myAltProperty = 123;

@Override

public String getObjectPath() {

return &quot;/com/acme/MyObject&quot;;

}

@Override

public String sayHello() {

return &quot;Hello!&quot;;

}

@Override

public long getMyAltProperty() {

return myAltProperty;

}

@Override

public void setMyAltProperty(long _myAltProperty) {

this.myAltProperty = _myAltProperty;

}

@Override

public String getMyProperty() {

return myProperty;

}

@Override

public void setMyProperty(String _property) {

myProperty = _property;

}

@Override

public boolean isMyOtherProperty() {

return myOtherProperty;

}

@Override

public void setMyOtherProperty(boolean _property) {

myOtherProperty = _property;

}

@Override

public boolean isRemote() {

/* Whenever you are implementing an object, always return false */

return false;

}

}

</code></pre></section><section><a id="Exporting_The_Object"></a>

<h3>Exporting The Object</h3>

<p>You would export the object the same as normal.</p>

<pre class="prettyprint"><code class="language-java">package com.acme;

import org.freedesktop.dbus.connections.impl.DBusConnection;

import org.freedesktop.dbus.connections.impl.DBusConnectionBuilder;

import org.freedesktop.dbus.exceptions.DBusException;

public class ExportMyObject {

ExportMyObject() throws DBusException {

DBusConnection conn = DBusConnectionBuilder.forSessionBus().build();

conn.requestBusName( &quot;com.acme&quot; );

MyObject obj = new MyObject();

conn.exportObject( obj.getObjectPath(), obj );

}

public static void main(String[] args) throws DBusException {

new ExportMyObject();

}

}

</code></pre></section><section><a id="Using_The_Exported_Object"></a>

<h3>Using The Exported Object</h3>

<p>And finally making use of the exported interface in client code.</p>

<pre class="prettyprint"><code class="language-java">package com.acme;

import org.freedesktop.dbus.connections.impl.DBusConnection;

import org.freedesktop.dbus.connections.impl.DBusConnectionBuilder;

import org.freedesktop.dbus.exceptions.DBusException;

public class ImportMyObject {

ImportMyObject() throws DBusException {

DBusConnection conn = DBusConnectionBuilder.forSessionBus().build();

MyInterface obj = conn.getRemoteObject(&quot;com.acme&quot;, &quot;/com/acme/MyObject&quot;, MyInterface.class);

System.out.println(&quot;My property: &quot; + obj.getMyProperty());

System.out.println(&quot;My Alt property: &quot; + obj.getMyAltProperty());

System.out.println(&quot;My Other property: &quot; + obj.isMyOtherProperty());

}

public static void main(String[] args) throws DBusException {

new ImportMyObject();

}

}

</code></pre></section></section><section><a id="Implementing_the_Properties_Interface"></a>

<h2>Implementing the Properties Interface</h2>

<p>As an alternative to the above, you can use DBus's <code>org.freedesktop.dbus.Properties</code> interface.</p>

<p>If you are exporting your own service, this means that you <code>extends Properties</code> in your interface,

and provide the required implementations of the <code>Get()</code>, <code>GetAll()</code> and <code>Set()</code> methods in your

concrete class.</p>

<p>If you are using an exported interface in client code, then you access your remote object as normal,

and invoke the <code>Get()</code>, <code>GetAll()</code> or <code>Set()</code> methods on that object.</p>

<p>The above example, re-written to use <code>@DBusProperty</code>, would look like this.</p>

<pre class="prettyprint"><code class="language-java">package com.acme;

import org.freedesktop.dbus.interfaces.DBusInterface;

import org.freedesktop.dbus.annotations.DBusProperty;

import org.freedesktop.dbus.annotations.DBusProperty.Access;

import org.freedesktop.dbus.interfaces.Properties;

@DBusProperty(access = Access.READ_WRITE, name = &quot;MyProperty&quot;, type = String.class)

@DBusProperty(access = Access.READ_WRITE, name = &quot;ZZZZZZZ&quot;, type = String.class)

@DBusProperty(access = Access.READ_WRITE, name = &quot;MyOtherProperty&quot;, type = Boolean.class)

public interface MyInterface extends DBusInterface, Properties {

String sayHello();

}

<p>While this interface is smaller than the above, there is a bit more to do in the implementation,

or when you need to access these properties.</p>

<pre class="prettyprint"><code class="language-java">package com.acme;

public class MyObject implements MyInterface {

private String myProperty = &quot;Initial value&quot;;

private boolean myOtherProperty;

private long myAltProperty = 123;

@Override

public String getObjectPath() {

return &quot;/com/acme/MyObject&quot;;

}

@Override

public String sayHello() {

return &quot;Hello!&quot;;

}

@SuppressWarnings(&quot;unchecked&quot;)

@Override

public &lt;A&gt; A Get(String _interfaceName, String _propertyName) {

if (&quot;MyProperty&quot;.equals(_propertyName)) {

return (A) new Variant&lt;&gt;(myProperty);

} else if (&quot;ZZZZZZZ&quot;.equals(_propertyName)) {

return (A) new Variant&lt;&gt;(myAltProperty);

} else if (&quot;MyOtherProperty&quot;.equals(_propertyName)) {

return (A) new Variant&lt;&gt;(myOtherProperty);

} else {

throw new IllegalArgumentException();

}

}

@SuppressWarnings(&quot;unchecked&quot;)

@Override

public &lt;A&gt; void Set(String _interfaceName, String _propertyName, A _value) {

if (&quot;MyProperty&quot;.equals(_propertyName)) {

myProperty = ((Variant&lt;String&gt;) _value).getValue();

} else if (&quot;ZZZZZZZ&quot;.equals(_propertyName)) {

myAltProperty = ((Variant&lt;Long&gt;) _value).getValue();

} else if (&quot;MyOtherProperty&quot;.equals(_propertyName)) {

myOtherProperty = ((Variant&lt;Boolean&gt;) _value).getValue();

} else {

throw new IllegalArgumentException();

}

}

@Override

public Map&lt;String, Variant&lt;?&gt;&gt; GetAll(String _interfaceName) {

Map&lt;String, Variant&lt;?&gt;&gt; all = new HashMap&lt;&gt;();

all.put(&quot;MyProperty&quot;, new Variant&lt;&gt;(myProperty));

all.put(&quot;ZZZZZZZ&quot;, new Variant&lt;&gt;(myAltProperty));

all.put(&quot;MyOtherProperty&quot;, new Variant&lt;&gt;(myOtherProperty));

return all;

}

@Override

public boolean isRemote() {

/* Whenever you are implementing an object, always return false */

return false;

}

}

<p>And finally making use of these properties in client code.</p>

<pre class="prettyprint"><code class="language-java">package com.acme;

import org.freedesktop.dbus.connections.impl.DBusConnection;

import org.freedesktop.dbus.connections.impl.DBusConnectionBuilder;

import org.freedesktop.dbus.exceptions.DBusException;

import org.freedesktop.dbus.types.Variant;

public class ImportMyObject {

ImportMyObject() throws DBusException {

DBusConnection conn = DBusConnectionBuilder.forSessionBus().build();

MyInterface obj = conn.getRemoteObject(&quot;com.acme&quot;, &quot;/com/acme/MyObject&quot;, MyInterface.class);

System.out.println(&quot;My property: &quot;

+ (String) obj.Get(&quot;com.acme.MyInterface&quot;, &quot;MyProperty&quot;));

System.out.println(&quot;My Alt property: &quot;

+ (Long) obj.Get(&quot;com.acme.MyInterface&quot;, &quot;ZZZZZZZ&quot;));

System.out.println(&quot;My Other property: &quot;

+ (Boolean) obj.Get(&quot;com.acme.MyInterface&quot;, &quot;MyOtherProperty&quot;));

}

public static void main(String[] args) throws DBusException {

new ImportMyObject();

}

}

</code></pre></section></section> </main>

</div>

</div>

<hr/>

<footer>

<div class="container-fluid">

<div class="row-fluid">

<p>© 2025

</div>

</div>

</footer>

</body>