Class AbstractConnection

java.lang.Object

org.freedesktop.dbus.connections.base.AbstractConnectionBase

org.freedesktop.dbus.connections.base.ConnectionMethodInvocation

org.freedesktop.dbus.connections.base.DBusBoundPropertyHandler

org.freedesktop.dbus.connections.base.ConnectionMessageHandler

org.freedesktop.dbus.connections.AbstractConnection

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

DBusConnection, DirectConnection

public abstract non-sealed class AbstractConnection
extends ConnectionMessageHandler

Handles a connection to DBus.

Field Summary

Fields

Modifier and Type	Field	Description
static final Pattern	DOLLAR_PATTERN
static final boolean	FLOAT_SUPPORT
static final int	MAX_ARRAY_LENGTH
static final int	MAX_NAME_LENGTH

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractConnection(ConnectionConfig _conCfg, TransportConfig _transportConfig, ReceivingServiceConfig _rsCfg)

Method Summary

Modifier and Type	Method	Description
void	addFallback(String _objectPrefix, DBusInterface _object)	Export an object as a fallback object.
protected abstract AutoCloseable	addGenericSigHandler(DBusMatchRule _rule, DBusSigHandler<DBusSignal> _handler)	Adds a DBusMatchRule to with a generic signal handler.
<T extends DBusSignal> AutoCloseable	addSigHandler(Class<T> _type, DBusInterface _object, DBusSigHandler<T> _handler)	Add a Signal Handler.
<T extends DBusSignal> AutoCloseable	addSigHandler(Class<T> _type, DBusSigHandler<T> _handler)	Add a Signal Handler.
abstract <T extends DBusSignal> AutoCloseable	addSigHandler(DBusMatchRule _rule, DBusSigHandler<T> _handler)	Add a signal handler with the given DBusMatchRule to DBus.
protected <T extends DBusSignal> void	addSigHandlerWithoutMatch(Class<? extends DBusSignal> _signal, DBusSigHandler<T> _handler)
DBusAsyncReply<?>	callMethodAsync(DBusInterface _object, String _method, Object... _parameters)	Call a method asynchronously and get a handle with which to get the reply.
<A> void	callWithCallback(DBusInterface _object, String _m, CallbackHandler<A> _callback, Object... _parameters)	Call a method asynchronously and set a callback.
protected IncomingMessageThread	createReaderThread(BusAddress _busAddress)	Create the read thread for reading incoming messages.
void	exportObject(String _objectPath, DBusInterface _object)	Export an object so that its methods can be called on DBus.
void	exportObject(DBusInterface _object)	Export an object so that its methods can be called on DBus.
protected <T extends DBusInterface> List<Class<?>>	findMatchingTypes(Class<T> _type, List<String> _ifaces)	If given type is null, will try to find suitable types by examining the given ifaces.
boolean	isFileDescriptorSupported()
void	queueCallback(MethodCall _call, Method _method, CallbackHandler<?> _callback)
void	removeFallback(String _objectprefix)	Remove a fallback
protected abstract void	removeGenericSigHandler(DBusMatchRule _rule, DBusSigHandler<DBusSignal> _handler)	Remove a generic signal handler with the given DBusMatchRule.
<T extends DBusSignal> void	removeSigHandler(Class<T> _type, DBusInterface _object, DBusSigHandler<T> _handler)	Remove a Signal Handler.
<T extends DBusSignal> void	removeSigHandler(Class<T> _type, DBusSigHandler<T> _handler)	Remove a Signal Handler.
abstract <T extends DBusSignal> void	removeSigHandler(DBusMatchRule _rule, DBusSigHandler<T> _handler)	Remove a match rule with the given DBusSigHandler.
void	setWeakReferences(boolean _weakreferences)	Deprecated, for removal: This API element is subject to removal in a future version. should be set during construction time (using the builder), will be removed in future

Methods inherited from class ConnectionMessageHandler

handleException, handleMessage, handleMessage

Methods inherited from class DBusBoundPropertyHandler

handleDBusBoundProperties, handleGet, handleGetAll, handleSet

Methods inherited from class ConnectionMethodInvocation

invokedMethodReply, invokeMethod, invokeMethodAndReply, queueInvokeMethod, setupAndInvoke

Methods inherited from class AbstractConnectionBase

close, connect, disconnect, disconnect, doWithExportedObjects, doWithExportedObjectsAndReturn, getAddress, getBusAddress, getCallbackManager, getCallInfo, getConnectionConfig, getDisconnectCallback, getError, getExportedObject, getExportedObject, getExportedObject, getFallbackContainer, getGenericHandledSignals, getHandledSignals, getImportedObjects, getInfoMap, getLogger, getMachineId, getMessageFactory, getObjectTree, getPendingCalls, getPendingErrorQueue, getReceivingService, getTransport, getTransportConfig, internalDisconnect, isConnected, listen, rejectUnknownProperty, sendMessage, setDisconnectCallback, toString, unExportObject

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

FLOAT_SUPPORT

public static final boolean FLOAT_SUPPORT

DOLLAR_PATTERN

public static final Pattern DOLLAR_PATTERN

MAX_ARRAY_LENGTH

public static final int MAX_ARRAY_LENGTH

See Also:

• Constant Field Values

MAX_NAME_LENGTH

public static final int MAX_NAME_LENGTH

See Also:

• Constant Field Values

Constructor Details

AbstractConnection

protected AbstractConnection(ConnectionConfig _conCfg,
 TransportConfig _transportConfig,
 ReceivingServiceConfig _rsCfg)
                      throws DBusException

Throws:

DBusException

Method Details

createReaderThread

protected IncomingMessageThread createReaderThread(BusAddress _busAddress)

Description copied from class: AbstractConnectionBase

Create the read thread for reading incoming messages.

Specified by:

createReaderThread in class AbstractConnectionBase

Parameters:

_busAddress - current bus address

Returns:

IncomingMessageThread, never null

removeSigHandler

public abstract <T extends DBusSignal> void removeSigHandler(DBusMatchRule _rule,
 DBusSigHandler<T> _handler)
                                                      throws DBusException

Remove a match rule with the given DBusSigHandler. The rule will only be removed from DBus if no other additional handlers are registered to the same rule.

Type Parameters:

T - signal type

Parameters:

_rule - rule to remove

_handler - handler to remove

Throws:

DBusException - on error

API Note:

public since 5.2.0 - 2025-05-03

addSigHandler

public abstract <T extends DBusSignal>
AutoCloseable addSigHandler(DBusMatchRule _rule,
 DBusSigHandler<T> _handler)
                     throws DBusException

Add a signal handler with the given DBusMatchRule to DBus. The rule will be added to DBus if it was not added before. If the rule was already added, the signal handler is added to the internal map receiving the same signal as the first (and additional) handlers for this rule.

Type Parameters:

T - signal type

Parameters:

_rule - rule to add

_handler - handler to use

Returns:

closeable that removes signal handler

Throws:

DBusException - on error

API Note:

public since 5.2.0 - 2025-05-03

removeGenericSigHandler

protected abstract void removeGenericSigHandler(DBusMatchRule _rule,
 DBusSigHandler<DBusSignal> _handler)
                                         throws DBusException

Remove a generic signal handler with the given DBusMatchRule. The rule will only be removed from DBus if no other additional handlers are registered to the same rule.

Parameters:

_rule - rule to remove

_handler - handler to remove

Throws:

DBusException - on error

addGenericSigHandler

protected abstract AutoCloseable addGenericSigHandler(DBusMatchRule _rule,
 DBusSigHandler<DBusSignal> _handler)
                                               throws DBusException

Adds a DBusMatchRule to with a generic signal handler. Generic signal handlers allow receiving different signals with the same handler. If the rule was already added, the signal handler is added to the internal map receiving the same signal as the first (and additional) handlers for this rule.

Parameters:

_rule - rule to add

_handler - handler to use

Returns:

closeable that removes signal handler

Throws:

DBusException - on error

findMatchingTypes

protected <T extends DBusInterface> List<Class<?>> findMatchingTypes(Class<T> _type,
 List<String> _ifaces)

If given type is null, will try to find suitable types by examining the given ifaces. If a non-null type is given, returns the given type.

Type Parameters:

T - any DBusInterface compatible object

Parameters:

_type - type or null

_ifaces - interfaces to examining when type is null

Returns:

List

setWeakReferences

@Deprecated(since="5.1.0 - 2024-07-12",
            forRemoval=true)
public void setWeakReferences(boolean _weakreferences)

Deprecated, for removal: This API element is subject to removal in a future version.

should be set during construction time (using the builder), will be removed in future

If set to true the bus will not hold a strong reference to exported objects. If they go out of scope they will automatically be unexported from the bus. The default is to hold a strong reference, which means objects must be explicitly unexported before they will be garbage collected.

Parameters:

_weakreferences - reference

exportObject

public void exportObject(String _objectPath,
 DBusInterface _object)
                  throws DBusException

Export an object so that its methods can be called on DBus.

Parameters:

_objectPath - The path to the object we are exposing. MUST be in slash-notation, like "/org/freedesktop/Local", and SHOULD end with a capitalised term. Only one object may be exposed on each path at any one time, but an object may be exposed on several paths at once.

_object - The object to export.

Throws:

DBusException - If the objectpath is already exporting an object. or if objectpath is incorrectly formatted,

exportObject

public void exportObject(DBusInterface _object)
                  throws DBusException

Export an object so that its methods can be called on DBus. The path to the object will be taken from the DBusInterface.getObjectPath() method, make sure it is implemented and returns immutable value. If you want export object with multiple paths, please use exportObject(String, DBusInterface).

Parameters:

_object - The object to export.

Throws:

DBusException - If the object path is already exporting an object or if object path is incorrectly formatted.

addFallback

public void addFallback(String _objectPrefix,
 DBusInterface _object)
                 throws DBusException

Export an object as a fallback object. This object will have it's methods invoked for all paths starting with this object path.

Parameters:

_objectPrefix - The path below which the fallback handles calls. MUST be in slash-notation, like "/org/freedesktop/Local",

_object - The object to export.

Throws:

DBusException - If the objectpath is incorrectly formatted,

removeFallback

public void removeFallback(String _objectprefix)

Remove a fallback

Parameters:

_objectprefix - The prefix to remove the fallback for.

removeSigHandler

public <T extends DBusSignal> void removeSigHandler(Class<T> _type,
 DBusSigHandler<T> _handler)
                                             throws DBusException

Remove a Signal Handler. Stops listening for this signal.

Type Parameters:

T - class extending DBusSignal

Parameters:

_type - The signal to watch for.

_handler - the handler

Throws:

DBusException - If listening for the signal on the bus failed.

ClassCastException - If type is not a sub-type of DBusSignal.

removeSigHandler

public <T extends DBusSignal> void removeSigHandler(Class<T> _type,
 DBusInterface _object,
 DBusSigHandler<T> _handler)
                                             throws DBusException

Remove a Signal Handler. Stops listening for this signal.

Type Parameters:

T - class extending DBusSignal

Parameters:

_type - The signal to watch for.

_object - The object emitting the signal.

_handler - the handler

Throws:

DBusException - If listening for the signal on the bus failed.

ClassCastException - If type is not a sub-type of DBusSignal.

addSigHandler

public <T extends DBusSignal> AutoCloseable addSigHandler(Class<T> _type,
 DBusSigHandler<T> _handler)
                                                   throws DBusException

Add a Signal Handler. Adds a signal handler to call when a signal is received which matches the specified type and name.

Type Parameters:

T - class extending DBusSignal

Parameters:

_type - The signal to watch for.

_handler - The handler to call when a signal is received.

Returns:

closeable that removes signal handler

Throws:

DBusException - If listening for the signal on the bus failed.

ClassCastException - If type is not a sub-type of DBusSignal.

addSigHandler

public <T extends DBusSignal> AutoCloseable addSigHandler(Class<T> _type,
 DBusInterface _object,
 DBusSigHandler<T> _handler)
                                                   throws DBusException

Add a Signal Handler. Adds a signal handler to call when a signal is received which matches the specified type, name and object.

Type Parameters:

T - class extending DBusSignal

Parameters:

_type - The signal to watch for.

_object - The object from which the signal will be emitted

_handler - The handler to call when a signal is received.

Returns:

closeable that removes signal handler

Throws:

DBusException - If listening for the signal on the bus failed.

ClassCastException - If type is not a sub-type of DBusSignal.

addSigHandlerWithoutMatch

protected <T extends DBusSignal> void addSigHandlerWithoutMatch(Class<? extends DBusSignal> _signal,
 DBusSigHandler<T> _handler)
                                                         throws DBusException

Throws:

DBusException

callWithCallback

public <A> void callWithCallback(DBusInterface _object,
 String _m,
 CallbackHandler<A> _callback,
 Object... _parameters)

Call a method asynchronously and set a callback. This handler will be called in a separate thread.

Type Parameters:

A - whatever

Parameters:

_object - The remote object on which to call the method.

_m - The name of the method on the interface to call.

_callback - The callback handler.

_parameters - The parameters to call the method with.

callMethodAsync

public DBusAsyncReply<?> callMethodAsync(DBusInterface _object,
 String _method,
 Object... _parameters)

Call a method asynchronously and get a handle with which to get the reply.

Parameters:

_object - The remote object on which to call the method.

_method - The name of the method on the interface to call.

_parameters - The parameters to call the method with.

Returns:

A handle to the call.

queueCallback

public void queueCallback(MethodCall _call,
 Method _method,
 CallbackHandler<?> _callback)

isFileDescriptorSupported

public boolean isFileDescriptorSupported()