Package org.freedesktop.dbus.connections

Class AbstractConnection

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    Direct Known Subclasses:
    DBusConnection, DirectConnection
    public abstract class AbstractConnection
extends java.lang.Object
implements java.io.Closeable
    Handles a connection to DBus.

    • Field Detail

      • FLOAT_SUPPORT

        public static final boolean FLOAT_SUPPORT

      • BUSNAME_REGEX

        public static final java.util.regex.Pattern BUSNAME_REGEX

      • CONNID_REGEX

        public static final java.util.regex.Pattern CONNID_REGEX

      • OBJECT_REGEX_PATTERN

        public static final java.util.regex.Pattern OBJECT_REGEX_PATTERN

      • DOLLAR_PATTERN

        public static final java.util.regex.Pattern DOLLAR_PATTERN

      • TCP_CONNECT_TIMEOUT

        @Deprecated(forRemoval=true,
            since="4.2.2 - 2022-12-23")
public static final int TCP_CONNECT_TIMEOUT
        Deprecated, for removal: This API element is subject to removal in a future version.
        no longer used
        Connect timeout, used for TCP only.
        See Also:
        Constant Field Values

      • TCP_ADDRESS_PROPERTY

        @Deprecated(since="4.2.0 - 2022-08-04",
            forRemoval=true)
public static final java.lang.String TCP_ADDRESS_PROPERTY
        Deprecated, for removal: This API element is subject to removal in a future version.
        is no longer in use
        System property name containing the DBUS TCP SESSION address used by dbus-java DBusDaemon in TCP mode.
        See Also:
        Constant Field Values

      • INFOMAP

        private static final java.util.Map<java.lang.Thread,​DBusCallInfo> INFOMAP

      • endianness

        private static byte endianness
        Lame method to setup endianness used on DBus messages

      • logger

        private final org.slf4j.Logger logger

      • exportedObjects

        private final java.util.Map<java.lang.String,​ExportedObject> exportedObjects

      • pendingErrorQueue

        private final java.util.Queue<Error> pendingErrorQueue

      • pendingCalls

        private final java.util.Map<java.lang.Long,​MethodCall> pendingCalls

      • senderService

        private final java.util.concurrent.ExecutorService senderService

      • weakreferences

        private boolean weakreferences

      • disconnecting

        private volatile boolean disconnecting

    • Method Detail

      • getExportedObject

        public abstract DBusInterface getExportedObject​(java.lang.String _source,
                                                java.lang.String _path)
                                         throws DBusException
        Retrieves an remote object using source and path. Will try to find suitable exported DBusInterface automatically.
        Parameters:
        _source - source
        _path - path
        Returns:
        DBusInterface compatible object
        Throws:
        DBusException

      • getExportedObject

        public abstract <T extends DBusInterface> T getExportedObject​(java.lang.String _source,
                                                              java.lang.String _path,
                                                              java.lang.Class<T> _type)
                                                       throws DBusException
        Retrieves an remote object using source and path. Will use the given type as object class.
        Parameters:
        _source - source
        _path - path
        _type - class of remote object
        Returns:
        DBusInterface compatible object
        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.
        Type Parameters:
        T - signal type
        Parameters:
        _rule - rule to remove
        _handler - handler to remove
        Throws:
        DBusException - on error

      • addSigHandler

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

      • 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 java.lang.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

      • getMachineId

        public abstract java.lang.String getMachineId()
        The generated UUID of this machine.
        Returns:
        String

      • findMatchingTypes

        protected <T extends DBusInterface> java.util.List<java.lang.Class<?>> findMatchingTypes​(java.lang.Class<T> _type,
                                                                                         java.util.List<java.lang.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

      • listen

        protected void listen()
        Start reading and sending messages.

      • changeThreadCount

        @Deprecated(forRemoval=true,
            since="4.1.0")
public void changeThreadCount​(byte _newPoolSize)
        Deprecated, for removal: This API element is subject to removal in a future version.
        does nothing as threading has been changed significantly
        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.

      • 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​(java.lang.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​(java.lang.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​(java.lang.String _objectprefix)
        Remove a fallback
        Parameters:
        _objectprefix - The prefix to remove the fallback for.

      • unExportObject

        public void unExportObject​(java.lang.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​(java.lang.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.
        java.lang.ClassCastException - If type is not a sub-type of DBusSignal.

      • removeSigHandler

        public <T extends DBusSignal> void removeSigHandler​(java.lang.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.
        java.lang.ClassCastException - If type is not a sub-type of DBusSignal.

      • addSigHandler

        public <T extends DBusSignal> java.lang.AutoCloseable addSigHandler​(java.lang.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.
        java.lang.ClassCastException - If type is not a sub-type of DBusSignal.

      • addSigHandler

        public <T extends DBusSignal> java.lang.AutoCloseable addSigHandler​(java.lang.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.
        java.lang.ClassCastException - If type is not a sub-type of DBusSignal.

      • 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

      • internalDisconnect

        protected final void internalDisconnect​(java.io.IOException _connectionError)
        Disconnects the DBus session. This method is private as it should never be overwritten by subclasses, otherwise we have an endless recursion when using disconnect(IDisconnectAction, IDisconnectAction) which then will cause a StackOverflowError.
        Parameters:
        _connectionError - exception caused the disconnection (null if intended disconnect)

      • disconnect

        public void disconnect()
        Disconnect from the Bus.

      • close

        public void close()
           throws java.io.IOException
        Disconnect this session (for use in try-with-resources).
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException

      • callWithCallback

        public <A> void callWithCallback​(DBusInterface _object,
                                 java.lang.String _m,
                                 CallbackHandler<A> _callback,
                                 java.lang.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,
                                         java.lang.String _method,
                                         java.lang.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.

      • createTypesArray

        private static java.lang.Class<?>[] createTypesArray​(java.lang.Object... _parameters)

      • handleMessage

        private void handleMessage​(DBusSignal _signal,
                           boolean _useThreadPool)
        Handle a signal received on DBus.
        Parameters:
        _signal - signal to handle
        _useThreadPool - whether to handle this signal in another thread or handle it byself

      • handleMessage

        private void handleMessage​(Error _err)

      • handleMessage

        private void handleMessage​(MethodReturn _mr)

      • queueCallback

        public void queueCallback​(MethodCall _call,
                          java.lang.reflect.Method _method,
                          CallbackHandler<?> _callback)

      • sendMessageInternally

        private void sendMessageInternally​(Message _message)
        Send a message to DBus.
        Parameters:
        _message - message to send

      • getExportedObjects

        protected java.util.Map<java.lang.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 java.util.Queue<Error> getPendingErrorQueue()

      • getPendingCalls

        protected java.util.Map<java.lang.Long,​MethodCall> getPendingCalls()

      • 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

      • getDisconnectCallback

        public IDisconnectCallback getDisconnectCallback()
        Returns the currently configured disconnect callback.
        Returns:
        callback or null if no callback registered

      • setDisconnectCallback

        public void setDisconnectCallback​(IDisconnectCallback _disconnectCallback)
        Set the callback which will be notified when a disconnection happens. Use null to remove.
        Parameters:
        _disconnectCallback - callback to execute or null to remove

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object