Skip to content

Commit

Permalink
Improved site documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@hypfvieh
hypfvieh committed Jan 24, 2024
1 parent 3abf6bb commit caf0dac
Showing 1 changed file with 68 additions and 29 deletions.
97 changes: 68 additions & 29 deletions src/site/markdown/quick-start.md → src/site/markdown/quick-start.md.vm
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,74 @@
# DBus-Java Quickstart

1. Add in dbus-java-core and a apropriate transport to your dependencies. [Documentation on adding to dependencies.](./dependency-info.html)
1. Add in dbus-java-core and a apropriate transport to your dependencies.
For maven this would look like this:
```
<dependency>
<groupId>com.github.hypfvieh</groupId>
<artifactId>dbus-java-core</artifactId>
<version>${project.version}</version>
</dependency>

<!-- Add one of these to support connection to unix sockets -->

<!-- Unixsockets support using JNR -->
<dependency>
<groupId>com.github.hypfvieh</groupId>
<artifactId>dbus-java-transport-jnr-unixsocket</artifactId>
<version>{project.version}</version>
</dependency>

<!-- Alternative unixsocket support using junixsocket -->
<dependency>
<groupId>com.github.hypfvieh</groupId>
<artifactId>dbus-java-transport-junixsocket</artifactId>
<version>${project.version}</version>
</dependency>

<!-- Unixsocket support using native unix socket implementation of Java (since Java 16) -->
<dependency>
<groupId>com.github.hypfvieh</groupId>
<artifactId>dbus-java-transport-native-unixsocket</artifactId>
<version>${project.version}</version>
</dependency>

<!-- Add this if you want support for TCP based DBus connections -->
<dependency>
<groupId>com.github.hypfvieh</groupId>
<artifactId>dbus-java-transport-tcp</artifactId>
<version>${project.version}</version>
</dependency>
```
2. (optional) Add in a logging framework of your choice to see the log messages.
DBus-Java uses SLF4J internally for logging.

<!-- Example of using log4j2 as the logging implementation with Maven -->
<dependencies>
<!-- ... other dependencies here ... -->
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
<version>2.17.2</version>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-slf4j-impl</artifactId>
<version>2.17.2</version>
</dependency>

</dependencies>

```
<!-- Example of using log4j2 as the logging implementation with Maven -->
<dependencies>
<!-- ... other dependencies here ... -->
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
<version>2.17.2</version>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-slf4j-impl</artifactId>
<version>2.17.2</version>
</dependency>
</dependencies>
```
3. Get a connection to the bus. This can be either the SESSION bus or the SYSTEM bus.

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

4. Request bus name if you want a well-known bus name, or begin calling methods on the bus!
You only need to request a bus name if you are expecting other people to talk
to you, so that they know how to talk to you.


## Session vs System bus
#[[##]]# Session vs System bus

By default, there are two buses on the system for different purposes. The
first bus, the session bus, is created on a per-user basis, generally when you
Expand All @@ -48,14 +87,14 @@ be able to request a bus name without updating some permissions. The process
of updating permissions is outside the scope of this document; however, the XML
files that control the permissions can be found in `/etc/dbus-1/system.d`.

## Connection configuration
#[[##]]# Connection configuration

If you do not have any special requirements, usually `DBusConnectionBuilder.forSessionBus().build()` or `DBusConnectionBuilder.forSystemBus().build()` is all you need to do.

In some cases you may have to change the default settings. This can be done through the appropriate builder options.
The Builder allows you to change most settings used to connect and to communicate with DBus.

### Changing thread-pool settings
#[[##]]## Changing thread-pool settings
For receiving data from DBus dbus-java uses several thread pools. This is required due to the different purposes of
received messages. There are signals, methods and method returns.
To prevent one message processing blocking other message processing, each of those message types are handled in different
Expand All @@ -66,22 +105,22 @@ size of 4.

To change those settings, use the `receivingThreadConfig()` method on the connection builders.
Example:

```java
DBusConnectionBuilder.forSessionBus()
.receivingThreadConfig()
.withSignalThreadCount(4)
.withMethodThreadCount(2)
.connectionConfig()
.withShared(false)
.build()

```
In the example above, the signal thread pool will be increased to 4 threads, the method thread pool to 2 threads.
Calling `connectionConfig()` will return the used connection builder (`DBusConnectionBuilder` in this case) to allow configure further settings on the connection before creating the actual connection.
If you do not want to do additional configuration you can also call `.buildConnection()` on the `ReceivingServiceConfigBuilder` to create the connection directly.

With this pattern you can also change the thread priority for each pool.

### IMPORTANT NOTE ABOUT SIGNAL THREADPOOL
#[[##]]## IMPORTANT NOTE ABOUT SIGNAL THREADPOOL
Increasing the signal thread pool will improve the speed the signals are handled.
Nevertheless increasing the thread pool may also cause the signals to be handled in any order, not necessarily in the order
they were sent/received.
Expand All @@ -90,7 +129,7 @@ This is caused by concurrency of the threads in the pool. If you receive e.g. 10

If signal order is important for your use case, DO NOT INCREMENT the signal thread pool size!

### Using retry handler
#[[##]]## Using retry handler
In some very rare cases (this has only been reported for some JDK versions of some vendors used on ARM 32-bit platform, see [#172](https://github.com/hypfvieh/dbus-java/issues/172)), the thread pool executors may throw unexpected NullPointerExceptions.

In such cases the default behavior is to retry adding the message callback runnable to the executor up to 10 times.
Expand All @@ -108,7 +147,7 @@ After that hard limit is reached, error will be logged and runnable will be igno
You can also set the configured retry handler to `null` which will cause the `ReceivingService` log an error (including exception) and ignoring the failed runnable.

Retry handler can be installed like this:

```java
DBusConnectionBuilder.forSessionBus()
.receivingThreadConfig()
.withRetryHandler((t, ex) -> {
Expand All @@ -118,10 +157,10 @@ Retry handler can be installed like this:
.connectionConfig()
.withShared(false)
.build()

### IMPORTANT NOTE USING RETRY HANDLER
```
#[[##]]## IMPORTANT NOTE USING RETRY HANDLER
The retry handler is executed synchronously (in the thread where the connection receives data from the bus).
That means whatever you do in your retry handler, either do it quick or delegate the actual work to your own thread pool/thread and do it asynchronously. Doing too much work in the retry handler will cause delays in other received messages and may cause DBus to disconnect the session.

## Examples
#[[##]]# Examples
For example code checkout dbus-java-examples module of this project.

0 comments on commit caf0dac

Please sign in to comment.