Package org.freedesktop.dbus.connections.impl

Class DBusConnection

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    public final class DBusConnection
extends AbstractConnection
    Handles a connection to DBus.

    This is a Singleton class, only 1 connection to the SYSTEM or SESSION busses can be made. Repeated calls to getConnection will return the same reference.

    Signal Handlers and method calls from remote objects are run in their own threads, you MUST handle the concurrency issues.

    • Field Detail

      • CONNECTIONS

        static final java.util.concurrent.ConcurrentMap<java.lang.String,​DBusConnection> CONNECTIONS

      • dbusMachineIdFile

        private static java.lang.String dbusMachineIdFile

      • logger

        private final org.slf4j.Logger logger

      • busnames

        private final java.util.List<java.lang.String> busnames

      • machineId

        private final java.lang.String machineId

      • dbus

        private DBus dbus

      • concurrentConnections

        final java.util.concurrent.atomic.AtomicInteger concurrentConnections
        Count how many 'connections' we manage internally. This is required because a DBusConnection to the same address will always return the same object and the 'real' disconnection should only occur when there is no second/third/whatever connection is left.

      • shared

        private final boolean shared
        Whether this connection is used in shared mode.

    • Method Detail

      • getConnection

        @Deprecated(since="4.1.0",
            forRemoval=true)
public static DBusConnection getConnection​(java.lang.String _address)
                                    throws DBusException
        Deprecated, for removal: This API element is subject to removal in a future version.
        use DBusConnectionBuilder
        Connect to the BUS. If a connection already exists to the specified Bus, a reference to it is returned. Will always register our own session to Dbus.
        Parameters:
        _address - The address of the bus to connect to
        Returns:
        DBusConnection
        Throws:
        DBusException - If there is a problem connecting to the Bus.

      • getConnection

        @Deprecated(since="4.1.0",
            forRemoval=true)
public static DBusConnection getConnection​(java.lang.String _address,
                                           boolean _registerSelf,
                                           boolean _shared)
                                    throws DBusException
        Deprecated, for removal: This API element is subject to removal in a future version.
        use DBusConnectionBuilder
        Connect to the BUS. If a connection already exists to the specified Bus and the shared-flag is true, a reference is returned. Will register our own session to DBus if registerSelf is true (default). A new connection is created every time if shared-flag is false.
        Parameters:
        _address - The address of the bus to connect to
        _registerSelf - register own session in dbus
        _shared - use a shared connections
        Returns:
        DBusConnection
        Throws:
        DBusException - If there is a problem connecting to the Bus.

      • getConnection

        @Deprecated(since="4.1.0",
            forRemoval=true)
public static DBusConnection getConnection​(java.lang.String _address,
                                           boolean _registerSelf,
                                           boolean _shared,
                                           int _timeout)
                                    throws DBusException
        Deprecated, for removal: This API element is subject to removal in a future version.
        use DBusConnectionBuilder
        Connect to the BUS. If a connection already exists to the specified Bus and the shared-flag is true, a reference is returned. Will register our own session to DBus if registerSelf is true (default). A new connection is created every time if shared-flag is false.
        Parameters:
        _address - The address of the bus to connect to
        _registerSelf - register own session in dbus
        _shared - use a shared connections
        _timeout - connect timeout if this is a TCP socket, 0 will block forever, if this is not a TCP socket this value is ignored
        Returns:
        DBusConnection
        Throws:
        DBusException - If there is a problem connecting to the Bus.

      • getConnection

        @Deprecated(since="4.1.0",
            forRemoval=true)
public static DBusConnection getConnection​(DBusConnection.DBusBusType _bustype)
                                    throws DBusException
        Deprecated, for removal: This API element is subject to removal in a future version.
        use DBusConnectionBuilder
        Connect to DBus. If a connection already exists to the specified Bus, a reference to it is returned.
        Parameters:
        _bustype - The Bus to connect to.
        Returns:
        DBusConnection
        Throws:
        DBusException - If there is a problem connecting to the Bus.

      • newConnection

        @Deprecated(since="4.1.0",
            forRemoval=true)
public static DBusConnection newConnection​(DBusConnection.DBusBusType _bustype)
                                    throws DBusException
        Deprecated, for removal: This API element is subject to removal in a future version.
        use DBusConnectionBuilder
        Connect to DBus using a new connection even if there is already a connection established.
        Parameters:
        _bustype - The Bus to connect to.
        Returns:
        DBusConnection
        Throws:
        DBusException - If there is a problem connecting to the Bus.

      • getConnection

        @Deprecated(since="4.1.0",
            forRemoval=true)
public static DBusConnection getConnection​(DBusConnection.DBusBusType _bustype,
                                           boolean _shared,
                                           int _timeout)
                                    throws DBusException
        Deprecated, for removal: This API element is subject to removal in a future version.
        use DBusConnectionBuilder
        Connect to the BUS. If a connection to the specified Bus already exists and shared-flag is true, a reference to it is returned. Otherwise a new connection will be created.
        Parameters:
        _bustype - The Bus to connect to.
        _shared - use shared connection
        _timeout - connect timeout if this is a TCP socket, 0 will block forever, if this is not a TCP socket this value is ignored
        Returns:
        DBusConnection
        Throws:
        DBusException - If there is a problem connecting to the Bus.

      • getConcurrentConnections

        private java.util.concurrent.atomic.AtomicInteger getConcurrentConnections()

      • setDbusMachineIdFile

        @Deprecated(since="4.1.0",
            forRemoval=true)
public static void setDbusMachineIdFile​(java.lang.String _dbusMachineIdFile)
        Deprecated, for removal: This API element is subject to removal in a future version.
        no longer required when DBusConnectionBuilder is used
        Set a specific machine-id file path to read the machine ID from. The system variable DBUS_MACHINE_ID_LOCATION will take precedence over this.
        Parameters:
        _dbusMachineIdFile - file containing DBus machine ID.

      • connect

        void connect​(boolean _registerSelf)
      throws DBusException
        Connect to bus and register if asked. Should only be called by Builder.
        Parameters:
        _registerSelf - true to register
        Throws:
        DBusException - if registering fails

      • dynamicProxy

        public <T extends DBusInterface> T dynamicProxy​(java.lang.String _source,
                                                java.lang.String _path,
                                                java.lang.Class<T> _type)
                                         throws DBusException
        Tries to resolve a proxy to a remote object. If a type class is given, it tries to convert the object using that class. If null is given as type, it tries to find a proper interface for this object.
        Type Parameters:
        T - object type (DBusInterface compatible)
        Parameters:
        _source - source
        _path - path
        _type - class of object type
        Returns:
        DBusInterface compatible object
        Throws:
        DBusException - when something goes wrong

      • releaseBusName

        public void releaseBusName​(java.lang.String _busname)
                    throws DBusException
        Release a bus name. Releases the name so that other people can use it
        Parameters:
        _busname - The name to release. MUST be in dot-notation like "org.freedesktop.local"
        Throws:
        DBusException - If the busname is incorrectly formatted.

      • requestBusName

        public void requestBusName​(java.lang.String _busname)
                    throws DBusException
        Request a bus name. Request the well known name that this should respond to on the Bus.
        Parameters:
        _busname - The name to respond to. MUST be in dot-notation like "org.freedesktop.local"
        Throws:
        DBusException - If the register name failed, or our name already exists on the bus. or if busname is incorrectly formatted.

      • getUniqueName

        public java.lang.String getUniqueName()
        Returns the unique name of this connection.
        Returns:
        unique name

      • getNames

        public java.lang.String[] getNames()
        Returns all the names owned by this connection.
        Returns:
        connection names

      • getPeerRemoteObject

        public <I extends DBusInterface> I getPeerRemoteObject​(java.lang.String _busname,
                                                       java.lang.String _objectpath,
                                                       java.lang.Class<I> _type)
                                                throws DBusException
        Throws:
        DBusException

      • getPeerRemoteObject

        public DBusInterface getPeerRemoteObject​(java.lang.String _busname,
                                         java.lang.String _objectpath)
                                  throws DBusException
        Return a reference to a remote object. This method will resolve the well known name (if given) to a unique bus name when you call it. This means that if a well known name is released by one process and acquired by another calls to objects gained from this method will continue to operate on the original process. This method will use bus introspection to determine the interfaces on a remote object and so may block and may fail. The resulting proxy object will, however, be castable to any interface it implements. It will also autostart the process if applicable. Also note that the resulting proxy may fail to execute the correct method with overloaded methods and that complex types may fail in interesting ways. Basically, if something odd happens, try specifying the interface explicitly.
        Parameters:
        _busname - The bus name to connect to. Usually a well known bus name in dot-notation (such as "org.freedesktop.local") or may be a DBus address such as ":1-16".
        _objectpath - The path on which the process is exporting the object.$
        Returns:
        A reference to a remote object.
        Throws:
        java.lang.ClassCastException - If type is not a sub-type of DBusInterface
        DBusException - If busname or objectpath are incorrectly formatted.

      • getRemoteObject

        public DBusInterface getRemoteObject​(java.lang.String _busname,
                                     java.lang.String _objectpath)
                              throws DBusException
        Return a reference to a remote object. This method will always refer to the well known name (if given) rather than resolving it to a unique bus name. In particular this means that if a process providing the well known name disappears and is taken over by another process proxy objects gained by this method will make calls on the new proccess. This method will use bus introspection to determine the interfaces on a remote object and so may block and may fail. The resulting proxy object will, however, be castable to any interface it implements. It will also autostart the process if applicable. Also note that the resulting proxy may fail to execute the correct method with overloaded methods and that complex types may fail in interesting ways. Basically, if something odd happens, try specifying the interface explicitly.
        Parameters:
        _busname - The bus name to connect to. Usually a well known bus name name in dot-notation (such as "org.freedesktop.local") or may be a DBus address such as ":1-16".
        _objectpath - The path on which the process is exporting the object.
        Returns:
        A reference to a remote object.
        Throws:
        java.lang.ClassCastException - If type is not a sub-type of DBusInterface
        DBusException - If busname or objectpath are incorrectly formatted.

      • getPeerRemoteObject

        public <I extends DBusInterface> I getPeerRemoteObject​(java.lang.String _busname,
                                                       java.lang.String _objectpath,
                                                       java.lang.Class<I> _type,
                                                       boolean _autostart)
                                                throws DBusException
        Return a reference to a remote object. This method will resolve the well known name (if given) to a unique bus name when you call it. This means that if a well known name is released by one process and acquired by another calls to objects gained from this method will continue to operate on the original process.
        Type Parameters:
        I - class extending DBusInterface
        Parameters:
        _busname - The bus name to connect to. Usually a well known bus name in dot-notation (such as "org.freedesktop.local") or may be a DBus address such as ":1-16".
        _objectpath - The path on which the process is exporting the object.$
        _type - The interface they are exporting it on. This type must have the same full class name and exposed method signatures as the interface the remote object is exporting.
        _autostart - Disable/Enable auto-starting of services in response to calls on this object. Default is enabled; when calling a method with auto-start enabled, if the destination is a well-known name and is not owned the bus will attempt to start a process to take the name. When disabled an error is returned immediately.
        Returns:
        A reference to a remote object.
        Throws:
        java.lang.ClassCastException - If type is not a sub-type of DBusInterface
        DBusException - If busname or objectpath are incorrectly formatted or type is not in a package.

      • getRemoteObject

        public <I extends DBusInterface> I getRemoteObject​(java.lang.String _busname,
                                                   java.lang.String _objectpath,
                                                   java.lang.Class<I> _type)
                                            throws DBusException
        Return a reference to a remote object. This method will always refer to the well known name (if given) rather than resolving it to a unique bus name. In particular this means that if a process providing the well known name disappears and is taken over by another process proxy objects gained by this method will make calls on the new proccess.
        Type Parameters:
        I - class extending DBusInterface
        Parameters:
        _busname - The bus name to connect to. Usually a well known bus name name in dot-notation (such as "org.freedesktop.local") or may be a DBus address such as ":1-16".
        _objectpath - The path on which the process is exporting the object.
        _type - The interface they are exporting it on. This type must have the same full class name and exposed method signatures as the interface the remote object is exporting.
        Returns:
        A reference to a remote object.
        Throws:
        java.lang.ClassCastException - If type is not a sub-type of DBusInterface
        DBusException - If busname or objectpath are incorrectly formatted or type is not in a package.

      • getRemoteObject

        public <I extends DBusInterface> I getRemoteObject​(java.lang.String _busname,
                                                   java.lang.String _objectpath,
                                                   java.lang.Class<I> _type,
                                                   boolean _autostart)
                                            throws DBusException
        Return a reference to a remote object. This method will always refer to the well known name (if given) rather than resolving it to a unique bus name. In particular this means that if a process providing the well known name disappears and is taken over by another process proxy objects gained by this method will make calls on the new proccess.
        Type Parameters:
        I - class extending DBusInterface
        Parameters:
        _busname - The bus name to connect to. Usually a well known bus name name in dot-notation (such as "org.freedesktop.local") or may be a DBus address such as ":1-16".
        _objectpath - The path on which the process is exporting the object.
        _type - The interface they are exporting it on. This type must have the same full class name and exposed method signatures as the interface the remote object is exporting.
        _autostart - Disable/Enable auto-starting of services in response to calls on this object. Default is enabled; when calling a method with auto-start enabled, if the destination is a well-known name and is not owned the bus will attempt to start a process to take the name. When disabled an error is returned immediately.
        Returns:
        A reference to a remote object.
        Throws:
        java.lang.ClassCastException - If type is not a sub-type of DBusInterface
        DBusException - If busname or objectpath are incorrectly formatted or type is not in a package.

      • removeSigHandler

        public <T extends DBusSignal> void removeSigHandler​(java.lang.Class<T> _type,
                                                    java.lang.String _source,
                                                    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.
        _source - The source of 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.

      • removeSigHandler

        public <T extends DBusSignal> void removeSigHandler​(java.lang.Class<T> _type,
                                                    java.lang.String _source,
                                                    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.
        _source - The source of the signal.
        _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,
                                                                    java.lang.String _source,
                                                                    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 source.
        Type Parameters:
        T - class extending DBusSignal
        Parameters:
        _type - The signal to watch for.
        _source - The process which will send the signal. This MUST be a unique bus name and not a well known name.
        _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,
                                                                    java.lang.String _source,
                                                                    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, source and object.
        Type Parameters:
        T - class extending DBusSignal
        Parameters:
        _type - The signal to watch for.
        _source - The process which will send the signal. This MUST be a unique bus name and not a well known name.
        _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.

      • validateSignal

        private <T extends DBusSignal> void validateSignal​(java.lang.Class<T> _type,
                                                   java.lang.String _source)
                                            throws DBusException
        Checks if given type is a DBusSignal and matches the required rules.
        Type Parameters:
        T - type of class
        Parameters:
        _type - class
        _source -
        Throws:
        DBusException - when validation fails

      • addSigHandler

        public <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.
        Specified by:
        addSigHandler in class AbstractConnection
        Type Parameters:
        T - signal type
        Parameters:
        _rule - rule to add
        _handler - handler to use
        Returns:
        closeable that removes signal handler
        Throws:
        DBusException - on error

      • disconnect

        public void disconnect()
        Disconnect from the Bus. If this is a shared connection, it only disconnects when the last reference to the bus has called disconnect. If this is not a shared connection, disconnect will close the connection instantly.
        Overrides:
        disconnect in class AbstractConnection

      • close

        public void close()
           throws java.io.IOException
        Same as disconnect.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class AbstractConnection
        Throws:
        java.io.IOException

      • addGenericSigHandler

        public java.lang.AutoCloseable addGenericSigHandler​(DBusMatchRule _rule,
                                                    DBusSigHandler<DBusSignal> _handler)
                                             throws DBusException
        Description copied from class: AbstractConnection
        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.
        Specified by:
        addGenericSigHandler in class AbstractConnection
        Parameters:
        _rule - rule to add
        _handler - handler to use
        Returns:
        closeable that removes signal handler
        Throws:
        DBusException - on error