From caf0dac6edc95db8c98a4a104da647060550f66b Mon Sep 17 00:00:00 2001 From: David M Date: Wed, 24 Jan 2024 15:35:49 +0100 Subject: [PATCH] Improved site documentation --- .../{quick-start.md => quick-start.md.vm} | 97 +++++++++++++------ 1 file changed, 68 insertions(+), 29 deletions(-) rename src/site/markdown/{quick-start.md => quick-start.md.vm} (73%) diff --git a/src/site/markdown/quick-start.md b/src/site/markdown/quick-start.md.vm similarity index 73% rename from src/site/markdown/quick-start.md rename to src/site/markdown/quick-start.md.vm index 5152635f..92e4e37c 100644 --- a/src/site/markdown/quick-start.md +++ b/src/site/markdown/quick-start.md.vm @@ -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: +``` + + com.github.hypfvieh + dbus-java-core + ${project.version} + + + + + + + com.github.hypfvieh + dbus-java-transport-jnr-unixsocket + {project.version} + + + + + com.github.hypfvieh + dbus-java-transport-junixsocket + ${project.version} + + + + + com.github.hypfvieh + dbus-java-transport-native-unixsocket + ${project.version} + + + + + com.github.hypfvieh + dbus-java-transport-tcp + ${project.version} + +``` 2. (optional) Add in a logging framework of your choice to see the log messages. DBus-Java uses SLF4J internally for logging. - - - - - - org.apache.logging.log4j - log4j-api - 2.17.2 - - - org.apache.logging.log4j - log4j-slf4j-impl - 2.17.2 - - - - +``` + + + + + org.apache.logging.log4j + log4j-api + 2.17.2 + + + org.apache.logging.log4j + log4j-slf4j-impl + 2.17.2 + + +``` 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 @@ -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 @@ -66,7 +105,7 @@ size of 4. To change those settings, use the `receivingThreadConfig()` method on the connection builders. Example: - +```java DBusConnectionBuilder.forSessionBus() .receivingThreadConfig() .withSignalThreadCount(4) @@ -74,14 +113,14 @@ Example: .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. @@ -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. @@ -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) -> { @@ -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.