org.freedesktop.dbus.connections

Class AbstractConnection

java.lang.Object

org.freedesktop.dbus.connections.AbstractConnection

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

DBusConnection, DirectConnection

public abstract class AbstractConnection
extends Object
implements Closeable

Handles a connection to DBus.

Field Summary

Fields

Modifier and Type	Field and Description
static String	BUSNAME_REGEX
static String	CONNID_REGEX
static Pattern	DOLLAR_PATTERN
static boolean	FLOAT_SUPPORT
static int	MAX_ARRAY_LENGTH
static int	MAX_NAME_LENGTH
static String	OBJECT_REGEX
static int	TCP_CONNECT_TIMEOUT Connect timeout, used for TCP only

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractConnection(String address, int timeout)

Method Summary

Modifier and Type	Method and Description
void	addFallback(String _objectPrefix, DBusInterface _object) Export an object as a fallback object.
protected abstract void	addGenericSigHandler(DBusMatchRule _rule, DBusSigHandler<DBusSignal> _handler) Adds a DBusMatchRule to with a generic signal handler.
<T extends DBusSignal> void	addSigHandler(Class<T> type, DBusInterface object, DBusSigHandler<T> handler) Add a Signal Handler.
<T extends DBusSignal> void	addSigHandler(Class<T> type, DBusSigHandler<T> handler) Add a Signal Handler.
protected abstract <T extends DBusSignal> void	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 m, 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.
void	changeThreadCount(byte _newPoolSize) Change the number of worker threads to receive method calls and handle signals.
void	close() Disconnect this session (for use in try-with-resources).
void	disconnect() Disconnect from the Bus.
protected void	disconnect(IDisconnectAction _before, IDisconnectAction _after) Special disconnect method which may be used whenever some cleanup before or after disconnection to DBus is required.
void	exportObject(String objectpath, DBusInterface object) Export an object so that its methods can be called on DBus.
BusAddress	getAddress() Returns the address this connection is connected to.
static DBusCallInfo	getCallInfo() Returns a structure with information on the current method call.
static byte	getEndianness() Get current endianness to use.
DBusExecutionException	getError() Return any DBus error which has been received.
String	getExportedObject(DBusInterface _interface)
abstract DBusInterface	getExportedObject(String source, String path)
protected Map<String,ExportedObject>	getExportedObjects()
protected Map<SignalTuple,Queue<DBusSigHandler<DBusSignal>>>	getGenericHandledSignals()
protected Map<SignalTuple,Queue<DBusSigHandler<? extends DBusSignal>>>	getHandledSignals()
protected Map<DBusInterface,RemoteObject>	getImportedObjects()
abstract String	getMachineId() The generated UUID of this machine.
protected ObjectTree	getObjectTree()
protected Map<Long,MethodCall>	getPendingCalls()
protected Queue<Error>	getPendingErrorQueue()
static byte	getSystemEndianness() Get the default system endianness.
protected void	handleException(AbstractConnection dbusConnection, Message methodOrSignal, DBusExecutionException exception)
boolean	isConnected()
protected void	listen() Start reading and sending messages.
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.
protected abstract <T extends DBusSignal> void	removeSigHandler(DBusMatchRule _rule, DBusSigHandler<T> _handler) Remove a match rule with the given DBusSigHandler.
void	sendMessage(Message _message) Send a message or signal to the DBus daemon.
static void	setEndianness(byte _b) Set the endianness to use for all connections.
void	setWeakReferences(boolean _weakreferences) If set to true the bus will not hold a strong reference to exported objects.
void	unExportObject(String _objectpath) Stop Exporting an object

Methods inherited from class java.lang.Object

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

Field Detail

TCP_CONNECT_TIMEOUT

public static final int TCP_CONNECT_TIMEOUT

Connect timeout, used for TCP only

See Also:

Constant Field Values

FLOAT_SUPPORT

public static final boolean FLOAT_SUPPORT

BUSNAME_REGEX

public static final String BUSNAME_REGEX

See Also:

Constant Field Values

CONNID_REGEX

public static final String CONNID_REGEX

See Also:

Constant Field Values

OBJECT_REGEX

public static final String OBJECT_REGEX

See Also:

Constant Field Values

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 Detail

AbstractConnection

protected AbstractConnection(String address,
                             int timeout)
                      throws DBusException

Throws:

DBusException

Method Detail

getExportedObject

public abstract DBusInterface getExportedObject(String source,
                                                String path)
                                         throws DBusException

Throws:

DBusException

removeSigHandler

protected 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.

Parameters:

_rule - rule to remove

_handler - handler to remove

Throws:

DBusException - on error

addSigHandler

protected abstract <T extends DBusSignal> void 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.

Parameters:

_rule - rule to add

_handler - handler to use

Throws:

DBusException - on error

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 void 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

Throws:

DBusException - on error

getMachineId

public abstract String getMachineId()

The generated UUID of this machine.

Returns:

String

listen

protected void listen()

Start reading and sending messages.

changeThreadCount

public void changeThreadCount(byte _newPoolSize)

Change the number of worker threads to receive method calls and handle signals. Default is 4 threads

Parameters:

_newPoolSize - The new number of worker Threads to use.

getExportedObject

public String getExportedObject(DBusInterface _interface)
                         throws DBusException

Throws:

DBusException

setWeakReferences

public void setWeakReferences(boolean _weakreferences)

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,

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.

unExportObject

public void unExportObject(String _objectpath)

Stop Exporting an object

Parameters:

_objectpath - The objectpath to stop exporting.

sendMessage

public void sendMessage(Message _message)

Send a message or signal to the DBus daemon.

Parameters:

_message - message to send

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> void 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.

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> void 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.

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

disconnect

protected void disconnect(IDisconnectAction _before,
                          IDisconnectAction _after)

Special disconnect method which may be used whenever some cleanup before or after disconnection to DBus is required.

Parameters:

_before - action execute before actual disconnect, null if not needed

_after - action execute after disconnect, null if not needed

disconnect

public void disconnect()

Disconnect from the Bus.

close

public void close()
           throws IOException

Disconnect this session (for use in try-with-resources).

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

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 m,
                                         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.

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

parameters - The parameters to call the method with.

Returns:

A handle to the call.

handleException

protected void handleException(AbstractConnection dbusConnection,
                               Message methodOrSignal,
                               DBusExecutionException exception)

queueCallback

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

getExportedObjects

protected Map<String,ExportedObject> getExportedObjects()

getCallInfo

public static DBusCallInfo getCallInfo()

Returns a structure with information on the current method call.

Returns:

the DBusCallInfo for this method call, or null if we are not in a method call.

getError

public DBusExecutionException getError()

Return any DBus error which has been received.

Returns:

A DBusExecutionException, or null if no error is pending.

getAddress

public BusAddress getAddress()

Returns the address this connection is connected to.

Returns:

new BusAddress object

isConnected

public boolean isConnected()

getPendingErrorQueue

protected Queue<Error> getPendingErrorQueue()

getHandledSignals

protected Map<SignalTuple,Queue<DBusSigHandler<? extends DBusSignal>>> getHandledSignals()

getGenericHandledSignals

protected Map<SignalTuple,Queue<DBusSigHandler<DBusSignal>>> getGenericHandledSignals()

getPendingCalls

protected Map<Long,MethodCall> getPendingCalls()

getImportedObjects

protected Map<DBusInterface,RemoteObject> getImportedObjects()

getObjectTree

protected ObjectTree getObjectTree()

setEndianness

public static void setEndianness(byte _b)

Set the endianness to use for all connections. Defaults to the system architectures endianness.

Parameters:

_b - Message.Endian.BIG or Message.Endian.LITTLE

getEndianness

public static byte getEndianness()

Get current endianness to use.

Returns:

Message.Endian.BIG or Message.Endian.LITTLE

getSystemEndianness

public static byte getSystemEndianness()

Get the default system endianness.

Returns:

LITTLE or BIG