/usr/share/doc/libdbus-java/dbus-java/dbus-javase3.html is in libdbus-java-doc 2.8-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | <?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd-->
<html xmlns="http://www.w3.org/1999/xhtml"
>
<head><title>DBusInterface</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)" />
<meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)" />
<!-- xhtml,2,html -->
<meta name="src" content="dbus-java.tex" />
<meta name="date" content="2014-02-01 19:41:00" />
<link rel="stylesheet" type="text/css" href="dbus-java.css" />
</head><body
>
<!--l. 215--><div class="crosslinks"><p class="noindent">[<a
href="dbus-javase13.html" >next</a>] [<a
href="dbus-javase2.html" >prev</a>] [<a
href="dbus-javase2.html#taildbus-javase2.html" >prev-tail</a>] [<a
href="#taildbus-javase3.html">tail</a>] [<a
href="dbus-java.html#dbus-javase9.html" >up</a>] </p></div>
<h3 class="sectionHead"><span class="titlemark">3 </span> <a
id="x13-150003"></a>DBusInterface</h3>
<!--l. 217--><p class="noindent" >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.
</p><!--l. 223--><p class="indent" > For example, if I want to expose methods on the interface <span
class="cmti-12">“org.freedesktop.DBus” </span>I would
define a Java interface in the package <span
class="cmtt-12">org.freedesktop </span>called <span
class="cmtt-12">DBus</span>. This would be in the file
<span
class="cmtt-12">org/freedesktop/DBus.java </span>as normal. Any object wanting to export these methods would
implement <span
class="cmtt-12">org.freedesktop.DBus</span>.
</p><!--l. 229--><p class="indent" > Any interfaces which can be exported over D-Bus must extend
<span
class="cmtt-12">DBusInterface</span><span class="footnote-mark"><a
href="dbus-java14.html#fn7x0"><sup class="textsuperscript">7</sup></a></span><a
id="x13-15001f7"></a> .
A class may implement more than one exportable interface, all public methods declared in an
interface which extend <span
class="cmtt-12">DBusInterface </span>will be exported.
</p><!--l. 234--><p class="indent" > A sample interface definition is given in figure <a
href="#x13-150032">2<!--tex4ht:ref: fig:interface --></a>, and a class which
implements it in figure <a
href="#x13-150043">3<!--tex4ht:ref: fig:class --></a>. More complicated definitions can be seen in the test
classes<span class="footnote-mark"><a
href="dbus-java15.html#fn8x0"><sup class="textsuperscript">8</sup></a></span><a
id="x13-15002f8"></a> .
</p><!--l. 240--><p class="indent" > All method calls by other programs on objects you export over D-Bus are executed in their
own thread.
</p><!--l. 243--><p class="indent" > <span
class="cmtt-12">DBusInterface </span>itself specifies one method <span class="obeylines-h"><span class="verb"><span
class="cmtt-12">boolean</span><span
class="cmtt-12"> isRemote()</span></span></span>. 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.
</p>
<hr class="figure" /><div class="figure"
>
<a
id="x13-150032"></a>
<div class="center"
>
<!--l. 248--><p class="noindent" >
</p>
<div class="verbatim" id="verbatim-8">
package org.freedesktop;
 <br />import org.freedesktop.dbus.UInt32;
 <br />import org.freedesktop.dbus.DBusInterface;
 <br />
 <br />public interface DBus extends DBusInterface
 <br />{
 <br />   public boolean NameHasOwner(String name);
 <br />   public UInt32 RequestName(String name, UInt32 flags);
 <br />}
</div>
<!--l. 259--><p class="nopar" ></p></div>
<br /> <div class="caption"
><span class="id">Figure 2: </span><span
class="content">An interface which exposes two methods</span></div><!--tex4ht:label?: x13-150032 -->
</div><hr class="endfigure" />
<hr class="figure" /><div class="figure"
>
<a
id="x13-150043"></a>
<div class="center"
>
<!--l. 266--><p class="noindent" >
</p>
<div class="verbatim" id="verbatim-9">
package my.real.implementation;
 <br />import org.freedesktop.dbus.DBus;
 <br />import org.freedesktop.dbus.UInt32;
 <br />
 <br />public class DBusImpl implements DBus
 <br />{
 <br />   Vector<String> names;
 <br />   public boolean NameHasOwner(String name)
 <br />   {
 <br />      if (names.contains(name)) return true;
 <br />      else return false;
 <br />   }
 <br />   public UInt32 RequestName(String name, UInt32 flags)
 <br />   {
 <br />      names.add(name);
 <br />      return new UInt32(0);
 <br />   }
 <br />   public boolean isRemote() { return false; }
 <br />}
</div>
<!--l. 287--><p class="nopar" ></p></div>
<br /> <div class="caption"
><span class="id">Figure 3: </span><span
class="content">A class providing a real implementation which can be exported</span></div><!--tex4ht:label?: x13-150043 -->
</div><hr class="endfigure" />
<h4 class="subsectionHead"><span class="titlemark">3.1 </span> <a
id="x13-160003.1"></a>Interface name overriding</h4>
<!--l. 295--><p class="noindent" >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.
</p><!--l. 299--><p class="indent" > To override the Java interface name you should add an annotation to the interface of
<span
class="cmtt-12">DBusInterfaceName</span><span class="footnote-mark"><a
href="dbus-java16.html#fn9x0"><sup class="textsuperscript">9</sup></a></span><a
id="x13-16001f9"></a>
with a value of the desired D-Bus interface name. An example of this can be seen in figure
<a
href="#x13-160024">4<!--tex4ht:ref: fig:interfacename --></a>.
</p>
<hr class="figure" /><div class="figure"
>
<a
id="x13-160024"></a>
<div class="center"
>
<!--l. 306--><p class="noindent" >
</p>
<div class="verbatim" id="verbatim-10">
package my.package;
 <br />import org.freedesktop.dbus.DBusInterface;
 <br />import org.freedesktop.dbus.DBusInterfaceName;
 <br />
 <br />@DBusInterfaceName("my.otherpackage.Remote")
 <br />public interface Remote extends DBusInterface
 <br />{
 <br />   ...
 <br />}
</div>
<!--l. 317--><p class="nopar" ></p></div>
<br /> <div class="caption"
><span class="id">Figure 4: </span><span
class="content">Overloading the name of an interface.</span></div><!--tex4ht:label?: x13-160024 -->
</div><hr class="endfigure" />
<!--l. 323--><p class="indent" > If you have signals which are declared in a renamed interface (see below for signals) then
when adding a signal handler you <span
class="cmti-12">must </span>use an <span
class="cmtt-12">addSigHandler </span>method which takes a
class object corresponding to that signal. If you do not then receiving the signal will
fail.
</p>
<!--l. 328--><div class="crosslinks"><p class="noindent">[<a
href="dbus-javase13.html" >next</a>] [<a
href="dbus-javase2.html" >prev</a>] [<a
href="dbus-javase2.html#taildbus-javase2.html" >prev-tail</a>] [<a
href="dbus-javase3.html" >front</a>] [<a
href="dbus-java.html#dbus-javase9.html" >up</a>] </p></div>
<!--l. 328--><p class="indent" > <a
id="taildbus-javase3.html"></a> </p>
</body></html>
|